glossary-values

Use this resource to retrieve a list of glossary values that meet specified criteria.

Method summary

HTTP Method Path Description
GET /bwl/glossary-values Returns a list of glossary values that match specified criteria. The criteria might consist of a category, or a category plus name, or neither. If neither name nor category is specified, all visible glossary values are returned.

GET /glossary-values

Description
Use this method to return a list of glossary values that meet specified criteria.
Resource information
Requirements Description
Response format JSON
Requires authentication Yes
Supports OAuth 2 client credentials Yes using a User Service ID containing Artifact Reporting Category
Parameters
Name Location Description Required Type
X-IBM-API-Version Header The version of this API. If you are programming against the API, you MUST include the version. If omitted, the latest version of the API is used, which might be incompatible with prior versions.

The current value is 1.0.0.

 No String
X-On-Behalf-Of Header The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified parent space, if any. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
category Query If specified, only values in this category are returned. A category could consist of one of the predefined categories listed, or it could be the name of a custom text property that is configured on the account.
Possible values are
  • participant-businessowner-expert
  • externalparticipant
  • system
  • supplier-customer
  • input-output
  • problem
  • kpi
  • goal
  • businessunit
  • tag
 No String
name Query If specified, only values with this exact name are returned. If a name is specified, a category must be provided. No String
active-state Query If specified, only values in the specified state are returned.
Possible values are
  • active
  • inactive

If this parameter is specified, a category must be provided. Inactive state is not supported for the business unit or tag categories.

 No String
Response
Example 1 input
LIST all glossary values in the KPI category, in an account that you have access to:
  • Using User Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" 
 "https://your_server_url/bwl/glossary-values?category=kpi"
  • Using Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token" 
"https://your_server_url/bwl/glossary-values?category=kpi"
  • Using Service ID OAuth 2 client credentials with user context:
    curl -i -H "Authorization: Bearer access_token" 
    -H "X-On-Behalf-Of:user_name@domain.com" "https://your_server_url/bwl/glossary-values?category=kpi"
Example 1 output
LIST all glossary values in the KPI category, in an account that you have access to:
HTTP/1.1 200 OK 
[  
   {  
      "id" : "2500e2",
      "name" : "myKPI2",
      "category" : "kpi",
      "visibility" : "always-visible",
      "type" : "complex",
      "content" : [ {
         "id" : "30051d71e",
         "name" : "Input4"
     } ],
      "enumerated" : false,
      "added-by-user" : {
         "full-name" : "JC Denton",
         "email-address" : "xjcdenton@your_org.com"
      },
      "added-by-date" : "2018-09-04T23:39:30.149+0000",
      "url" : "https://your_server_url/scr/glossary/2500e2"
   },
   {   
      "id" : "2500d8",
      "name" : "myKPI1",
      "category" : "kpi",
      "visibility" : "always-visible",
      "added-by-user" : {  
         "full-name" : "JC Denton",
         "email-address" : "xjcdenton@your_org.com"
      }, 
      "enumerated" : true,
      "added-by-date" : "2018-09-09T23:39:25.394+0000",
      "url" : "https://your_server_url/scr/glossary/2500d8",
      "hyperlink-references" : [  
         {  
            "url" : "https://google.com",
            "name" : "Google",
            "added-by-date" : "2018-09-17T20:28:19.677+0000",
            "added-by-user" : {  
               "full-name" : "Jane Doe",
               "email-address" : "jdoe@your_org.com"
            }
         }
      ],
      "glossary-references":[  
         {  
            "id" : "c001e",
            "name" : "Background Check Forms",
            "category" : "input-output",
            "type" : "text",
            "enumerated" : false,
            "added-by-user" : {  
               "full-name" : "JC Denton",
               "email-address" : "xjcdenton@your_org.com"
            },
            "added-by-date" : "2018-09-06T15:35:05.806+0000",
            "url" : "https://localhost:8443/scr/glossary/c001e"
         }
      ],
      "file-references" : [
         {
            "name" : "import_inputs.csv",
            "added-by-date" : "2018-10-29T15:24:39.272+0000",
            "added-by-user" : {
               "full-name" : "Jane Doe",
               "email-address" : "jdoe@your_org.com"
            }
         }
      ]
   }
]
Example 2 input
LIST all inactive glossary values in the KPI category, in an account where you can see inactive glossary values:
  • Using User Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token"  
    "https://your_server_url/bwl/glossary-values?category=kpi&active-state=inactive"
  • Using Service ID OAuth 2 client credentials:
    curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-values?category=kpi&active-state=inactive"
  • Using Service ID OAuth 2 client credentials with user context:
    curl -i -H "Authorization: Bearer access_token"  
    -H "X-On-Behalf-Of:user_name@domain.com" "https://your_server_url/bwl/glossary-values?category=kpi&active-state=inactive"
Example 2 output
LIST all inactive glossary values in the KPI category, in an account where you can see inactive glossary values:
[
  {
     "id": "750019",
     "name": "notUsedKpi",
     "category": "kpi",
     "visibility": "visible-when-used",
     "active-state": "inactive",
     "enumerated": false,
     "added-by-date": "2020-08-31T13:14:15.154+0000",
     "url": "https://localhost:8443/scr/glossary/750019"
  }
]
Response messages
HTTP code Reason
200

The request was completed successfully.
400

There was an error processing the request. Required parameters were missing or contained invalid values.
401
This user didn't pass authentication. This response could appear for the following reasons:
  • An invalid username or password was provided.
  • This user belongs to multiple accounts and an account wasn't specified in the request.
403 Access is forbidden because you have insufficient permissions for the specified glossary value. To use active-state=inactive, you must be an admin who can see inactive glossary values.
More details
To get more details about the operations and response values, use a Swagger Editor to view the APIs:
  1. Download the rest-apis.zip file.
  2. Extract the openapi.yaml file.
  3. Open a web browser, and navigate to https://editor-next.swagger.io/.
  4. Import openapi.yaml using the File > Import File option.