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 that can have global access to the account or can be restricted to what's permitted for a specific user. Viewers and community members do not have access to the API.
URL for Curl
- Issue the Curl command by using the URL you would typically log in to. For example,
https://www.blueworkslive.com
- Use the
-i
option to include the HTTP header in the output. - 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
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 theClient ID
value from the Service ID JSON file. - Replace
my_client_secret
with theSecret
value from the Service ID JSON file. - Specify the
grant_type
asclient_credentials
. - Specify the
consent_type
asuser_consent
. - Replace
your_server_url
with the server that you are making the POST request to, for example, https://ServerName/oauth/token.
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.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.
- Account activity reporting
- Artifact authoring
- Artifact reporting
- User management
- Work management
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
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 theClient ID
value from the Service ID JSON file. - Replace
my_client_secret
with theSecret
value from the Service ID JSON file. - Specify the
grant_type
asclient_credentials
. - Replace
your_server_url
with the server that you are making the POST request to, for example, https://ServerName/oauth/token.
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.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.
- Account activity reporting
- Artifact authoring
- Artifact reporting
- User management
- Work management
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. 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.
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.
- Download the following
Java
files:-
The following example programmatically runs
/scr/api/UserList
and parses the results.RestApiClientTemplate.java
-
The following example programmatically runs
/bwl/glossary-values/{category}
and demonstrates how to work with a rate-limited API.RestApiRateLimitClientTemplate.java
-
The following example demonstrates how to call the
/scr/api/Search
API.SearchExample.java
-
- Download the following Java archive (JAR) file:
- 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
- For Windows operating
systems:
- 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 Windows operating systems:
Viewing OpenAPI specification file with Swagger editor
You can use the swagger editor to get more information about the operations and response values of an API.
Follow these steps to view the details:
- 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 option.
For more information, contact Blueworks Live Support.