blueprints/{blueprint-id}/activities/{activity-id}/documentation

Use this resource to update documentation of an activity within a specified blueprint.

Method summary

HTTP Method Path Description
POST /bwl/blueprints/{blueprint-id}/activities/{activity-id}/documentation Update documentation of an activity within a blueprint

POST /bwl/blueprints/{blueprint-id}/activities/{activity-id}/documentation

Description
Use this method to update documentation of an activity within a blueprint.
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.

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
Content type Header The value must be application/json Required when there is content in the request body 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 blueprint, if any. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
blueprint-id Path The identifier of the blueprint. Yes String
activity-id Path The identifier of the activity. 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 activity. The description contains HTML markup. Yes String
Response
Example - Update Activity documentation
  • Using User Service ID OAuth 2 client credentials:
    curl -i --request POST \
  --url https://yyour_server_url/bwl/blueprints/5f6000cc6003d/activities/5f6000cc60045/documentation \
  --header 'authorization: Bearer access_token' \
  --header 'content-type: application/json' \
  --data '{"description" : "<h1>New paragraph</h1>"}'
  • Using service ID OAuth 2 client credentials:
    curl -i --request POST \
  --url https://your_server_url/bwl/blueprints/5f6000cc6003d/activities/5f6000cc60045/documentation \
  --header 'authorization: Bearer access_token' \
  --header 'X-On-Behalf-Of: user_name@domain.com' \
  --header 'content-type: application/json' \
  --data '{"description" : "<h1>New paragraph</h1>"}'
Example output

If the request is successful, a “200 OK” "Updated Activity Documentation" 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. 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.
404 The blueprint-ID or activity-ID does not exist.
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:
  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.