Article authored by Martin Westphal
This week and next we will be re-blogging some of our most valuable content around APIs in Blueworks Live. Watch for a post of all 5 parts of the API 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
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:
/scr/api/ListFiles and /scr/api/FileDownload
- For use case 2:
/scr/api/UserList and /scr/api/activity
- For use case 3:
/scr/api/Search
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:
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.
SoapUI
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 bin directory of SoapUI:
-Dsoapui.https.protocols=SSLv3,TLSv1.2
- 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
Blueworks Live.
- Enter a resource for the request. First start with
/api/Auth and 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
20091212 is used as the default value for the API version. Add a parameter named version with 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 401 Unauthorized response, as shown in Figure 13.
Figure 13. Result of an unauthorized request
Although the 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 provide the account parameter and the version attribute, if available.
If you try to use a resource that does not exist because of a typo, you receive a 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
IBM70 account 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:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
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 comment.
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 Garant and requests the cost and work_time attributes, 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.
Figure 24. Example search request for a specific tag
Conclusion
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.
Acknowledgments
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.
Downloadable resources
Related topics
#BlueworksLive
#processmodeling
#processmapping
#RESTAPI