Article authored by Sam Weeks and 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.
This series of articles introduces the Representational State Transfer (REST) application programming interface (API) for IBM® Blueworks Live, which provides extra capabilities such as customized reporting on business process information stored in Blueworks Live. Blueworks Live is an IBM software as a service (SaaS) offering for collaborative modeling of business processes and business rules in the cloud. REST is a method of communicating with servers and an alternative for web services based on SOAP.
Part 1 presents five general use cases that use the REST API, with an overview of approaches to get the most of out of each use case. The remaining parts in the series dive into these approaches and show how to implement use cases based on practical examples.
Blueworks Live is a powerful platform for process modelling. It offers an intuitive environment for collaborative process modelling and a cloud repository for process and decision artifacts. Blueworks Live is much more than simply a process modelling tool and is often underused.
When used to its full potential, Blueworks Live becomes a structural map for your entire organization, from a high level departmental classification, down to the details of individual steps in a particular process. It is a macroscopic description of your process estate, rather than a grouping of isolated processes. There is a goldmine of process data available to use. An elegant adoption of Blueworks Live with full harnessing of the data contained in your Blueworks Live account gives you the following benefits: governance checking, dashboards, the power to build process reports such as RACI matrices and customized SIPOC reports, and the ability to rank and quantify processes for investment optimization.
In addition, integrating this data with other system data makes Blueworks Live a cog in a wider enterprise architecture engine. Combining previously disconnected systems and their previously segregated data builds organization-wide consensus on business terminology and nomenclature. For an autonomous process without painful management, interacting with the information in Blueworks Live extends past the user interface that end users see.
Information from Blueworks Live needs to be shared with the other pieces of the enterprise architecture puzzle, and so you find that you need tools for system-system integration, and methods for mass information extraction and consolidation. These tools already exist but are often underused. Blueworks Live has an extensive set of APIs that you can use to make information and services from Blueworks Live available to other applications in your organization.
This article explains what the APIs offer, how to use them, and above all, why we should all be using them.
A complete approach to using the process estate data in Blueworks Live
What value can you extract from Blueworks Live and why should you care? Leaving your data locked up in Blueworks Live is fine. However, getting that data out to populate other artifacts, or for various analysis activities, is a huge help to your business.
Before addressing how to using data outside Blueworks Live, consider why you want to. Review the follow five examples from Blueworks Live customers that show what you can achieve with a complete approach to using the process estate data in Blueworks Live.
1. Governance checking use case
In a collaborative environment, it is sometimes unclear when a process is fully modelled and ready for publishing. Many editors work on the process, and it has no root owner. Therefore, no user has the omniscience to know if a process is ready to publish and share with the viewer community. Also, most organizations have a formal governance procedure to publish a process, which includes various checks that need to be completed by various individuals to ensure the process is ready.
For example, "Is the process fully documented?" is an obvious question to ask, but not an easy one to answer. What are the criteria for a process to be fully documented? The answer is likely subjective, different for each reviewer.
By exploring and consuming the process blueprint data, you can design a structured system based on custom criteria to review the level of documentation on a process. You can extract this data and analyze it in Microsoft Word, for example. You can design a template of Microsoft Excel formulas to calculate metrics such as the following examples:
- Length of process description
- Percentage of activities that have a non-empty documentation sections
- The presence of certain tags
- The ratio of specific activity types to the default normal activity type
- Percentage of activities with defined inputs/outputs
- Percentage of activities with defined cost and other properties
Every metric can count toward a process completeness score, and to be approved for publication, a process needs a particular completeness score. You can build a reliable and consistent governance checking system quickly, to ensure a specific level of completeness for your published processes.
2. User administration use case
A big challenge for larger teams is managing Blueworks Live user licenses. Arduous and costly tasks include keeping on track with provisioning new users who request access to Blueworks Live, and de-provisioning users who are no longer using it.
A common practice is to email users individually to ask if access is still required (and rely on the honesty of their responses), then de-provision user accounts manually through the user interface and reallocate the licenses. This approach is inefficient and time-consuming.
What if you could make this process more autonomous by extracting the user login information and the user license information, and then building a system to automatically review user login rates and reallocate licenses to new requesters from non-active users?
For example, you can put a rule in place that if users don't log in for 2 months, they get de-provisioned. Or, you might use a more complex rule set such as a minimum login count over a rolling period (to stop the "I should log in today to keep my license" mentality). Even better, if the system provisions the new user account automatically, the Blueworks Live administrators are saved from needing to individually provision and de-provision users through the Blueworks Live user interface. This approach can speed up administrators' work, especially when batch provisioning is needed! This kind of autonomous or assisted user management can bring significant savings to Blueworks Live maintenance costs.
See Blueworks Live Bulk User Registration on GitHub at BwlSamples/BwlBulkRegistration
3. Process-level custom reports use case
If the process is documented with the required supplier, input, process, output, and customer (SIPOC) information, Blueworks Live automatically generates a SIPOC report for each process. Blueworks Live default capabilities don't include creating custom reports to suit specific needs, or creating a responsible, accountable, consulted, and informed (RACI) matrix. However, all the information for a report is in the tool, it’s just a question of getting it out and putting it into the appropriate format. For example, other activity properties are synonymous with the RACI properties (for example, Participant=Responsible and Experts=Consulted). If theses properties aren't aligned to meet your needs, you can simply create some custom properties.
After the data is entered into Blueworks Live, the trick is getting it out and building the required resources. A simple example is the Excel export of a Process Blueprint, which gives a comprehensive pull of the data in a process. You can create a template Excel sheet that you can paste in as an additional sheet to the exported report. Then, build the custom report for each process by taking the appropriate values from the export.
Process analysis in Blueworks Live covers the most common needs, but it naturally focuses at the process level. How can you easily see and consume account-wide information, such as the number of processes with a specific tab and the number of uses of a specific policy without having to navigate around the Blueworks Live user interface at a granular level? The data required is in Blueworks Live, but the analysis and navigation are not optimized for the macroscopic level: The user interface focuses on displaying the information at a process level, but it is not easy to see a wider, end-to-end process view of the data.
One answer to this problem is account-level dashboards. By pulling the data out of Blueworks Live, then building custom dashboards (using existing technology) on top of the data, you can visualize the data for easy exploration at the process estate level. The following dashboard is similar to one currently in operation for a large UK organization that uses Blueworks Live. The dashboard gives helpful visualization and easy navigation of a large amount of data, ranging from the number of artifacts and users, to the number of processes using a certain tag or property value.
With this approach you achieve low effort, up-to-date dashboards for process estate analysis, which clearly become a valuable tool for process analysis and process improvement.
5. Quantifying and ranking processes use case
If an organization is using Blueworks Live, it is likely that the organization undergoes some kind of process transformation, which maps as-is processes to discover how tasks are run at the moment and then maps to-be processes for how they are addressed in the future. To help determine which processes to focus your transformation efforts, quantify the business benefit for improving a particular process, relative to the other processes in the estate. Naturally, there are some processes that are more efficient than others, but some processes are faster and cheaper to redesign and improve than others. To decide which process provides the best benefits versus cost and time is challenging.
You can use extensive data contained in process documentation to help rank processes relative to each other based on custom criteria and then create a short list for closer scrutiny. Select your criteria, rank them by importance, and compare them. Blueworks Live offers several metrics you can use to determine the cost and importance of a processes: common properties such as cost, number of participants, systems, number of linked processes and less frequently used properties such as number of process changes, number of process updates, and process creation date. You can use other metrics to decide which processes are currently inefficient, such as value add, inputs/outputs, and risk. By harnessing this data and doing some comparative analysis, you can highlight processes that are best choices for transformation.
For example, imagine that you have a budget to improve two processes in your process estate. One of the first criteria to consider might be the size of a process. The definition of process size can vary by industry. Financial services organizations might determine size of as the number of participants of a process. Retail organizations might consider size as volume of inputs and outputs per process. Both of these examples use data that are included as documentation properties in Blueworks Live. You can determine which processes your organization considers the largest in your estate simply by exporting a short list of processes and sorting on the documentation properties. The following illustration shows a blank space representing your process estate, with processes shown as circles of ranging sizes to represent the size property:
Consider further comparisons to add to this image. The following table gives more examples of ways of using Blueworks Live data to rank your processes to focus your optimization effort:
It is difficult to determine how to compare these orthogonal variables against each other. Is the stone as heavy as the string is long? This is a tough problem, and there is always some guesswork when weighing these factors against each other. However, if you take educated guesses at the relative weight between these variables, you can draw basic ("T-shirt size") estimates that have practical benefit. Keep in mind that the aim here is not to identify an absolute list of where to put your transformation budget. Instead, this technique identifies a short list, and you can conduct a more detailed expert analysis on the list to arrive at a conclusion.
If you want to add other variables to this diagram, rather than using further concentric circles, pick a visualization that is non-comparable with area size, such as color, or border thickness. This approach best illustrate the problem. Eventually you might arrive at an approach that looks like the following diagram:
Even at this gross level of simplification, you can start building estimates of which processes are stronger candidates than others for optimization. At first look, when just comparing process size, the bottom two processes in the diagram are the clear choices. Now that you built out the picture further, the top middle process seems like a better option.
This work is just a diagram. But it represents an approach that is very achievable with correct data extraction and consumption from Blueworks Live. Perhaps the easiest, most familiar tool for this kind of analysis is Excel. After you get the data from Blueworks Live, you can get it into a sensible structure in Excel. Then start your ranking analysis by assigning weights to each criterion and calculating an overall optimization benefit for each process.
Can you take a more elegant approach? Part 5 in this series explores the art of the possible, and gives an example of a custom-built web application that builds helpful visualizations based on data extracted from Blueworks Live. The previous figure is simply a diagram, but Part 5 presents an operational version, not too dissimilar.
With proper consumption of the data in Blueworks Live, you can gain powerful insight, and in less time you can draw conclusions that are more profound. The question for all of the examples above is "How do I get the right data out of Blueworks Live as efficiently as possible?"
Ways to extract data from Blueworks Live with APIs
The earlier parts of this article simply describe the concepts. Now consider the practical ways to extract data from Blueworks Live.
The most obvious method is to use the various Excel exports through the Blueworks Live user interface, then consolidate the data into Excel and complete your analysis. This approach is feasible, and certainly worth the effort, but not the most elegant option. There is a fair amount of information available in Blueworks Live that you cannot access through the user interface, and some of the information in the space and in process exports might not be needed. This approach is not the most efficient way to consume and gain insight from the Blueworks Live data.
Blueworks Live has an extensive set of REST APIs that you can use to get data from or push data to Blueworks Live, without using the Blueworks Live user interface. The advantage is that you can access information much faster if you know what it is that you want to get from Blueworks Live. Also, some data is only available through the API, so this approach increases the total amount of information available to consume. The data available from the API library include user management, group management, artifact details, file management, work management. You can retrieve or edit essentially all of the information that sits inside a Blueworks Live account. The APIs are a powerful tool for extending the value of the data in Blueworks Live outside of the Blueworks Live account. For example, all the use cases previously described use APIs partially or wholly for interaction with the Blueworks Live data:
-
For governance checking, you can use the Blueworks Live APIs to retrieve only data you are interested in, rather than a generic Space export or Process export. And, you can retrieve it much faster than logging in to Blueworks Live and navigating to a particular space or process.
-
For user administration, you can use a selection of Blueworks Live user management APIs to retrieve user information such as login dates and license types of users. Also, you can de-provision a license from a user or provision to another. Using the APIs, you can build a system that runs autonomously and provisions and de-provisions users for your organization based on last login dates. This system automates vast amounts of the traditionally manual process and removes the need to individually email users to assess their continued business need for the tool. This approach allows for batch provisioning and de-provisioning rather than processing each user change individually through the UI.
-
For custom extensions of SIPOC diagrams or RACI matrices, you can use a Blueworks Live API for process exports, which can be much faster, especially if you are requesting multiple exports at one time.
- For dashboards, you can create many space exports through the Blueworks Live user interface and then consolidate the data, but this approach requires exporting a large amount of data from Blueworks Live and inserting into the dashboard tool. To compound this, after the data is taken out of Blueworks Live, it is static, not live. Frequent repeated exports are required to ensure the data in the dashboard is reliable, which could quickly become a burden if this data needs to be exported manually each time.
However, if you call the APIs programmatically you can automate the process of exporting the data (and potentially get the data in a format and location required for the dashboards). For example, a small script that sits on a job scheduler can run periodically without human involvement, calling the Blueworks Live API to collect large amounts of data, such as a process export for each process in the account. Then the script can transform the results and store them in an appropriate location. Also, you can ensure that when working with the high volume of data you don't export data that you don't need. This approach maximizes the efficiency of data extraction. By using APIs, you can cherry-pick the specific data you want.
- For quantifying and ranking processes, similar to preparation of dashboards, you can select the exact data that you require (based on pre-defined custom criteria), and then pull that data out using APIs. You are then ready for the analysis, without navigating through the Blueworks Live user interface and without the overkill of space and process exports.
APIs are optimized for use with system-to-system communication. They are really powerful when used as part a of an automated system, such as a custom-built application, where the APIs can be called programmatically and iteratively. Then you can configure the application to combine multiple API responses and present them in visually helpful formats to all users. The sky is the limit.
Patterns for using Blueworks Live APIs
Now, consider ways to jump in and get started. You might have experience with process modelling and Blueworks Live, and you might be a business analyst, perhaps not with deep IT skills or an understanding of how to leverage APIs. Blueworks Live is inherently a business tool, an as-a-service offering, so there is no usual need to leverage IT teams for either deploying or using Blueworks Live. Business users might face a dilemma that they want to be able to use the APIs for some of the advantages described listed above, but don't know how.
This series of articles gives you all you need to know to become a Blueworks Live API expert, whether you are experienced working with APIs or not. The series covers which tools to use and examples of API requests. There are three main patterns for using Blueworks Live APIs:
1. Through a local script, program, or local REST tester
The following figure shows this first pattern.
In this first pattern, you make an API request from a local machine to pull data from the Blueworks Live cloud and save it locally. You can accomplish this approach in one of two ways:
- A local REST tester program such as Postman or SoapUI that allows one-off API requests and displaying responses through a helpful user interface to avoid the need to write code. See Part 2 of this series.
- A custom script or piece of code that makes single or multiple API requests, collects the responses, and saves them in some form to a specified location. This script can be executed manually, or set to run on a designated periodic basis. See Part 3 and 4 of the series.
Both methods have use cases. The REST tester tests the correct use of an API before building it into a script, and also makes one-off calls on a case-by-case basis to collect information that is slower to collect or not available via the UI. Examples include accessing user activity information, searching and collecting data for a specific artifact, and downloading a specific process PDF or BPMN2.0 file.
The script method has the advantage of making multiple API requests, or the same API request multiple times with only one execution of the script. This method is great for batch tasks, such as batch provisioning or de-provisioning licenses based on last login date, and collecting and storing .xls exports for all spaces in an account.
2. Through an application
This pattern pulls data from Blueworks Live and pushes it into a pre-built application, either running locally, or on a centralized application. Think of this pattern as an extension of the script method, where you have a custom-built application to make combinations of API requests. Then you extend this application by adding a custom user interface on top, which give all users various controls to decide which API requests or combinations of API requests they want to make, to see the API responses come through the user interface in a helpful visualization.
Think of it as some pre-configured recipes of bundled API requests and pre-designed presentations of the responses, that business users can access and trigger at will. Examples of this pattern include dashboards or quantifying and ranking processes that were previously described. You add helpful visualizations over the top of data collected from API requests, to allow business users to explore the data after it has been presented in helpful ways.
This approach also works great for many users who access a centrally hosted application. Especially if this application provides a web interface so that users only need their normal web browser like they do when working with Blueworks Live. This way they can simply stay in their familiar working environment and switch seamlessly between Blueworks Live and the extension application. The following diagram depicts the specific variation of this approach:
Part 5 of this series discusses a sample implementation and its details.
3. Through system-to-system integration
The final pattern is full system-to-system integration: data sharing through the APIs of the constituent systems, as shown in the following figure:
One system has a runtime environment that you can configure to make an API request to another system and consume the response. The process can go through an integration bus or an extract, transform, load tool, or it can be point-to-point. The result is an architecture of many systems that all share and consume each other's data. This approach allows for a truly consolidated business glossary, enforcing standardized and consolidated terminology across the many systems.
Blueworks Live specifically cannot make API requests to other systems because it has no runtime environment, but you can pull data from Blueworks Live and push it into another system through an integration bus or some other middleware architecture. This approach allows consolidated data, or a single version of the truth between different systems. For example, you can take user lists and glossary terminology periodically from Blueworks Live and share across an organization's enterprise architecture tool, allowing Blueworks Live to become a cog in a wider enterprise architecture engine.
Conclusion
This article described real use cases to show how you can extract maximum business value from your Blueworks Live process estate.
A large amount of information is added over the lifetime of a Blueworks Live account. Reviewing and consuming this information through the Blueworks Live user interface is very useful, with many advantages. However, you can greatly extend the advantages if you extract the information to use outside Blueworks Live.
You learned ways to create assets such as customized reports, RACI matrices, and dashboards, built by using Blueworks Live artifact data. You followed an example that accesses data to reduce administrator and management overhead. You also saw approaches for assistance with governance checking and identification of processes that are good candidates for improvement through extraction and analysis of data from the Blueworks Live environment.
This tutorial introduced the tool behind all the data collection and extraction: the library of Blueworks Live REST APIs that is available to Blueworks Live administrator users. The next parts in this series explore how to use the Blueworks Live API and demonstrate the power and potential of the patterns described in Part 1.
Go to Part 2 to continue.
Acknowledgements
The authors would like to thank Mark White and David Elliott of Barclays and Rolf Riedlinger of IBM for their review and comments on this article.
Downloadable resources
Related topics
#BlueworksLive
#processmapping
#RESTAPI
#processmodeling