Blueworks Live API

Use the Blueworks Live API to access a limited subset of its available functions, such as search, list process details, and launch 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 Service IDs, Enable API access via basic authentication, or both.

Overview

The Blueworks Live API provides access to a limited subset of the available Blueworks Live functions, such as search, list process details, and launch work instances. All access to the API requires authentication using either an access token that can have global access to the account or can be restricted to what's permitted for a specific user, or a valid username and password that is restricted based on the normal Blueworks Live roles and permissions. Viewers and community members do not have access to the API.

URL for Curl

To issue a Curl command, you need to know the URL of the server where your account is. To find that URL:
  1. Issue the Curl command using the URL you would typically log into. 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:
  1. Use OAuth 2 authentication with client credentials. Automated systems use a Service ID to request a token.
  2. (deprecated) Use basic authentication in combination with the account or the accountId parameter. Basic authentication requires a user ID and password.
Responses
401 UNAUTHORIZED
The user is unauthorized at the time to complete the action, but user authorization might be possible. Use the /api/Auth method to determine the cause. One of the possible causes is that the user's password expired.
403 FORBIDDEN
The user is authenticated, but the action is disallowed for the user. Possible causes are that a user without an administrator license tried to call the /scr/api/UserList or that a Service ID that was not in the User Management category tried to call the /scr/api/UserList. Another possible cause is the APIs isn't enabled by the administrator on the Account Information tab.

OAuth 2 client credentials

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. You can use 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" "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 name and values of the grant_type, 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 an 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. Or, 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.

Basic authentication (deprecated)

To access the APIs through basic authentication, provide the username and password in the request. Users who belong to multiple accounts must also specify an account name or an account ID.

You can experiment with API calls by using the Curl program. The following example demonstrates how to make a basic authentication call using Curl:
curl -i --basic --user user_name:password "https://your_server_url/scr/api/UserList"

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 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.

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.