Manage and Customize Workflows

Introduction

PIM Supplier Portal uses the workflow engine Activiti internally. By default the following processes are modeled as workflows:

  • Supplier Registration

  • Supplier Invitation

  • Data Upload Test Run

  • Data Upload Import Run

From a customization point of view there are two aspects:

  • Customize Workflow definition by changing the bpmn files

  • Interact with the workflow engine from external systems by using the workflow REST API

Both options are available starting with PIM 7.0.4

Customizing Workflows Definitions

All workflows used in PIM Supplier Portal may be overwritten by customized workflows. The property workflows.customizationFolderPath defines the location of the folder where the customized workflows are contained. The default location is

<INSTALLATION_ROOT>\configuration\workflows

Currently the following workflows can be customized:

Workflow

Filename

Purpose (default behavior)

Registration

registration.activiti.bpmn20.xml

Self registration of a user to PIM Supplier Portal if no account is there yet.

Invitation

invitation.activiti.bpmn20.xml

Invitation by Portal Admin to join PIM Supplier Portal.

Upload

initialDataload.activiti.bpmn20.xml

Data upload by supplier user. An initial test run is done with this data.
It is also later used for the actual import if the data has been approved by the portal admin.

Import

initialDataload.activiti.bpmn20.xml

Actual import of the data that has been uploaded in the upload workflow.

Note that the full file name is important, the file extension must always be .bpmn20.xml.

Changing a workflow definition

To change a workflow definition, simply open the bpmn20.xml file using your favorite XML editor.

You might also want to use the Activiti Designer in Eclipse. However, this editor (last tested with Activiti 5.14) doesn't support all XML elements that are used in the Supplier Portal workflow definitions ("extensionElements" in particular). Hence the Activiti Designer should only be used for viewing but not for editing workflows.

Changing a workflow definition could incorporate things like adding/removing specific tasks or adding additional flows. To add custom logic to a workflow definition, integrate a new service task. Within the service task you can either use activiti:class to specify a class that is instantiated and called by the workflow engine. As an (prefered) alternative, use activiti:delegateExpression to reference a Spring bean that is called. The latter approach is especially prefered if other parts of the application are needed because Spring's dependency injection can be used to acquire the necessary references.

Interact with Workflow Engine

PIM Supplier Portal exposes the REST API of the internal workflow engine Activiti. This gives external systems a great flexibility to monitor and interact with running workflows or to manage workflow definitions. A typical use case is to proceed (ie. "signal") a paused workflow instance.

The full documentation can be found at http://www.activiti.org/userguide/

By default, the Activiti rest interface may be accessed in using the following url :

http://localhost:9090/hsx/activiti-rest

Please change host name, port and web app name to your local environment accordingly.

Authentication for all rest calls is done using http Basic Authentication. Clients are required to specify username and password of an existing PIM user.

As username and password are not encrypted when using http Basic Authentication, the usage of SSL is recommended in production environments.

Example - Proceed a running workflow (receive task)

This example illustrates how a paused workflow can be continued ("signalled") using the Activiti REST API. This is done by using the call

POST /process-instance/{processInstanceId}/signal

as described in http://www.activiti.org/userguide/#N160BB.

The authenticated user is "portal/portal".

Request Header
POST /activiti-rest/process-instance/4e65e489-7c38-11e3-a7c0-6c88140eb6d0/signal HTTP/1.1
Host: localhost:8888
Authorization: Basic cG9ydGFsOnBvcnRhbA==
Cache-Control: no-cache
Request Body (JSON)
{
"activityId":"approveInMDM",
 
"supplierApprovalState":"reject",
"supplierApprovalReason":"Missing bank account."
}

The parameter activityId is reserved in that context and must not be used for any other variables. The value is the name of the receive task that should be signaled. For example the activityId would be "approveInMDM" if the corresponding element in the activiti bpmn xml looks like this:

<receiveTask id="approveInMDM" name="Wait for approval in MDM" />