Extending Workflow¶

This section of the documentation provides 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

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.

Note: Authentication for Workflow IFS Rest Connector requires the Workflow author to create and manage authentication manually. It does not support OAuth authentication to create tokens when calling external APIs.

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.

Workflow Templates can be added to the relevant component’s source following the file and folder conventions below. The 'isExecutable' attribute in the BPMN file should be set false for it to be identified as a system installed Workflow Template but it will not be deployed during the deployment phase. Further, if a non-template workflow exists within the system with the same process key, the new Workflow Template will be added with a prefix (i.e. TmpWorkOrder).

It is not recommended for R&D to ship Workflows having Entity service APIs via the IFS Applications installer. This is because Entity service APIs are de-active by default and fail deployment during the system Workflow deployment process.

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

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