Adding new workflows

How do I add new workflows?

To add a new workflow to Atoti Limits, follow these steps:

1. Create your BPMN file.
2. Create a <process-id>-extensions.json file.
3. Write Spring beans for your service tasks.
4. Define YAML for your user tasks.

How to create a BPMN file

You can create a BPMN file in two ways:

• Modify an existing BPMN file: Recommended only if your workflow is similar to an existing one.
• Create a BPMN file from scratch: Use a BPMN editor or generate the XML manually.

How to create a BPMN file from scratch

A BPMN file is an XML document. Here are recommended steps to create one:

1. Generate a skeleton using an AI agent
   Example prompt:
   “Create a BPMN file for a four-eyes breach approval process that automatically sends a notification after the second approval. Include BPMN diagram tags."

2. Use a BPMN editing tool
   Tools like bpmn.io help you visualize and edit the BPMN file.

3. Ensure the process is executable
   Include isExecutable="true" in the <process> tag.

4. Define implementation for service tasks
   Each <serviceTask> must include an implementation attribute. The value should match the name of a Spring bean in your application.

What is a <process-id>-extensions.json file?

This file tells the Activiti engine how to handle custom elements and attributes not defined in the BPMN 2.0 schema. In Atoti Limits, it mainly controls which variables are included or excluded at different workflow stages.

How to create a <process-id>-extensions.json file

Use the following format:

{
  "id": "PROCESS",
  "name": "PROCESS",
  "extensions": {
    "<process-id>": {
      "properties": {},
      "mappings": {
        "<activity-1-id>": {
          "mappingType": "MAP_ALL"
        },
        "<activity-2-id>": {
          "mappingType": "MAP_ALL"
        }
      },
      "constants": {}
    }
  }
}

where:

• <process-id> is the process id in the BPMN file
• <activity-X-id> is the id of all startEvents, userTasks, serviceTasks and sequenceFlows in your workflow

You will need to create a file that follows this format and place it in the same location as your BPMN file.

How do I write Spring beans for my service tasks?

Service task beans must implement the org.activiti.api.process.runtime.connector.Connector functional interface and be named to match the implementation attribute for the service task in the BPMN file. For example, if you wanted to treble the value of a numerical variable for the next step in the workflow, you could do the following:

@Bean
public Connector trebleVariableValue() {
  return integrationContext -> {
    Double currentValue = integrationContext.getInBoundVariable("amount", Double.class);
    integrationContext.addOutBoundVariable("amount", currentValue * 3);
    return integrationContext;
  };
}

What patterns do you recommend when designing workflows?

Here are useful patterns for designing BPMN workflows:

1. Use service tasks around user tasks
   Implement logic before or after user decisions to keep the BPMN file clean.

2. Keep task names concise
   Add descriptions to clarify each task’s purpose.

3. Use workflow variables
   Pass data between tasks using variables to isolate workflow logic.

4. Use multi-action user tasks
   Instead of separate Approve and Reject tasks, define one Review task with both actions.

What if my workflow does not apply to limits or incidents?

If your workflow does not apply to limits or incidents, you can still create the workflow using the aforementioned approach. You will just need to manually start the workflow and execute the user tasks throughout the code. This can be done by injecting IWorkflowService and calling:

• IWorkflowService::startWorkflow
• IWorkflowService::executeUserTasks