General Architecture

The TASKANA adapter serves as a bridge to all systems in the enterprise, where tasks originates froms. While it is always possible to directly create tasks in TASKANA using the API, there are use cases where a (bidirectional) synchronisation is required. For example:

• BPM / workflow systems
• Packaged applications with an included task component (like ERP, CRM, ...)

The TASKANA adapter provides a generic design to allow to connect to almost any kind of software. 

The adapter implements the general synchronisation algorithm. Both types of connectors are loaded through an SPI.

Task System Connector

The Task System Connector is the connector to the central task management system, which will typically be TASKANA. However, due to the generic design, you could attach any other system as well. Since TASKANA is meant to pool all tasks from various source systems, there is only one Task System Connector per Adapater instance. 

There is a default implementation of Task System Connector to connect to TASKANA directly using the Java API. This way the Adapter and TASKANA will be synchronized using a shared database. 

If TASKANA is embedded into your own application or wrapped in your own services, you can implement your own Task System Connector to make use of your own API instead of directly creating tasks in TASKANA. This makes sense if your API implements additional functionality. 

System Connector

You can have as many system connectors as you like, whereas there is only one task system connector which is directly ore indirectly connected to the TASKANA instance. 

The Taskana Adapter syncs tasks between TASKANA and an external workflow system, e.g. Camunda BPM. In this document, we call a task in the external workflow system 'referenced task'.

The adapter periodically performs the following work::

• retrieve new referenced tasks and create corresponding Taskana tasks
  * retrieve newly created referenced tasks
  * get the task’s variables
  * map referenced task to Taskana task
  * create an associated Taskana task
  * remember the tasks created in the adapter’s database
• retrieve finished referenced tasks and terminate corresponding Taskana tasks
  * retrieve finished referenced tasks
  * terminate corresponding Taskana tasks
• retrieve finished Taskana tasks and complete corresponding referenced tasks
  * retrieve finished Taskana tasks
  * complete the corresponding referenced tasks in the external system
• cleanup Adapter’s database tables
  * delete aged entries from the adapter’s database tables

The adapter is structured in an adapter proper that controls the logic and two SPI:

• The SystemConnector SPI that connects to the external system and
• The TaskanaConnector SPI that connects to the taskana system.

The component structure of the adapter is as follows

Notes

1. Duplicate tasks
   Method retrieveNewReferencedTasksAndCreateCorrespondingTaskanaTasks periodically queries the external system, to retrieve tasks that were created in a specific interval.
   To determine this interval, transactional behavior must be taken into account. Due to transactions, a task that was created at a specific instant may become visible only when the transaction is committed.
   In the extreme case this is the maximum transaction lifetime. As a consequence, the specified interval is not between the last query time and now, but between (the last query time – maximum transaction lifetime) and now.
   Using default values to illustrate: Queries are performed every 10 seconds. The default maximum transaction lifetime is 120 seconds. This is, the adapter has to retrieve all tasks that were created in the last 130 seconds.
   In the result, the query returns many tasks that have already been processed by the adapter. To cope with this problem, the adapter uses the TASKS table of its database to keep track of the tasks that are already handled.
   Tasks that are not found in this table are added to the table and a corresponding taskana task is started. Tasks that are found in the table are ignored, they are duplicates.
2. Variables
   When the adapter finds a referenced task for which a taskana task must be started, it retrieves the variables of the referenced task's process. These variables are stored in the custom attributes of the corresponding taskana task in a HashMap with key referenced_task_variables and value of type String that contains the Json representation of the variables.
3. Workbaskets
   Task / workbasket mapping has been kept to a minimum. If the adapter creates a taskana task, it puts it into the workbasket of the referenced task’s assignee. If this workbasket doesn't exist, it is created (together with some workbasket_access_items). If the task has no assignee, it is put into a default workbasket with name DEFAULT_WORKBASKET.