Contents


Do more with the IBM Blueworks Live REST API, Part 2

Explore the Blueworks Live REST API resources with a generic testing tool

Comments

Content series:

This content is part # of # in the series: Do more with the IBM Blueworks Live REST API, Part 2

Stay tuned for additional content in this series.

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
ResourceMethodDescription
/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/ManageGroup GET,
PUT, DELETE
Manage groups.
/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.
/scr/api/provision/user GET,
PUT, DELETE
Provision user to an account.
/scr/api/revision GET,
POST
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: /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

  1. After you start SoapUI, you see an empty workspace. Create a REST project by right-clicking Projects and selecting New REST Project.
  2. For the URI, type https://www.blueworkslive.com, as shown in Figure 1.
Figure 1. New REST Project window
Screen                     capture of New REST Project window
Screen capture of 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
Screen                     capture of New REST Project window
Screen capture of New REST Project window
  1. Right-click the project name and select Rename. Give your project an appropriate name such as Blueworks Live.
  2. 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
    Screen                     capture of entering a resource and send request
    Screen capture of entering a resource and send request
  3. 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
    Screen                     capture of the Response HTML tab
    Screen capture of the Response HTML tab
  4. 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
    Screen                     capture of adding an authorization
    Screen capture of adding an authorization
  5. 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
    Screen                     capture of configuring the authorization
    Screen capture of configuring the authorization
  6. 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
    Screen                     capture of resubmitted request results
    Screen capture of resubmitted request results
  7. 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
    Screen                     capture of adding a parameter
    Screen capture of adding a parameter
  8. 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
    Screen                     capture of setting parameter values
    Screen capture of setting 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.
    Screen                     capture of example request with results
    Screen capture of example request with results

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
Screen                     capture of a request name: My Accounts

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
Screen                     capture of configuring basic authorization
Screen capture of configuring basic authorization

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
Screen                     capture of the Raw tab of an unauthorized request
Screen capture of the Raw tab 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
Screen capture                     of a 404 Not Found response

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.
Screen                     capture of example endpoint
Screen capture of example endpoint
Figure 16. Use the actual service endpoint for the request
Screen                     capture of example endpoint
Screen capture of example endpoint

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
Screen                     capture of example GET request forwarding
Screen capture of example GET request forwarding

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.

  1. 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
    Screen                     capture of HTML tab with a request for a file list
    Screen capture of HTML tab with a request for a file list
  2. 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
    Screen                     capture the Raw tab
    Screen capture the Raw tab

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.

  1. 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
    Screen                     capture of results of the User list request
    Screen capture of results of the User list request
  2. 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
Screen                     capture of example request for login information
Screen capture of 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
Screen                     capture of example request for comments
Screen capture of 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.

  1. 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.
    Screen                     capture of example search request
    Screen capture of example 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
Screen                     capture of example search request for a specific tag
Screen capture of 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


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware, Cloud computing
ArticleID=1027619
ArticleTitle=Do more with the IBM Blueworks Live REST API, Part 2: Explore the Blueworks Live REST API resources with a generic testing tool
publish-date=06292017