Skip to content

Workflow Architecture

Overview

How Workflows Fit within IFS Cloud?

The majority of the workflow logic resides within the middle-tier through tight integration between the Camunda Workflow Engine offering and the IFS oData provider. Wrapping every oData transaction, the lightweight communications between the components come to life when Event Actions are triggered within the IFS Event Framework or Projection Actions are performed within an IFS Projection.

WorkflowArchitectureDiagram

How Workflows are processed?

SuccessScenario

FailedScenario

How Cascade works?

CascadeWorks_1

Figure: Diagram depicting the flow of Workflows being run with the projection action that triggered them.

The Workflow timings After and Asynchronous refer to when the Workflow is run relative to when the projection action that triggers the Workflows is run. "After" Workflows are run immediately after. "Asynchronous " Workflows have a listener that polls for the Asynchronous Workflows and runs each Asynchronous Workflow on its thread in the background.

While a projection action is being executed in the database it may call another projection or otherwise trigger an event without the middle tier’s involvement. In this case, we still want to run any Workflows that are linked to the additional projections that got executed. all the additional Workflows will get called after the additional projection has been executed. These additional Workflows are referred to as the cascading Workflows. After running any After Workflows that the original projection has a list of all the synchronous Workflows that were triggered is checked and any that haven’t been run are then taken care of. Any additional Asynchronous Workflows that got triggered will be picked up and handled the same way Asynchronous Workflows normally are.

Additionally, after an Asynchronous Workflow is run cascades are checked just in case the Workflow triggered projections or events with Workflows attached. The list of cascading Workflows is thread-specific so there is no concern with an Asynchronous Workflow accidentally running cascading Workflows before the main projection flow can get to them.

CascadeWorks_2

Figure: Diagram depicting the flow when a Workflow triggers another Projection. Note that in this diagram an After Workflow triggers the projection as an example; any Workflow could invoke the second projection or event.

In the case that the IfsProjectionDelegate is used in a Workflow then when that Workflow is run the projection will be called and handled before proceeding on with where the original flow was left off. This means if a Before Workflow calls the IfsProjectionDelegate then the projection it calls will be executed before the projection that originally invoked the Workflows. If an After Workflow calls IfsProjectionDelegate then the called projection will execute after the original projection. Asynchronous Workflows can also call the IfsProjectionDelegate and have the called projection happen in the background. If one of these nested projections is called then only its Before Workflows are executed. Any After Workflows will be picked up when looking for cascading Workflows. Only the original projection will search and run cascading Workflows. Asynchronous Workflows of nested projections will be handled the same as the original projection’s Asynchronous Workflows.

How Projection Reaction Works?

ProjectionActionWorks

Figure: Diagram depicting the flow when a Workflow triggers another Projection. Note that in this diagram an After Workflow triggers the projection as an example; any Workflow could invoke the second projection.

While a projection (Projection A) action is being executed, it executes the Workflow if there is a Workflow linked to this projection. If this Workflow invokes another Projection (Projection B) which is linked to another Workflow, then the second Workflow executes base on the Workflow timing.

For Before timing, the second Workflow executes before the second projection action while for After timing, the second Workflow executes soon after the second projection action.

For Asynchronous timing, the second Workflow executes in normal Asynchronous process.

Workflow Execution Order

There are two methods of invoking a Workflow. For more details about Workflow invocation methods, refer Invocation and Timing.

When a Projection action is triggered, Workflows which are associated with this projection and its triggering events, are executed in the following order base on the Workflow types and invocation methods.

WorkflowExecutionOrder

Figure: Diagram depicting the Workflows execution order when the projection action that triggered them.

Invocation and Timing

There are two ways of invoking a Workflow,

1. Projection Action

Projections are the endpoints exposed by oData provider for IFS Cloud. Currently users can easily determine the projections and their entitysets used within a page by enabling debug log. Once the Projection is determined, it can be linked to a Workflow through Projection Action configuration to trigger the deployed Workflow when the specific Projection action is performed within an IFS Projection.

Specifically, a Workflow could be linked to a Create, Read, Update or Delete operation using any entityset available within an IFS Projection. A Workflow may also be associated with the invocation of any action or function available in the Projection. For more details about Projection action, refer Workflow Tooling Projections section

ProjectionAction

Figure: Diagram depicting the flow of Workflows being run with the projection action that triggered them.

For more details about workflow types and timing, refer What are Workflows?.

2. Event Action

Events are stored in the database using the Event framework. An Event action with the type “Workflow” that is referenced to a custom event will allow the deployed Workflow to be invoked within IFS Cloud.

EventAction

Figure: Diagram depicting the flow of Workflows being run with the Event action that triggered them.

When an event action is triggered, the oData Provider prepares to execute the Workflow. The middle tier communicates with the database and logs the intent to execute the Workflow in the database. After the initial action, the Workflow is executed using the Camunda Workflow Engine in the middle-tier. Once the execution has been completed, the database session is checked to see if any other Workflows need to be executed. This sequence occurs within a single transaction. For more details about Event action, refer Workflow Tooling Events section

For more details about workflow types and timing, refer What are Workflows?.

Transaction Handling

Workflow type “User Interaction” is only supported in Projection action Workflow invocation method with Workflow timing “After”. When such Workflow got executed, it handles the transactions as below.

UserFromTransactionHandling

Figure: Diagram depicting how transactions are managed when invoking a User Interaction Workflow in Projection action Workflow invocation method.

Other Workflow types (Validation & Process Enrichment) Workflows with Workflow timing “Before” or “After” are utilized the same transaction when they got invoked by the projection action or event action. But Workflow with “Asynchronous” timing is executed in a separate transaction in separate thread.

Error Handling

During the execution of a Workflow, if an exception occurs then the entire transaction rollbacks and an Error is presented to the user. If a Workflow executes successfully but one of the cascading Workflow executions fails, then the entire transaction is rolled back.

ErrorHandling

For more details about IFS Failure Event, refer IFS Failure Event

IFS Failure Event (Validation Failure End Event)

The Workflow process must end with either End Event or Terminate End Event. Terminate End Event represents Failure and End Event represents Success.

IFS Failure Event requires the following input:

  • Locale (mandatory) - The input to specify the language of the Error Message.

  • Message (mandatory) - The input to specify the Error Message required.

For error handling in the BPMN diagram, there is a custom Terminate End Event called ‘IFS Failure Event’. Users can provide the error message that they want to show to the user in case of failure, or they can provide an error code. Below is an image from Workflow Designer for the IFS Failure Event.

FailureEvent

Generated XML

The generated XML will contain the following content for this IFS Failure End Event:

<bpmn:endEvent id="FailureEvent" name="Failure Event">
      <bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaValidationErrorMessages">
            <camunda:map>
              <camunda:entry key="en">Error Message</camunda:entry>
              <camunda:entry key="fr">Message d’erreur</camunda:entry>
            </camunda:map>
          </camunda:inputParameter>
        </camunda:inputOutput>
        <camunda:executionListener class="com.ifsworld.fnd.bpa.process.validation.IfsBpaFailureEndEventListener" event="end" />
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_1yiszw0</bpmn:incoming>
      <bpmn:terminateEventDefinition id="TerminateEventDefinition_0vfik34" />
    </bpmn:endEvent>

Note about the Error Code and Error Message: Users can provide error messages in multiple languages in the Workflow Designer tool. Users can also use the pre-existing error code by modifying the XML and providing the error code as ‘ifsBpaValidationErrorCode’ shown in the example below. Please note that ‘ifsBpaValidationErrorCode’ and ‘ifsBpaValidationErrorMessages’ are mutually exclusive so if the ‘ifsBpaValidationErrorCode’ is provided in the BPMN XML then ‘ifsBpaValidationErrorMessages’ parameter should not be present.

<bpmn:endEvent id="FailureEvent" name="Failure Event">
      <bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaValidationErrorCode">
            ${errorCode}
          </camunda:inputParameter>
        </camunda:inputOutput>
        <camunda:executionListener class="com.ifsworld.fnd.bpa.process.validation.IfsBpaFailureEndEventListener" event="end" />
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_1yiszw0</bpmn:incoming>
      <bpmn:terminateEventDefinition id="TerminateEventDefinition_0vfik34" />
    </bpmn:endEvent>

Deployment Validations

For more information about deployment validations, refer Deployment Validations.

Naming Conventions

The following naming guidelines are recommended when naming a Workflow (process key), version, and its components.

Naming Workflow

Workflow name, also known as the process key, is used to identify the Workflow in the system. Therefore, it should be a unique name by describing the business purpose in best possible manner.

  • Should be a camelCase name which the first letter of each word in a compound word is capitalized, except for the first word.
  • Should contains the prefix to indicate the business domain which use the Workflow.

Syntax: < prefix >< meaning name by describing the business purpose >

Example: If Human Capital Management (HCM) team uses a Workflow for handing training history, then Workflow name would be like this.

hcmTrainingHistory

Naming Workflow Version

There can be multiple versions for same Workflow. It should start with “version” prefix

Syntax: version_< Next sequence Number >

Example: If a Workflow has two versions already then, the next version should be like,

version_3

Naming the elements of Workflow

Workflow elements are the Camunda BPMN components use inside the BPMN diagram.

Element Type Guideline
Activities Name a task using an object and a verb in the infinitive.
Try to be more specific about what you do in your activity from a business perspective.

Example:
Check Invoice
Events Name an event by using an object and a verb reflecting a state.

Example:
Invoice Checked
Gateways Name the Gateway by using a question.

Example:
Invoice Correct?

Name the outgoing sequence flows by using the condition under which each of them is executed.

For more details about naming of Workflow elements, refer Naming BPMN Elements.