policies/{policy-id}

Use this resource to update a specific policy model.

Note: API documentation migrated to IBM API Hub External link opens a new window or tab

. Find the latest updates and documentation for Blueworks Live APIs in API Hub.

Method summary

HTTP Method	Path	Description
PUT	/bwl/policies/{policy-id}	Updates description or references of a specific policy model.

PUT /policies/{policy-id}

Description: Use this method to update description or hyperlink-references of a policy. To add a File attachment use FileUpload API.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes
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. When 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
Content-Type	Header	The value must be `application/json`.	Yes	String
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to create a policy in the account and to the specified parent space, if any.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
policy-id	path	The identifier of the policy model to update.	Yes	String

Request JSON body

The request body is a JSON object containing the following properties:

Name	Location	Description	Required	Type
description	JSON body	The new description to give the policy. The description contains HTML markup. Either a description or a hyperlink-references must be specified.	No	String
hyperlink-references	JSON array	JSON array of hyperlink-references. A hyperlink-reference object contains name and url. Either a description or a hyperlink-references must be specified.	No	String
name	JSON body	The name of the hyperlink-reference.	No	String
url	JSON body	The URL of the hyperlink-reference.	No	String

Response

Example 1 input - Update a specified policy

Update description and hyperlink references of a specified policy

Using User Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'content-type: application/json' \
  --data '{"description" : "Security Policy","hyperlink-references": [{"name": "IBM Blueworks Live security policy","url": "https://www.ibm.com/docs/en/blueworks-live?topic=description-blueworks-live-security-policy"},{"name": "IBM Product Documentation","url": "https://www.ibm.com/docs/en/blueworks-live"}]}'

Using Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'X-On-Behalf-Of: user_name@domain.com' \
  --header 'content-type: application/json' \
  --data '{"description" : "Security Policy","hyperlink-references": [{"name": "IBM Blueworks Live security policy","url": "https://www.ibm.com/docs/en/blueworks-live?topic=description-blueworks-live-security-policy"},{"name": "IBM Product Documentation","url": "https://www.ibm.com/docs/en/blueworks-live"}]}'

Example 2 input - Delete description of a specified policy

Delete description alone of a specified policy

Using User Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'content-type: application/json' \
  --data '{"description" : ""}'

Using Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'X-On-Behalf-Of: user_name@domain.com' \
  --header 'content-type: application/json' \
  --data '{"description" : ""}'

Example 3 input - Remove all hyperlink-references of a specified policy

Remove all hyperlink references of a specified policy

Using User Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'content-type: application/json' \
  --data '{"hyperlink-references" : []}'

Using Service ID OAuth 2 client credentials:

curl -i --request PUT \
  --url https://your_server_url/bwl/policies/5f6000cc86ae4 \
  --header 'authorization: Bearer access_token' \
  --header 'X-On-Behalf-Of: user_name@domain.com' \
  --header 'content-type: application/json' \
  --data '{"hyperlink-references" : []}'

Example output: If the request is successful, a “200 OK” "Updated Policy"message is returned.

Response headers

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

Response messages

HTTP code	Reason
200	The request was completed successfully.
400	There was an error processing the request. A policy ID doesn't exist in the account, the JSON body is missing from the request, or a required parameter is missing.
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.
404	The policy-id is invalid.
429	The request exceeded the rate limit of the API for this account.

For more information, see OpenAPI specification.