> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add new workflows

> How to add new workflows to Atoti Limits, covering workflow file creation, process extension configuration, Spring beans for service tasks, YAML for user tasks, and recommended design patterns

## 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](https://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.

<Tip>
  Defining the BPMN file is often the most challenging part. If your workflow becomes hard to
  follow, consider simplifying it
  using [our recommended patterns](#what-patterns-do-you-recommend-when-designing-workflows).
</Tip>

***

## 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:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "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 `startEvent`s, `userTask`s, `serviceTask`s and `sequenceFlow`s
  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:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Bean
public Connector trebleVariableValue() {
  return integrationContext -> {
    final Double currentValue = integrationContext.getInBoundVariable("amount", Double.class);
    integrationContext.addOutBoundVariable("amount", currentValue * 3);
    return integrationContext;
  };
}
```

<Tip>
  The `Connector` beans have access to the Spring context, which means you can inject other Spring
  beans into them which can be used for the service task logic.
</Tip>

***

## 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`