Blueworks Live API

Use the Blueworks Live API to access a limited subset of its available functions, such as search, list process details, and start work instances. Most Blueworks Live API calls return responses in JSON format; therefore, an example is provided to describe some of the JSON responses.

To enable the API, go to the Account Information tab of the Admin page and click Enable API access via User Service IDs, Enable API access via Service IDs, or all.

Overview

The Blueworks Live API provides access to a limited subset of the available Blueworks Live functions, such as search, list process details, and start work instances. All access to the API requires authentication by using an access token. It either has global access to the account or can be restricted to what is permitted for a specific user. Viewers and community members do not have access to the API.

URL for Curl

To issue a Curl command, you must know the URL of the server where your account is. The following are the steps to find the URL:
  1. Issue the Curl command by using the URL you typically log in to. For example, https://www.blueworkslive.com
  2. Use the -i option to include the HTTP header in the output.
  3. If the command produces a "301" response, check the Location field of the response. That field shows the URL to use.

Authentication

Authentication is required for Blueworks Live API calls.

To do authentication, use OAuth 2 authentication with client credentials. Automated systems use a Service ID/User Service ID to request a token.

Responses
401 UNAUTHORIZED
The token has expired or is unauthorized at the time to complete the action, but authorization might be possible.
403 FORBIDDEN
The user is authenticated, but the action is disallowed for the user. Possible cause is that a Service ID that was not in the User Management category tried to call the /scr/api/UserList. Another possible cause is that the APIs isn't enabled by the administrator on the Account Information tab.

OAuth 2 client credentials

User Service ID authentication

When you create a User Service ID, the OAuth 2 client credentials (Client ID and Secret) are downloaded as a JSON file. Use those credentials to request an access token. The following command to request the token:
curl.exe -k -i -H "Content-type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&client_id=
my_client_id&client_secret=my_client_secret&consent_type=user_consent" "https://your_server_url/oauth/token"
  • Replace my_client_id with the Client ID value from the Service ID JSON file.
  • Replace my_client_secret with the Secret value from the Service ID JSON file.
  • Specify the grant_type as client_credentials.
  • Specify the consent_type as user_consent.
  • Replace your_server_url with the server that you are making the POST request to, for example, https://ServerName/oauth/token.
If the command produces a "301" response, check the Location field of the response and request the access token at the URL that is specified in that field. If the command produces a "400" response, check the syntax of your command. Check the names and values of the grant_type, user_consent, client_id, and client_secret parameters.
The server returns a short-lived token that the system can use to call the API. For example:
curl -i -H "Authorization: Bearer access_token" "https://your_server_url/scr/api/UserList"
When the token expires, the command produces a "401" response and the system must request a new one.
A User Service ID can have multiple categories, which determine the set of APIs that it can access.
  • Account activity reporting
  • Artifact authoring
  • Artifact reporting
  • User management
  • Work management
The User Service ID cannot be used for APIs outside of the categories opted.

The response includes only the resources that the specified user has access to or is permitted to see in the account. For example, if the /bwl/blueprints API is called, only the blueprints that are visible to the User Service ID owner are shown. Or, if the /bwl/blueprints/{blueprint-id} API is called to get the details of a specific blueprint and the blueprint is not accessible to the User Service ID owner, the command produces a "403" response.

For information about OAuth 2, see The OAuth 2.0 Authorization Framework.

Service ID authentication

When your administrator creates a Service ID, the OAuth 2 client credentials (Client ID and Secret) are downloaded as a JSON file. Use those credentials to request an access token:
curl.exe -k -i -H "Content-type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&client_id=
my_client_id&client_secret=my_client_secret" "https://your_server_url/oauth/token"
  • Replace my_client_id with the Client ID value from the Service ID JSON file.
  • Replace my_client_secret with the Secret value from the Service ID JSON file.
  • Specify the grant_type as client_credentials.
  • Replace your_server_url with the server that you are making the POST request to, for example, https://ServerName/oauth/token.
If the command produces a "301" response, check the Location field of the response and request the access token at the URL that is specified in that field. If the command produces a "400" response, check the syntax of your command. Check the names and values of the grant_type, user_consent, client_id, and client_secret parameters.
The server returns a short-lived token that the system can use to call the API. For example:
curl -i -H "Authorization: Bearer access_token" "https://your_server_url/scr/api/UserList"
When the token expires, the command produces a "401" response and the system must request a new one.
Each Service ID has a category, which determines the set of APIs that it can access.
  • Account activity reporting
  • Artifact authoring
  • Artifact reporting
  • User management
  • Work management
The Service ID cannot be used for APIs outside of that category.

APIs that can be called only on behalf of a specific user (such as FollowedProcesses and TaskList) require a user context. Other APIs optionally allow you to specify a user context. To provide the user context, pass a X-On-Behalf-Of header in your request with the username as the value. The response includes only the resources that the specified user has access to or is permitted to see in the account. For example, if the /bwl/blueprints API is called with a user context, only the blueprints that are visible to the specified user are shown. If the /bwl/blueprints/{blueprint-id} API is called with a user context to get the details of a specific blueprint and the blueprint is not accessible to the specified user, the command produces a "403" response.

Not all APIs are enabled for user context. If you try to pass a user context to an API that is not enabled for it, the command produces a "400" response.

For information about OAuth 2, see The OAuth 2.0 Authorization Framework.

Rate Limiting

IBM Blueworks Live applies a rate limit that determines how often an API can be called within a specific period. 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 of the account for the API is exceeded, the next request is rejected with status code 429 and response header Retry-After. This status code indicates the number of seconds when the next request can be made.

OpenAPI specification

The OpenAPI specification is a standardized, machine-readable format for describing RESTful APIs. The OpenAPI specification provides you with a clear and comprehensive understanding of APIs, enabling easier interaction and integration.

The specification includes detailed information about:

  • Available endpoints
  • Request parameters
  • Response formats
To get started, you can explore the interactive API documentation that is generated from the OpenAPI file here: OpenAPI specification. This resource simplifies integration, accelerates troubleshooting, and ensures a seamless development experience.

Examples

Use the following Java template as a basis for your own projects. The example uses the JSON4J library from the Apache Wink project to decode the JSON responses sent back by the API.

  1. Download the following Java files:
  2. Download the following Java archive (JAR) file:

    json4j

  3. Compile the following example:
    • For Windows operating systems, 
      javac -cp .;wink-json4j-1.3.0.jar RestApiClientTemplate.java
javac -cp .;wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate.java
javac -cp .;wink-json4j-1.3.0.jar SearchExample.java
    • For Linux operating systems, 
      javac -cp ./wink-json4j-1.3.0.jar RestApiClientTemplate.java
javac -cp ./wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate.java
javac -cp ./wink-json4j-1.3.0.jar SearchExample.java
  4. Run the example and change credentials to valid values.
    • For Windows operating systems,
      java -cp .;wink-json4j-1.3.0.jar RestApiClientTemplate
java -cp .;wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate
java -cp .;wink-json4j-1.3.0.jar SearchExample
    • For Linux operating systems,
      java -cp .:./wink-json4j-1.3.0.jar RestApiClientTemplate
java -cp .:./wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate
java -cp .:./wink-json4j-1.3.0.jar SearchExample

For more information, contact Blueworks Live Support.