# Worflow Documentation Talkdesk
###### tags: `Build-Measure-Learn`

## Introduction
Flowable is a business process engine written in Java, with many features that allow someone to manage several processes instances at the same time. The entire application can seem very complex at first, but we can look at it as a core engine with a colletion of services around it, that expose APIs to manage and execute business processes.

As of right now, the application is configured as a Spring-Boot application, connected to a PostgreSQL database, and uses Maven to manage all the dependencies.

## Process Definition
In order to read the process definition, Flowable uses an XML file, which emulates the BPMN 2.0 notation. It uses then this **process definition** to create one or more **process instances**.

The XML file can be created manually of course, but that is error prone and it might be hard to visualize the different process steps. So, we also included in the project one of the Flowable applications: Flowable Modeler. This application can be accessed at **http://localhost:8888/flowable-modeler** and allows the user to create and edit a process through an interface.

Also taking into account the BPMN 2.0 notation, the Modeler uses that same notation to model a process. A process is triggered by a starting event, and by combining tasks and connectores, we can create a fully working process definition. A task can be a **user task**, which will have to be done manually, or a **service task**, which will be executed by the engine. On each task, there are several variables that can be changed, in order to change the task behaviour. There is a link below with the Modeler documentation given by Flowable. It explains more in detail each one of the functionalities and gives an example.
Useful link: https://flowable.com/open-source/docs/bpmn/ch14-Applications/#flowable-modeler-application

DISCLAIMER: Although Flowable can deal with several types of gateaways (that connect several steps of a process), but our end-user application is only ready to deal with sequential steps. That is, no two steps can be "active" for review at the same time, for example.

When creating a new process, it can be exported as an XML file. There is also the possibility to load a valid XML file, with an already configure process, edit it and export it again.

Several process definitions can be stored inside Flowable at the same time, and all these definitions are stored inside the folder src/main/resources. In order to have the engine load several process definitions, they need to be added to the folder referenced before and also add a new call fo the process deployment function, with its "processes/id" as a String argument, where "id" is the "id" variable defined in the XML file. That function should be caaled inside the file FlowableApplication.kt. Below, you can see an example code

### Process Definition Example

Currently, we have defined a definition that processes a new submission.

Firstly, the engine starts a new process instance whenever there is a new submission on the form. That submission works as a trigger and also sends the process variables through a REST API to the engine. The process is instantiated using a key, defined in the process XML file (the id attribute), that works a unique ID that distinguishes it from other processes. In this case, the id is "submissionProcess".

Then we have the steps, each one being of a specific type.

The manual step is defined as a *userTask*. This task has an *id* and *name* attributes, and can use the *flowable:candidateGroups* attribute to assign this task to a specific group of users. In our case, we have several *userTask*, each one with its own name, and that are related to certain process variables.

The automatic step is defined as a "serviceTask". The logic behind this process can be defined in several ways, such as code in the Flowable project or REST API calls to an external system. In our case, we are simply running "dummy" code, to show that the step is executed when is set to active by the Flowable engine.

When reaching its conclusion, the process can be either completed ou suspended, depending on if it was rejected in any of the checkpoints.

## End-user application and Process Engine connection

In order to present the user with relevant information, we had to somehow access the data stored by the Flowable Engine in the database base, and interpret it accordingly. The Flowable core is consisted by several "sub-systems", each one with its own responsibility. Here below we list a few, but their documentation can be accessed the **Flowable API Documentation** link below:
- Runtime Service: This service has access to all the currently active processes. It is usually used for performance reasons, when we know a process we need it currently active. It also has access to those process variables.
- History Service: This service has access to all the processes, both the ones also accessible by the Runtime Service and all the others that are no longer active. Through this, the process variables can also be accessed.
- Task Service: This service deals with the tasks, independent from the process they are connected at.

To retrieve information from the Engine, we use the Flowable Java API, which allows us to create "queries", that Flowable then interprets and queries the database with.


## Useful Links
**Flowable BPMN Getting Started**: [](https://flowable.com/open-source/docs/bpmn/ch02-GettingStarted/) 
    - from this link we managed to gather most of the information needed to understand how Flowable works on a more generic perspective.
    
**Flowable API explanation**: [](https://flowable.com/open-source/docs/bpmn/ch04-API/)

**Flowable API Documentation**: [](https://flowable.com/open-source/docs/javadocs/)
    - As all the classes needed to create the queries and retrieve information from Flowable.
    
**Flowable JavaDocs**: [](https://flowable.com/open-source/docs/all-javadocs/)

**Flowable Event Registry**: [](https://flowable.com/open-source/docs/eventregistry/ch02-Configuration/)
    - Used to integrate the engine with other Event-based applications.