Do more with the IBM Blueworks Live REST API, Part 2
Explore the Blueworks Live REST API resources with a generic testing tool
This content is part # of # in the series: Do more with the IBM Blueworks Live REST API, Part 2
This content is part of the series:Do more with the IBM Blueworks Live REST API, Part 2
Stay tuned for additional content in this series.
Part 1 of this series presented 5 general use cases for the best ways to use the Representational State Transfer (REST) application programming interface (API) for IBM® Blueworks Live. You also learned different implementation approaches for each use case. The next parts in the series, starting with this one, dive into the approaches and discuss implementation details.
Parts 2-4 of the series use the same three use case scenarios as examples, which are introduced here in Part 2. If you are only interested in the Java implementation, you can read the next two sections about the REST API and the use case scenarios, but then you can skip directly to Part 4.
Blueworks Live REST API
The Blueworks Live API provides access to a limited subset of the available Blueworks Live capabilities. All access requires a valid user name and password and is restricted based on the normal Blueworks Live roles and permissions.
After you log in to Blueworks Live, you have access to the following online documentation about the REST API: Blueworks Live REST API documentation published on the IBM Knowledge Center.
Table 1 shows all available REST resources as of 2016, their methods, and a description of the resource.
Table 1. Overview of REST resources
|/scr/api/activity||GET||Retrieve account activity details.|
|/scr/api/ActivityDocumentation||GET||Retrieve the documentation for an activity.|
|/scr/api/AppDetail||GET||Retrieve details of an app definition for an ID.|
|/scr/api/AppList||GET||Get list of the apps that the user has access to start.|
|/api/Auth||GET||Check user authentication and return accounts information|
|/scr/api/Avatar||GET||Download user avatars.|
|/scr/api/BpmnExport||GET||Export Process Diagrams to BPMN 2.0 format.|
|/scr/api/ExcelExport||GET||Export a space, process, or decision to an excel file.|
|/scr/api/export/process||GET||Export a specific revision of a process in BPMN 2.0 format.|
|/scr/api/FileDownload||GET||Download of an attached document.|
|/scr/api/FileUpload||POST||Add file attachments to process activities or work items.|
|/scr/api/FollowedProcesses||GET||Get information about the processes that the user marked as followed|
|/scr/api/LaunchInstance||POST||Launch a new instance from an app definition.|
|/scr/api/LibraryArtifact||GET|| New since December 2015:|
Retrieve library artifact details.
|/scr/api/ListFiles||GET||Retrieve list of attached files.|
|/scr/api/NewsFeed||GET||Retrieve messages in date time order from most recent to oldest.|
|/scr/api/PostComment||POST||Add a comment to an activity or as a reply to an existing comment.|
|/scr/api/PrintDiagram||GET||Download PDF view of the diagram.|
|/scr/api/ProcessData||GET||Get process data as a map of items.|
|Provision user to an account.|
|Query or create process/policy/decision revisions|
|/scr/api/Search||POST||Search an account for specified properties.|
|/scr/api/TaskList||GET||Retrieve list of tasks assigned to or completed by the current user.|
|/scr/api/TaskListCount||GET||Get total number of tasks assigned to or completed by the current user.|
|/scr/api/UpdateFavorites||POST||Update the favorite apps list of a user.|
|/scr/api/UserList||GET||Retrieve list of the users in the authenticated user's account.|
|/scr/api/UserListForWork||GET||Retrieve list of users that can get tasks assigned to.|
|/scr/api/WorkAction||POST||Perform some action, such as completing a task, for a piece of work.|
|/scr/api/WorkComment||POST||Add a comment to a work item.|
|/scr/api/WorkDetail||GET||Return the details of a work instance for an ID.|
|/scr/api/WorkList||GET||Retrieve list of open or completed work instances that the current user started.|
Use case scenarios
Consider three typical use cases in this tutorial series. The advantages of considering use cases are that you learn both the theory of the Blueworks Live REST API and how the technology is used, to retrieve information or data, and to store and present information or data in an appropriate way.
The first two use cases are real requests by Blueworks Live customers:
- Use Case 1: Get all attached documents from a specific Blueworks Live account and download them to a local file system. Next, you want to get only the files that were added to the Blueworks Live repository since your last call.
- Use Case 2: To get an idea of how intensely users are updating process models, writing comments, attaching documents, and other activities, you want a report that lists all users and the last date of the contribution to the repository. For example, you want a report of which users are still active and are working on process optimization. There are many built-in reports in Blueworks Live that show recent changes by date, user, space, and statistics within each space, but a report of users who are still active and are working on process optimization is not available.
Although these use cases are special cases, they are good examples to show the capability of the REST interface. The first use case has a technical purpose, namely to back up the documents (which is why it isn't related to general use cases that were introduced in Part 1 of this series). The second use case falls under the categories of user administration and dashboards. In the simple form considered in this tutorial, the use case has only a reporting aspect, but you can extend it to administrate users as well. More typical examples in the dashboard category are special reports about the process model contents and documentation such as the following use case:
- Use Case 3: Produce a report that lists all artifacts tagged with a
specific keyword, such as
core, and that contains detailed information like artifact type, name and ID.
A quick look at the available REST resources tells you that you need the following APIs to implement the use cases:
- For use case 1:
- For use case 2:
- For use case 3:
Generic REST testing tools
There are a variety of REST testing tools available, and some are available at no cost. If you want a desktop program that allows you to define testing projects, consider SoapUI. Tools that you can run in a browser are now available: Postman is available for Google Chrome and RESTClient is a similar tool available as an add-on for Firefox.
Get the REST testing tools from the following websites:
- SoapUI: http://www.soapui.org. Details and downloads are available.
- Postman: https://www.getpostman.com. See instructions on the website for installing Postman as a Google Chrome app.
- RESTClient: https://addons.mozilla.org/en-US/firefox/addon/restclient. Install this add-on for Firefox by clicking Add to Firefox. After a restart, call RESTClient from Tools menu.
This tutorial uses SoapUI as the REST testing tool, but the steps you need to perform in other tools are very similar. You won't face difficulties using an alternative tool.
To get familiar with the Blueworks Live API and better understand the calls and responses, this tutorial shows how to use SoapUI for exploration. In Part 3 of this series, you learn to process the responses with program logic.
SoapUI is a tool to test web services based in SOAP and REST. The base version is available under GNU Lesser General Public license as free software. See http://www.soapui.org for more information and to download the tool. This tutorial uses version 5.1.2.
Create the SoapUI project
Before you start SoapUI, you must change the default security protocols.
Starting in July 2017, Blueworks Live only supports TLS version 1.2 and
more recent versions, for higher security. Add the following line to the
file with extension
.vmoptions in the
- After you start SoapUI, you see an empty workspace. Create a REST project by right-clicking Projects and selecting New REST Project.
- For the URI, type
https://www.blueworkslive.com, as shown in Figure 1.
Figure 1. New REST Project window
The first SoapUI request
The empty request is created and opened in the center SoapUI window, as shown in Figure 2.
Figure 2. Example first request
- Right-click the project name and select
Rename. Give your project an
appropriate name such as
- Enter a resource for the request. First start with
/api/Authand then send the request by clicking on the green arrow, as shown in Figure 3.
Figure 3. Enter resource and send request
- You receive a response from the server. Select one of the format tabs,
such as the HTML tab, to look at the content. As
shown in Figure 5, you see a message that an authorization is required.
Figure 4. Response HTML tab
- Select the settings for Auth in the bottom of the
window, and add an authorization as shown in Figure 5.
Figure 5. Add an authorization
- Choose Basic as the authorization type and enter the
user name and password. Also, select Authenticate
pre-emptively, as shown in Figure 6.
Figure 6. Configure the authorization
- Send the request again by clicking the green arrow and selecting
JSON as the output format. With correct user
credentials, you receive a list with all of your Blueworks Live
accounts. For an example, see Figure 7.
Figure 7. Resubmitted request results
- Add a parameter to the request. You can use the + icon, as shown in
Figure 8, or you can click Parameters.
Figure 8. Add a parameter
- A quick look into the API documentation shows that
20091212is used as the default value for the API version. Add a parameter named
versionwith a value of
20110917, and send the request again, as shown in Figure 9.
Figure 9. Set parameter values
Next to the green arrow you can see how the request is built with the extension
?version=20110917. Figure 10 shows the new result, which also includes the ID for every account, in addition to the name.
Figure 10. Result of the request using a different version.
Tips for creating further requests
Now you call other resources in your exploration project and use multiple requests with various parameters. Give the requests a meaningful name by right-clicking and selecting Rename. Enter a new name like you did for the project. See Figure 11.
Figure 11. Example of a meaningful name for a request
You can create additional resources by right-clicking the URI of Blueworks Live and selecting New Resource.
Then you can create additional methods (besides GET) by right-clicking on the resource and selecting New Method.
You can create additional requests for a method by right-clicking on the method and selecting New Request.
Important: Do not forget to set the authorization for each request, as shown in Figure 12.
Figure 12. Configure authorization for each request
To simplify the process, you can clone an existing request and change the method or the parameters.
Some requests require mandatory parameters such as the account name. If you
don't provide the parameters, you receive a
response, as shown in Figure 13.
Figure 13. Result of an unauthorized request
account parameter is described as optional in the
documentation, understand that you need an alternative if you do not set
it. Consider using the
accountId parameter or a cookie in a
session. A call might also work, without giving the account, if you have
only one Blueworks Live account. However, to be safe, you should always
account parameter and the
attribute, if available.
If you try to use a resource that does not exist because of a typo, you
404 Not Found response, as shown in Figure 14.
Figure 14. Result for an unknown example resource
Be aware that all requests other than
/api/Auth must be
forwarded to the final service provider that hosts your specific account
data. For example, you might want to access one Blueworks Live account
that is hosted in Amsterdam, and you might want to access another
Blueworks Live account that is hosted in Austin. Until now you gave only
one global Blueworks Live URL. For security reasons, most REST clients do
not automatically forward data send though the POST method. Instead, use
the correct service provider address for the account. This data can be
found on the response from the
Auth call when you provide an
/api/Auth account with the
https://www.blueworkslive.com endpoint and provide the
account that you want to use. You receive the service provider address.
For consecutive calls, use the service provider as endpoint.
Figure 15 shows an example with a dedicated IBM server called
ibm.blueworkslive.com. The example in Figure 16 uses the
server as the new endpoint.
Figure 15. Determine the service endpoint.
Figure 16. Use the actual service endpoint for the request
SoapUI automatically forwards GET requests by default. See Figure 17.
Therefore, for these types of requests, you might also keep
https://www.blueworkslive.com as an endpoint. Parts 2 and 3
of this series discuss this topic further.
Figure 17. Automatic GET request forwarding by SoapUI
Use case examples
Now you determine which REST resources are needed to implement the three use case scenarios that were previously described. These examples briefly look into the service calls and provide some sample results. These examples are a good starting point to implement useful tools for the scenarios in Part 3 and Part 4.
Use Case 1: Attached documents
To back up all documents that are attached to a Blueworks Live account, you first need a list of these files and then a way to download each of them.
- Use the /scr/api/ListFiles API resource: The sample
call shown in Figure 18 requests a list of files from the
IBM70account with creation dates since 3/1/2015. In this example, it is only one file. Note that this request requires administration rights for the account.
Figure 18. Request for a file list
- Use the /scr/api/FileDownload API resource:
Use the return value from the previous example to get the corresponding file. However, SoapUI displays the content in a raw format, as shown in Figure 19.
Figure 19. Example of requesting a pdf file with SoapUI
Use Case 2: User activities
For the user activity report use case, you first need a list of users and then some details about login times or activities for each of the users.
- Use the /scr/api/UserList API resource:
Receive a list of users. See Figure 20 for an example. Some of the following content in screen captures is truncated on purpose for this tutorial so that you can see the returned attributes but not the full names and user data from the original customer examples.
Figure 20. Result of the user list request
- Use the /scr/api/activity API resource:
This API resource offers multiple possibilities. Some types are structured hierarchically, which you can see in the following list:
LOGINS ITEMS_VIEWED PROCESSES_VIEWED POLICIES_VIEWED DECISIONS_VIEWED SPACES_VIEWED COMMENTS PROCESS_COMMENTS DECISION_COMMENTS USERS_JOINED ITEMS_CHANGED PROCESSES_CHANGED POLICIES_CHANGED DECISIONS_CHANGED SPACES_CHANGED ACCOUNT_CHANGED SNAPSHOTS PROCESS_SNAPSHOTS POLICY_SNAPSHOTS DECISION_SNAPSHOTS
If you want to try this use case, start by looking for sample login data over about one week. Otherwise, you might receive a lot of data returned. Figure 21 shows an example request with given start and end dates.
Figure 21. Example request for login information
Figure 22 shows another example with activity comments. Note that the
service result contains key value pairs with some text and the
message key. The text is not the comment itself (which is
entered by a user), but it is a generated message that describes that a
user entered a comment and describes which artifact contains the
Figure 22. Example request for comments
Use Case 3: Search artifacts with specific tags
In this last use case, you find model artifacts in Blueworks Live that are marked with a specific tag.
- Use the /scr/api/Search API resource:
Searching elements in a Blueworks Live account is certainly one of the most important functions. To do so, you must first define what you want to search (type and match) and second, what kind of results you want to retrieve. The example in Figure 23 searches for processes that start with
Garantand requests the
work_timeattributes, in addition to the core information (space, process, activity).
Figure 23. Example of a search request.
To retrieve all artifacts with a certain tag, use
tag as the
search field name and provide the value that you are searching for. Also,
you might want to request returning the associated tags, as shown in
Figure 24. Example search request for a specific tag
You completed Part 2 of the Blueworks Live REST API series. You learned where to find information about the service resources of the Blueworks Live REST API and how to authenticate and send service requests with a testing tool such as SoapUI. This Part 1 also identified all the specific REST API resources that are needed to implement three proposed example use cases.
In Part 3 and Part 4, you learn how to process the results of the REST API calls. You learn how to call the REST API and use the results with shell commands and scripts (in Part 3) and in Java applications (in Part 4) to extend the built-in capabilities of Blueworks Live.
The author would like to thank Margaret Thorpe from the Blueworks Live management team for help with the tutorial concept and Daniel Treiber from the development team and Sean Roe from the technical sales team for their review and comments.
- Blueworks Live
- Blueworks Live REST API
- SOAP (Wikipedia entry)
- Do more with the IBM Blueworks Live REST API, Part 1: Maximize your business value with 5 universal use cases
- Do more with the IBM Blueworks Live REST API, Part 3: Use Blueworks Live REST API resources interactively with cURL
- Do more with the IBM Blueworks Live REST API, Part 4: Write Java applications with the Blueworks Live REST API
- Do more with the IBM Blueworks Live REST API, Part 5: Write web applications for the Blueworks Live REST API with Node.js on Bluemix
- IBM developerWorks Middleware: Get the latest technical resources on Blueworks Live and other middleware and hybrid cloud solutions, including downloads, demos, articles, tutorials, events, videos, and more.