glossary-values/{category}

Method summary

PUT /glossary-values/{category}

Description

Use this method to add or update glossary values in a specific predefined category or custom process property. The tag and goal categories are not supported.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be a glossary manager.
Supports OAuth 2 client credentials	Yes using a User Service ID containing Artifact Authoring Category
Rate limited	IBM Blueworks Live applies a rate limit that determines how often this API can be called within a specific period. The allowed rate is 30 requests per hour. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users. Once the rate limit for the API is exceeded for the account, the next request is rejected with status code 429 and response header Retry-After, which indicates the number of seconds when the next request can be made.

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	Path	The category of the glossary values to be created or updated. Possible values are participant-businessowner-expert externalparticipant system supplier-customer input-output problem kpi businessunit name of your custom process property	Yes	String

Request JSON body

The request body is an array of JSON objects containing the following properties:

Name	Location	Description	Required	Type
id	JSON body	The ID of the glossary value. Either a name or an ID is required.	Yes	String
name	JSON body	The name of the glossary value. Either an ID or a name is required.	Yes	String
description	JSON body	The description of the glossary value.	No	String
visibility	JSON body	The visibility of the glossary value. Allowed values are always-visible, always-visible-and-preferred, and visible-when-used.	No	String
type	JSON body	A simple type associated with the glossary value. This parameter applies only to the input-output category. Allowed values are text, yes-no, integer, decimal, date, and complex.	No	String
type-link	JSON body	Another glossary value that serves as the type of this glossary value. This parameter applies only to the input-output category.	No	JSON object containing id or name properties
content	JSON body	The content of a glossary value. This parameter applies only to complex types in the input-output category.	No	Array of JSON objects containing id or name properties

Response

Example 1 input - Create a glossary value

Create a new glossary value with the name "input1" in the input-output category:

• Using User Service ID OAuth 2 client credentials:

  curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
     -X PUT --data "[{\"name\":\"input1\",\"description\":\"This is the description\"}]" 
     "https://your_server_url/bwl/glossary-values/input-output"

• Using Service ID OAuth 2 client credentials:

  curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
     -X PUT --data "[{\"name\":\"input1\",\"description\":\"This is the description\"}]" 
     "https://your_server_url/bwl/glossary-values/input-output"

• Using Service ID OAuth 2 client credentials with user context:

  curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
      -H "X-On-Behalf-Of:GlossaryManager@domain.com" -X PUT 
    --data "[{\"name\":\"input1\",\"description\":\"This is the description\"}]" "https://your_server_url/bwl/glossary-values/input-output"

Example 1 output - Create a glossary value

The new value is created and assigned an ID.

{
   "values-created": [
       {
           "id": "13399a",
           "name": "input1"
       }
   ]
}

Example 2 input - Create and update glossary values

This example shows how to use the JSON body to perform bulk creation and updating of glossary values in the input-output category.

Note: If you provide only the name, and the name is already in use, the API will overwrite the existing value with the information provided in the input.

[
   {
       "name" : "input2",
       "description" : "This is the description"
   },
   {
       "name" : "input1"
   },
   {
       "id" : "d0012",
       "type" : "complex",
       "content" : [ 
	   {
            "name" : "input2"
           {
           },
           "id" : "134567"
           }
       ]
   }
]

Example 2 output - Create and update glossary values

A new "input2" glossary value is created and an ID is assigned to it. The properties of the glossary value with ID "d0012" are updated, and it is now a complex type with "input2" as its content. No changes are made to "input1" or ID "134567."

{
   "values-created": [
       {
           "id": "1348cf",
           "name": "input2"
       }
   ],
   "values-updated": [
       {
           "id": "d0012"
       }
   ],
   "values-unchanged": [
       {
           "id": "134567",
           "name": "input1"
       }
   ]
}

Example 3 input - Create a glossary value with references

This example shows how to use the JSON body to create a glossary value with hyperlink references and linked glossary references in the input-output category.

Note: Linked glossary references can be added by glossary ID or glossary name. If you use the glossary name, you must also add the the category of the glossary reference.

[  
   {  
       "name":"input1",
       "glossary-references":[  
           {  
               "id":"c0027"
           },
           {  
               "name":"Access Badge",
               "category":"input-output"
           }
       ],
       "hyperlink-references":[  
           {  
               "url":"http://yahoo.com",
               "name":"Yahoo"
           }
       ]
   }
]

Example 3 output - Create a glossary value with references

The new value is created and the references are assigned to it.

{
    "values-created": [
        {
           "id": "13399a",
           "name": "input1"
       }
   ]
}

Example 4 input - Create and update glossary values - input not valid

Input data is validated. In the following example, as shown in the output, updates to both entries as skipped and no changes are made.

[
   {
       "id": "1348d7",
       "name" : "input1"
   },
   {
       "id" : "d0012",
       "type" : "complex",
       "content" : [ {
           "name" : "input 100"
       }]
   }
]

Example 4 output - Create and update glossary values - input not valid

Updates to both entries are skipped and the error messages are provided. For a complete list of validation messages, see the table that follows.

{
   "values-skipped": [
        {
            "id": "1348d7",
            "name": "input1",
            "code": "BWLGVU05",
            "message": "Name conflict with an existing item."
        },
        {
            "id": "d0012",
            "code": "BWLGVU09",
            "message": "An ID or name that is used in the type-link or content property is not found."
       }
   ]
}

Validation messages

Error code	Error message
BWLGVU01	ID or name is not valid.
BWLGVU02	ID is not valid.
BWLGVU03	A value with this ID is not found.
BWLGVU04	You don't have access to that item to update it.
BWLGVU05	Name conflict with an existing item.
BWLGVU06	Name conflict with an existing item that you don't have access to.
BWLGVU07	Name conflict with 2 or more existing items.
BWLGVU08	The content is not valid.
BWLGVU09	An ID or name that is used in the type-link or content property is not found.
BWLGVU10	You don't have access to an ID or name that is used in the type-link or content property.
BWLGVU11	An ID or name that is used in the type-link or content property of the item refers to the item itself.
BWLGVU12	A glossary reference URL is not valid.
BWLGVU13	The ID of a linked glossary reference is not valid.
BWLGVU14	The ID, name, or type of a linked glossary reference is not valid.
BWLGVU15	An ID or name that is used in a linked glossary reference of an item refers to the item itself.
BWLGVU16	You don't have access to an ID or name that is used in a linked glossary reference.
BWLGVU17	An ID or name that is used in a linked glossary reference is not found.
BWLGVU18	An ID that is used in the type-link or content property of the item is not valid.
BWLGVU19	An ID or name that is used in the type-link or content property is not valid.
BWLGVU20	There are duplicate entries in the input. The first entry is used and all others are skipped.

Response headers

Header name	Description
Retry-After	When the next request can be made, in number of seconds.

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 updating glossary values.
404	The category path identifies a glossary category that does not exist in this account.
429	The request exceeded the rate limit of the API for this account.

Check the HTTP specification for any response codes not listed here.

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.