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

# General principles

> Overview of the architecture and object model for Atoti Sign-Off workflow customization, covering object management, workflow services, REST controllers, and utility methods.

This page provides details of how the customizable workflow objects are
set up in Atoti Sign-Off.

## Starter module

The `signoff-starter` maven module is designed to be the starting place
for most customizations. Some more advanced customization may also need
to change the `signoff-activeviam` maven module.

## Object management

The Module is built around managing server-side objects as they
progress through Business Process Management (BPM) workflows.

In Atoti Sign-Off there are two types of objects being managed:

* Sign Off Process Definition
* Sign Off Process Instance

Each object type, comes with:

* JPA Entity and DTO implementations of the object (sharing a common interface)
* A service for managing the persistence of the DTO objects, backed by a JPA repository.
* A Workflow Service that interacts with the Activiti workflows to manage the DTO objects.

  The workflow service provides methods aligned to the actions within the workflows. Hence it is expected that the workflow service will
  be customized alongside the workflows.

See [Customizing the sign-off backend](./custom-workflow-backend)

### Activiti workflows

The BPM Process Engine used in the Module is Activiti. It reads
definitions from .bpmn files and is able to manage workflows based on
these definitions.

For each object type there can be multiple workflows that can be used
for managing the objects. These are all defined in the .bpmn files.

For details on working with .bpmn files, see the [Activiti documentation](https://www.activiti.org/userguide/)

### Workflow service

The Workflow Services provide an interface into the Activiti workflows.
The workflow services implement interfaces that are used to control the
workflows, these interfaces contain two types of methods:

* **Start workflows**

  Examples:

  * Create (sign-off process definition)
  * Initiate (sign-off process instance)
* **Send user actions to the workflows**

  Examples:

  * Publish (sign-off process definition)
  * Approve (sign-off process instance)

Additionally, the workflow services contain Spring beans that can be called from within workflows to implement service tasks.

#### Utility methods

A few utility methods are provided to help implement the two method types above.

| Method              | Description                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| startProcess        | Starts a new Activiti process instance.                                                             |
| taskStateTransition | Sends a user action to the workflow instance so that the workflow can transition to the next state. |
| signalEvent         | Sends a signal to the workflow.                                                                     |

#### REST controller

Thin wrapper around the workflow service. The REST API matches the API in the workflow service, and all REST calls are passed straight through to the service.

The UI can use the REST API to start processes and send user actions to the workflows.

For example, the **Approve** button in the UI,
will call the `execute-task-action` REST endpoint on the sign-off process instance REST Controller with `taskKey: "Approve"`, which will call the `approve` method on the sign-off process instance workflow service, which will send the `approve` action to the workflow.