Integrating a workflow with external web services

Written by Peter Hilton | 6 min read
Published on: April 21st 2017 - Last modified: November 13th, 2020
Workflow Integration - man with four arms sitting in front of a laptop

A systems integration tutorial that shows how to use a script task in an approval workflow to fetch data from another system

Sooner or later, workflow automation leads you to workflow integration. When you automate a workflow, you sometimes need information that’s only available in another IT system. For example, management approval workflows need to know which manager should approve each employee request, while a human resources (HR) IT system keeps track of each employee’s manager.

An HR system can provide a service that lets other systems look up information about an employee, including who the employee’s manager is. These services are called ‘web services’ because systems access them via a URL (like http://hr.example.com/employee?email=ben@example.com) in the same way that you load a web page in your web browser.

This article shows you how one approach to workflow integration with an example HR web service. This article is intended for people who implement workflows and who want an overview of what’s involved in web services integration, even if someone else will actually do the implementation. This article also includes the code that the integration uses.

Assigning a process role to a manager

You may need workflow integration for even the simplest business process, such as a basic vacation request process. For this example, consider a vacation request process that contains a single ‘Approve Request’ task for the approval decision, following by result notifications.

This process defines one role: the ‘Manager’ who completes the approval task. In Signavio Process Governance, you can define this ‘Manager’ under ‘Assign using a role’ on the user task’s configuration panel.

The consequence of this role assignment is that for each separate vacation request, someone will take the ‘Manager’ role. In workflow automation terms, Manager is a process variable whose value will be a workflow system user. Note that being a vacation request Manager is like being a meeting’s chairman - the next one will be someone else.

When you automate the vacation request process, it turns out that the workflow system knows who submitted the request but not who their manager is. In Signavio Workflow, the person who who submits the trigger form is called the ‘Case Creator.’ What you need is a way to work out who the case creator’s manager is in your organisation.

Using a web service to look up the employee’s manager

When a vacation request workflow needs to determine who an employee’s manager is, the workflow system will have to request the information from an HR system. You might want to copy the employee-manager information to the workflow system somehow, but a workflow automation system isn’t designed to work as a database. Besides, if you did that, you’d have a new (and harder) problem: how to keep the data in sync with the HR system.

Another approach to workflow integration, for this example, is to fetch up-to-date employee information from the HR system for each vacation request. In web services terms, the HR system provides an employee information web service that you can query.

Web service API specification

For this to work, the employee information web service will respond to the following HTTP request for employee information, which identifies an employee by email address:

GET http://api.example.com/employee?email=ben%40example.com

The HTTP response will be a JSON document that includes a ‘manager’ property, whose value is the manager’s email address:

{ "manager" : "alice@example.com" }

In practice, there may be other properties in the response that provide more employee information. This web service API will also require authentication, authorisation, and error handling, which are beyond the scope of this article.

Now you need to call this web service from a workflow.

Calling the web service from Signavio Workflow

In general, a business process can use script task or a service task to run code that can request information from an external web service. In Signavio Workflow, you use script tasks called ‘JavaScript actions’ for workflow integration.

In the vacation request process, you can add an ‘Assign manager’ JavaScript action at the start of the process. This script task will use the employee information web service to determine the case creator’s manager, and assign the Manager role to the right person before creating the ‘Approve request’ task.

Select the ‘Assign manager’ to open the JavaScript action configuration. In the process variable table, select the built-in ‘Case’ variable and the ‘Manager’ role variable to make them available to the script.

In the script code area, enter the the following JavaScript (EcmaScript 2016) code:

const users = require('users')

const requestOptions = {
  uri : 'https://api.example.com/employee',
  qs : {
    email : _case.creatorId.emailAddress
  }
}

const assignManager = (error, response, body) => {
  if (error) {
    console.log('error: ' + error);
    return;
  }
  const managerEmail = JSON.parse(body).manager
  manager = users.findByEmail(managerEmail)
}

request.get(requestOptions, assignManager)

The last line uses the request library to send the HTTP request. The assignManager function extracts the manager’s email from the JSON response and uses the users library to look up the corresponding Signavio Workflow user. See the JavaScript integration documentation for more information about these libraries.

Now you can publish the process and start a new case to run the code. You can submit a vacation request to see the automatic Manager role assignment in action.

Running the code

The vacation request workflow starts with a trigger form that an employee uses to request vacation, by completing ‘Start date’ and ‘End date’ fields.

After you start the case, Signavio Workflow shows the case details view, which provides an overview of the vacation request.

On the right, starting at the bottom, the event stream shows that Peter created a vacation request for a week in June, after which the ‘Assign manager’ script was executed. Next, the ‘Approve request’ task was created.

On the left, the task list contains the ‘Approve request’ task. The avatar shows that the task is assigned to Alice, Peter’s manager. Meanwhile, Alice will have received an email notification that a new ‘Approve request’ has been assigned to her.

Workflow integration

Even the simplest business processes can require some systems integration. Workflow integration is always an issue in practice, sooner or later. Some data belongs in external systems and may participate in multiple business processes.

Web services integration is a common approach to systems integration, based on HTTP. Signavio’s JavaScript actions let you use standards-based technology for workflow integration, which results in straightforward implementation using commodity skills.

If you would like to try workflow integration for yourself, sign up for a free 30-day trial of Signavio Workflow

Published on: April 21st 2017 - Last modified: November 13th, 2020