glossary-values/{value-id}

Use this resource to delete a value from the glossary.

Method summary

HTTP Method	Path	Description
DELETE	/bwl/glossary-values/{value-id}	Deletes a value from the glossary.

DELETE bwl/glossary-values/{value-id}

Description: Use this method to delete any predefined or custom glossary value in any category except tag. Glossary values can be deleted only if they are not currently used in other artifacts or referenced from other glossary values.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be a glossary manager and account administrator, and "Admins have full permissions in all spaces, all user groups, and the glossary" must be on.
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 200 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-On-Behalf-Of	Header	The user context. The value must be an admin in the account. The user must have permission to delete glossary values in the account.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
id	Path	The ID of the glossary value to delete.	Yes	String
force	Query	Force the deletion. If you set this parameter to true, the glossary value is deleted even if it was previously used in other artifacts. Warnings are summarized in the response.	No	Boolean

Response

Example 1 input - Delete a custom glossary value

Try to delete a custom glossary value.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

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-value/2500d8/usage"

Example 1 output - Delete a custom glossary value

In this example, the glossary value is in use and is not deleted. These are the possible usage sections:

active-usages: The glossary value is still in active use in these artifacts.
historical-usages: The glossary value was used in these artifacts, but is no longer in use.
glossary-usages: The glossary value is referenced from these glossary items.
user-usages: The glossary value is a business unit and is referenced from these user settings.

HTTP/1.1 409 Conflict
{
    "developer-message": "This glossary value cannot be deleted because it is in use.",
    "user-message": "This glossary value cannot be deleted because it is in use.",
    "active-usages": [
        {
            "id": "2009f6",
            "name": "Process1",
            "type": "blueprint",
            "space-ids": [
                "13130b"
            ],
            "space-names": [
                "ASpace"
            ],
            "archived-state": "active",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-22T17:13:14.121+0000"
        },
        {
            "id": "200c3a",
            "name": "Process3",
            "type": "blueprint",
            "space-ids": [
                "13130b"
            ],
            "space-names": [
                "ASpace"
            ],
            "archived-state": "archived",
            "published-state": "unpublished",
            "last-modified-date": "2020-09-22T17:14:59.862+0000"
        }
    ],
    "glossary-usages": [
        {
            "id": "13138a",
            "name": "GlossaryValue1",
            "category": "customProperty1",
            "active-state": "active",
            "enumerated": false,
            "usage-type": "reference"
        }
    ],
    "historical-usages": [
        {
            "id": "200c0c",
            "name": "Process2",
            "type": "blueprint",
            "archived-state": "active",
            "last-modified-date": "2020-09-22T17:14:46.551+0000"
        }
    ]
}

Example 2 input - Force deletion of a business unit glossary item

Try to force deletion of a business unit glossary item.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

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-value/2500d8/usage"

Example 2 output - Force deletion of a business unit glossary item

The glossary item cannot be deleted because it is being used in user settings.

HTTP/1.1 409 Conflict
{
    "developer-message": "This glossary value cannot be deleted because it is in use.",
    "user-message": "This glossary value cannot be deleted because it is in use.",
    "user-usages": [
        {
            "id": "4000c",
            "full-name": "John Doe",
            "email-address": "johndoe@domain.com"
        },
        {
            "id": "4000b",
            "full-name": "Jane Doe",
            "email-address": "janedoe@domain.com"
        },
        {
            "id": "40012",
            "full-name": "Mary Poppins",
            "email-address": "marypoppins@domain.com"
        }
    ]
}

Example 3 input - Delete a system glossary value that is no longer in active use

Try to delete a system glossary value that is no longer in active use.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

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-value/2500d8/usage"

Example 3 output - Delete a system glossary value that is no longer in active use

In this example, the glossary item is not deleted because it is still used in historical artifacts.

HTTP/1.1 409 Conflict
{
    "developer-message": "This glossary value cannot be deleted because it is in use.",
    "user-message": "This glossary value cannot be deleted because it is in use.",
    "historical-usages": [
        {
            "id": "c00f7",
            "name": "Hiring - Onboarding",
            "type": "blueprint",
            "archived-state": "active",
            "last-modified-date": "2020-10-14T12:07:39.296+0000"
        }
    ]
}

Example 4 input - Force deletion of a system glossary value that is no longer in active use

Force deletion of a system glossary value that is no longer in active use.

Using User Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

Using Service ID OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token"  
 "https://your_server_url/bwl/glossary-value/2500d8/usage"

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-value/2500d8/usage"

Example 4 output - Force deletion of a system glossary value that is no longer in active use

The glossary item is deleted with warnings.

HTTP/1.1 200 OK
{
    "developer-message": "Glossary value deleted with warnings. The glossary value was deleted, but it will reappear in the glossary if a snapshot that uses it is restored.",
    "user-message": "Glossary value deleted with warnings. The glossary value was deleted, but it will reappear in the glossary if a snapshot that uses it is restored.",
    "historical-usages": [
        {
            "id": "c00f7",
            "name": "Hiring - Onboarding",
            "type": "blueprint",
            "archived-state": "active",
            "last-modified-date": "2020-10-14T12:07:39.296+0000"
        }
    ]
}

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	Glossary values in the `tag` category cannot be deleted.
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	The command failed because the user does not have permission to delete this glossary value.
404	The glossary value does not exist in the account.
409	The command failed because the glossary value is or was in use.
429	The request exceeded the rate limit of the API for this account.

More details

To get more details about the operations and response values, use a Swagger Editor to view the APIs:

Download the rest-apis.zip file.
Extract the openapi.yaml file.
Open a web browser, and navigate to https://editor-next.swagger.io/.
Import openapi.yaml using the File > Import File option.