Creating the descriptor file - signavio/workflow-connector GitHub Wiki

Before you start the workflow connector you have to specify the schema of the data it handles in the config/descriptor.json file.

In order to explain the steps required in going from data model to working descriptor.json file, we will use a basic example here that most people should be familiar with. If you are able to setup a test database, you can follow along by using the database specific migration files provided in the build folder.

If you are just looking for a script to help you to create a valid descriptor.json file from a dump of a table schema (using the output from DESCRIBE <tableName> in mysql for instance) then you will find a python script in the scripts folder which performs this conversion.

Let's assume we want to create a workflow that can instruct an intern on how to make coffee for the rest of our team. In order for the intern to do their job properly, there are three things the intern must know:

1. What style of coffee do we want?
2. What are the necessary ingredients?
3. How do I properly use the machines to make the best batch of coffee possible?

We can use these requirements to come up with a data model that we can implement in a relational database. The following diagram shows how this data model could look like:

This diagram is a little abstract so let's express what our intentions are with this data model in plain english.

• A Recipe contains instructions for the intern to follow. Making a Recipe requires only one piece of Equipment. A Recipe of course contains many Ingredients.
• A single Equipment can be used in many different Recipes.
• The database keeps track of the Ingredients in stock in the inventory table. When the intern is shown the Ingredients necessary for a Recipe he or she will also be shown if there is enough of these Ingredients in stock.

Using the equipment table as an example, let's look at how we could translate the table's schema into a valid record type descriptor that we can then insert into our descriptor.json file.

The diagram shows the equipment table schema which contains an attribute entitled purchase_date (highlighted in yellow) that is of data type DATETIME (highlighted in green). The corresponding example data is shown on the right.

In order for the Signavio Workflow Accelerator to know what the structure of the data retrieved from the database looks like, a mapping needs to be performed. This mapping is specified in the descriptor.json file, a snippet of which is shown in the diagram in the bottom left.

Here you can see how a mapping is performed on the attributes' names and data types:

database attribute name	workflow connector attribute name
purchase_date	purchaseDate
database attribute type	workflow connector native type
DATETIME	date / datetime

Looking at the mapping for the recipes table shows how to create mappings for tables that have relationships with other tables. Below we see how we can annotate the descriptor.json file with a relationship section to include the many-to-one relationship it has with the equipment table.

Although the original recipes table does not have an attribute called equipment, we can add this attribute to the descriptor.json file and tell it that this will represent a related equipment. At the bottom right of the diagramm, we see what the workflow connector outputs for data when asked to return the data for the recipe with id = 1.

You can find the complete mapping for this coffee example in the config/descriptor.json file in this repository.