Guideline for the creation of process models and their deployment to yuuvis® Momentum.

Introduction

The process definitions for BPM Engine are modeled locally via Flowable UI and deployed to the BPM Engine afterwards. For the deployment, the internal API of the BPM Engine itself has to be used. It can be made available for authorized users via configuration of the AUTHENTICATION service or via port forwarding.

Process Definition

The process modeling requires the local installation of Flowable UI. A detailed description of the installation and usage is provided in the Flowable documentation linked below.
>> Flowable UI Documentation

By means of the Flowable UI, create your process definitions and group them in an application.

As of version 2021 Winter, Flowable Http tasks can call internal yuuvis® Momentum endpoints. In order to add the yuuvis® Momentum authentication headers that are required for internal requests, set the placeholder %%YuuvisSystemInternal%% for the 'Request header' configuration parameter. If Http task is used to call external methods, this option should not be used. Other headers can be added as desired and required via the modeler.

Publish your application including your new versions of process definitions and export it in BAR or ZIP format.

The BAR format is the primary format for deployment that includes Flowable-specific pre-defined forms (not supported by a library-based client) that will be deployed in the BPM Engine. This may be of interest for custom clients that are using and supporting forms in Flowable format. Unfortunately, this format is a pure deployment format and cannot be imported back to Flowable modeler.

The ZIP format will be also accepted by BPM Engine, and can be reimported to a Flowable modeler as well. The Flowable-specific forms are included but will not be deployed by the Flowable BPM Engine.

Process Deployment

The exported application from the Flowable UI has to be imported to BPM Engine via its internal API. The corresponding endpoints can be configured in the file authentication-prod.yml to be accessible via Swagger UI for users with a specified administrative role. In productive systems, the internal API should not be accessible for yuuvis® Momentum users. Instead, you can use the internal REST interface of BMP Engine via port forwarding. Thus, the Swagger UI can be used only by Kubernetes administrators. Alternatively, you can also use a different tool of your preference, such as cURL.

Deployment via Swagger UI

In order to use the internal BPM Engine endpoints via Swagger UI, the following configuration is required to be added in the configuration file authentication-prod.yml under authorization.accesses. The access will be managed by the AUTHENTICATION Service and has to be limited to users with a specified administrative role.

- endpoints: /bpm-engine/swagger-ui.html,/bpm-engine/swagger-ui/**,/bpm-engine/v2/api-docs/**,/bpm-engine/v3/api-docs/**
- endpoints: /bpm-engine/internal/**
  access: hasAuthority('<role>')

If the configuration is applied and the logged-in user is authorized, the Swagger UI is available via the URL https://<host>/bpm-engine/swagger-ui.

• Select the Internal Flowable App Rest API from the dropdown menu in the top bar.
• In the App Deployments section, click the POST /app-repository/deployments endpoint.
• Click Try it out.
• Type the ID of the tenant to which you want to deploy the new process definitions.
• Select the exported Flowable application from your file system.
• Execute the API call.

It is also possible to use the internal REST interface of the BPM Engine for the deployment of new process definitions without enabling user web access. Since those endpoints are accessible only for services within the yuuvis® Momentum cluster, port forwarding is required for the access to the Kubernetes pod for the BPM-ENGINE service.

Deployment via cURL

If Swagger is not activated in a system, process definitions can be deployed by other means, such as for instance cURL. The same access configuration rules apply as described before. In the following steps, replace the <*> terms by your specific values.

• Create a deployment. The following command deploys the exported Flowable application to the BPM Engine instance.

  curl -u <username>:<password> -F 'upload=@\"<PATH TO THE APPLICATION .zip OR .bar FILE>"' -X POST "https://<HOSTNAME>/bpm-engine/internal/process-api/repository/deployments?tenantId=<tenantId WHERE THE APPLICATION IS TO BE DEPLOYED>" -H "accept: application/json" -H "Content-Type: multipart/form-data" -H "X-ID-TENANT-NAME: <tenantId WHERE THE APPLICATION IS TO BE DEPLOYED>"

• Retrieve the deployments in order to check whether the deployment was successful.

  curl -u <username>:<password> -X GET "https://<HOSTNAME>/bpm-engine/internal/process-api/repository/deployments?tenantId=<tenantID WHERE APPLICATION WAS DEPLOYED>" -H "accept: application/json" -H "X-ID-TENANT-NAME: <tenantID WHERE APPLICATION WAS DEPLOYED>"

• List the deployed process definitions. The command retrieves a list of your available process definitions.

  curl -X GET "https://<HOSTNAME>/bpm-engine/internal/process-api/repository/process-definitions?tenantId=<tenantID WHERE APPLICATION WAS DEPLOYED>" -H "accept: application/json" -H "X-ID-TENANT-NAME: <tenantID WHERE APPLICATION WAS DEPLOYED>"

• From the retrieved list of process definitions, choose one process definition you want to use to instantiate a process. For the process creation, you can specify the process definition by its ID. Note that if you specify the ID of an older version of a process definition, this old version will be used for the instantiation of your process.
  Alternatively, you can refer to a process definition by specifying its processDefinitionKey as shown in the command below. In this case, the current version of process definition will always be used for the process instantiation.

  curl -u <username>:<password> -X POST "https://<HOSTNAME>/bpm-engine/internal/process-api/runtime/process-instances" -H "accept: application/json" -H "Content-Type: application/json" -d "\{ \"businessKey\": \"myBusinessKey\", \"name\": \"myProcessInstanceName\", \"processDefinitionKey\": \"<PROCESS DEF KEY TO BE STARTED>\", \"returnVariables\": true, \"tenantId\": \"<tenantID WHERE APPLICATION WAS DEPLOYED>\"}" -H "X-ID-TENANT-NAME: <tenantID WHERE APPLICATION WAS DEPLOYED>"

Custom Functionality Extension

As of version 2022 Winter, it is possible to add custom functionality to process definitions that is not supported by Flowable, e.g., notifying a logger. The custom extension is integrated as delegation in service tasks or event listeners.

Dependency

Create a new project. Inject the flowable-engine dependency.

<dependency>
    <groupId>org.flowable</groupId>
    <artifactId>flowable-engine</artifactId>
    <version>6.7.2</version>
    <scope>provided</scope>
</dependency>

Java Implementation

The class with your custom extension has to implement the JavaDelegate Flowable interface as shown in the example below.

package my.company;

import org.flowable.engine.delegate.DelegateExecution;
import org.flowable.engine.delegate.JavaDelegate;

import java.util.logging.Logger;

public class LoggerDelegate implements JavaDelegate {

    private static final Logger log = Logger.getLogger(LoggerDelegate.class.getName());
    
    public void execute(DelegateExecution execution) {
        log.info("\n\n  ... LoggerDelegate invoked by "
          + "processInstanceId=" + execution.getProcessInstanceId()
          + ", processInstanceBusinessKey=" + execution.getProcessInstanceBusinessKey()
          + ", processDefinitionId=" + execution.getProcessDefinitionId()
          + ", activityId=" + execution.getCurrentActivityId()
          + ", flowElementId='" + execution.getCurrentFlowElement().getId() + "'"
          + ", flowElementName='" + execution.getCurrentFlowElement().getName() + "'"
          + ", executionId=" + execution.getId()
          + " \n\n");
    }
}

Extension of BPM-ENGINE Image

Compile your project and copy the JAR into the /yuuvis/libs BPM-ENGINE library folder.

You can use your custom Java class in your process definitions now.