Skip to content

Extending Workflow

This section of the documentation is dedicated to providing more technical guidance to our users about using workflows.

Workflow REST API

REST API

As the Workflow engine is built upon the Camunda engine, the Camunda REST API can still be used to provide access to all relevant interfaces of the engine. Refer to the Camunda REST API link for details. This link explains all existing methods in the REST API. For each method it provides:

  • An informal description
  • HTTP verb and URL
  • Possible query, path, or message body parameters
  • A detailed description of the response content
  • Possible response codes
  • A brief example of requests and response

More links to Camunda API documents:

https://docs.camunda.org/manual/7.15/reference/rest/

https://docs.camunda.org/manual/7.15/reference/rest/process-definition/

https://docs.camunda.org/manual/7.15/reference/rest/process-instance/

Examples:

Action URI
Get List GET /deployment
Get List Count GET /deployment/count
Get GET /deployment/{id}
Create POST/deployment/create

REST Security

The REST Security is managed by Permission Sets granted directly or indirectly to the current user. Permission Sets are the basis for administrating authorities in the IFS Cloud. A Permission Set is a set of permissions that you can grant to users to give them the authority to perform tasks like view or update certain information. Refer to Permission Sets for more general information about Permission Sets and refer to Workflows for information about the process of granting Workflows to Permission Sets.

Figure: Below diagram depicts the different REST endpoint privileges that administrators and non-administrators have.

All actions are available to system administrators, however, non-administrators may only access process definitions or process instances for which they have been explicitly granted access. Non-administrators are also limited in scope to which actions they may take. They will still have the ability to use all of the GET actions on workflows, the ability to start instances of workflows as well as a couple of other things. However, they will have no ability to modify, delete, suspend or restart process definitions or instances. A list of all the REST endpoints non-administrators will not have access to has been included below.

Non-Administrator Exclusion List:

DELETE /process-definition/{id} DELETE /process-definition/key/{key}/delete DELETE /process-definition/key/{key}/tenant-id/{tenant-id}/delete

PUT /process-definition/{id}/history-time-to-live PUT /process-definition/key/{key}/history-time-to-live PUT /process-definition/key/{key}/tenant-id/{tenant-id}/history-time-to-live

PUT /process-definition/{id}/suspended PUT /process-definition/key/{key}/suspended PUT /process-definition/key/{key}/tenant-id/{tenant-id}/suspended PUT /process-definition/suspended

POST /process-definition/{id}/restart POST /process-definition/{id}/restart-async

DELETE /process-instance/{id} POST /process-instance/delete POST /process-instance/delete-historic-query-based POST /process-instance/{id}/modification POST /process-instance/{id}/modification-async

PUT /process-instance/{id}/suspended PUT /process-instance/suspended POST /process-instance/suspended-async

Authentication

User authentication is done by Keycloak. Keycloak is an open-source Identity and Access Management solution for modern Applications and Services. Keycloak runs as a standalone service deployed on its own. Refer to User Authentication for more information.

Connectors

Camunda provides an API called Camunda Connect which can be used to connect HTTP services. More information on the API can be found here.

A complete example can be found here on GitHub.


Custom Delegates

Custom Delegates allow external Java code to be executed when certain events occur during process execution. These can be used to access and wire business logic into the process.

Java Delegate

A custom delegate can be created by attaching a Java Delegate to a BPMN Service Task.

To create a class that can be called during process execution, the class must extend the com.ifsworld.fnd.bpa.config.TransactionalDelegate abstract Java class and provide the logic in the doExecute method. When the process arrives at the service task, it will execute the logic defined in the doExecute method.

Note that the classes referenced in the process definition are NOT instantiated during deployment. Some minor validation happens at deployment to verify that the given class exists and is an extension of the TransactionalDelegate class. However, no logic will be verified. During the process execution, an instance of the class will be created when the execution arrives at the point where the class is used for the first time. If the class has been moved and cannot be found, a ProcessEngineException will be thrown.

The following is an example of a Java class that changes the process variable input string to uppercase.

public class ToUppercase extends TransactionalDelegate {
    public void doExecute(ExecutionWrapper execution) {
        CamundaAttributeSet camAttrSet = execution.getCamundaAttributeSet();
        String var = (String) camAttrSet.getValue("input");
        var = var.toUpperCase();
        camAttrSet.setVariable(“input”, var);
    }
}

Service Task that used the ToUpperCase Delegate

Below is the XML generated for the service task:

<bpmn:serviceTask id="Task\_0shq7da" name="To Uppercase"  camunda:class="com.ifsworld.fnd.bpa.process.ToUppercase">  
      <bpmn:incoming>SequenceFlow\_0zqi4k7</bpmn:incoming>  
</bpmn:serviceTask>

For more information, please refer to the Camunda Documentation Link.

Execution Listener

Execution listeners can be used to execute external Java code when certain events occur during process execution. The events can be captured at the start or end of an activity.

To create a listener class that can be called during process execution, the class must extend the com.ifsworld.fnd.bpa.config.TransactionalListener abstract Java class and provide the logic in the doNotify method. When the process arrives at the service task, it will execute the logic defined in the doNotify method before the execution of the service task or after the execution of the service task depending on how you have configured the listener.

Note that the classes referenced in the execution listener are NOT instantiated during deployment. Some minor validation happens at deployment to verify the given class exists and is an extension of the TransactionalListener class. However, no logic will be verified. During the process execution, an instance of the class will be created when the execution arrives at the point where the class is used for the first time. If the class has been moved and cannot be found, a ProcessEngineException will be thrown.

The following is an example of a Java class that changes the process variable input string to uppercase before starting the execution of a service task.

public class ToUppercase extends TransactionalListener {
    public void doNotify(ExecutionWrapper execution) {
        CamundaAttributeSet camAttrSet = execution.getCamundaAttributeSet();
        String var = (String) camAttrSet.getValue("input");
        var = var.toUpperCase();
        camAttrSet.setVariable(“input”, var);
    }
}

Service Task that used the ToUpperCase Listener

Below is the XML generated for the service task:

<bpmn:serviceTask id="Activity_0od6rv1" name="To UpperCase">
  <bpmn:extensionElements>
    <camunda:executionListener class="com.ifsworld.fnd.bpa.process.ToUppercase" event="start" />
  </bpmn:extensionElements>
  <bpmn:incoming>Flow_0q8lg1a</bpmn:incoming>
  <bpmn:outgoing>Flow_01qndiv</bpmn:outgoing>
</bpmn:serviceTask>

For more information, please refer to the Camunda Documentation Link.


Code Deployment

Workflow / Delegate Deployment

Workflows, delegates, and associated configurations may be deployed manually using the user interface or automatically as part of the IFS Applications installer. This document explains the automated deployment mechanisms currently available; details for manual configuration and deployment of Workflows can be found here.

Automated deployments follow the Layered Component Architecture philosophy by bundling BPMN and Java Classes within the building home.

BPMN files should be located within the relevant component’s source following the file and folder conventions below. BPMN files will be validated each time the system starts during the deployment phase; as such care should be taken to ensure the BPMN file and system configuration are Valid.

Source Locations

•       \source\workflow\bpmn*.bpmn

Build Home Locations

•       \server\lob\bpmn\.bpmn

Java Delegates should be located within the relevant component’s source following the file and folder conventions below. Java code will be compiled as part of the build home bundling phase, so any external references must be included as a library. Base classes, including the Camunda runtime and the oData Workflow API, will be included in each compilation; Java Delegates must extend the TransactionalDelegate class to ensure the safety of the system.

Source Locations

•       \source\workflow\delegates\*.java

•       \source\workflow\lib\*.jar

Build Home Locations

•       \server\lob\bpa-impl\-bpa.jar

•       \server\lob\bpa-lib\.jar

Workflow Configurations can be encoded within database insert files. Lacking elegance, this approach will ensure a consistent base configuration for the system on each installation. Database data files should follow typical conventions and reside within the path below.

Source Locations

•       \source\database\Event.ins