Creating a Data Object Model With a Database Service Model

In this guide, we’ll look at creating a data object model, where the data for the data object is stored in a relational database table (next to the tables Flowable uses).

This is useful for when you do want to use data objects in your process or case models, but the data is not in an external data store or service.

The steps we’ll go through are

  1. Create the data object model

  2. Create the service model based on the data object model

  3. Create a Liquibase changelog for the data object model

  4. Create an example case model and forms to show the usage of the data object

Creating the Data Object Model

In Flowable Design, go to the Others section, select Data object from the list on the left-hand side, and then click on the the Create button in the top-right corner.

In the dialog, give the data object model a name, set the key, and optionally add a meaningful description for it. Once all the information is entered then click on Create new model.

Create a Data Object

Once created, the Data Object Model editor opens, and we can start defining it.

Defining the Data Object Fields

A data object consists of one or more fields. New fields can be added by clicking the Create new field button.

The following form is shown:

New data object field

Following properties can be set:

  • Label (optional): a human-readable version of the (technical) name of the field.

  • Name (required): the (technical) name of the field. This is the name that is used for example in expressions in process or case models (e.g. ${customer.id === '123}).

  • Type (required): the type of the field. Currently supported are String/Date/Boolean/Integer/Double/Long fields.

  • Default value (optional): a value for the field that is set in case when a value would not have been set.

  • Description (optional): a human-readable explanation of the purpose of this field.

Let’s add following fields to the data object:

  • ID: a unique identifier for the customer.

  • Name: the name of the customer

  • Active: a flag indicating whether this is an active customer or not

  • Country: the country where the customer resides.

  • Yearly fee: a monetary value indicating some yearly fee the customer pays.

This should result in something that looks like this:

Data object fields

If a description is set, an information icon is shown next to the label of that field (e.g. for the ID field here.)

The actions column of the table shows the following actions (from left to right):

  • Edit: this will allows changing the field settings.

  • Delete: this deletes the field. A confirmation will be asked before deleting.

  • Move up: moves the field one row up.

  • Move down: moves the field one row down.

Advanced Settings

At the bottom of the page there is a check box available that, when selected, displays optional advanced settings:

Advanced settings

All these fields are (technical) metadata settings:

  • Type: A custom type for the data object.

  • Sub type: A custom sub type for the data object.

  • External Id: An external id to identify the data object.

The main use case for these is to categorise or easily query and retrieve data object definitions via the API’s.

Include in App

Data object models can be added and are deployed as part of a regular app. To do that we need to go to the Apps section of Flowable Design and create an app. After the app is created in the App Editor, we need to

  • select the + button

  • select now Include an existing model into the app

  • go to the Others models tab and then select the data object model

Add data object to app

Creating the Service Model

In this part, we’ll create the service model needed to retrieve and manipulate the data for a data object model. The point about doing this, is that all of this is hidden to the business modeler. The actual details how this done are hidden in the service models and don’t leak into the models where the data object gets used.

In Flowable Design, go to the Others section, select Service from the list on the left-hand side, and then click on the the Create button in the top-right corner.

In the dialog, give the model a name, set the key, and optionally add a meaningful description for it. Once all the information is entered then click on Create new model.

Database Service Definition Creation

Flowable Design will now switch to the service model editor.

Two dropdowns are available: one to select the type and one to select the service type. he type is either standard or based on a data object model.

  • A standard service model allows defining operations and parameters in a free-form way. This is for service models that e.g. get used by the service registry task (See The Service Registry Developer Guide) in process or case models.

  • A service model based on a data object model is used to connect a data object model to an implementation of how to retrieve and manipulate the data at runtime.

Select now based on a data object model. A second dropdown appears that allows selecting the data object model. Choose from that list the Customer data object model which we’ve created above.

Database Service Definition Type Selection

With the third dropdown, the type of service is chosen. In this case, we’ll use the Database option.

When switching to this type a few things happen, as shown on the screenshot below.

  • The Data Object Configuration section appears

  • A table appears that allows to map the data object structure into a olumns

A few things need to be configured now:

  • Lookup ID: To uniquely identify and retrieve data object instances it is mandatory to mark one of the data object fields as the 'lookup identifier'. In the example here, this is the ID field.

  • Table name: This is the name of the table where the data of the data object instances will be stored. We’ve chosen CUSTOMER_ here (in Flowable all database tables and columns have a _ at the end, to avoid clashes with reserved keywords)

  • Column mappings: Every data object field needs to be mapped to a column name. In the example here, we’ve simply used the uppercased name of the field, with a _ suffix.

Database Service Definition Column Mapping

Creating the Liquibase Changelog Model

In the previous section, we showed how to define our own Data object. Given that object, it can be mapped to a database table that exists, or we can create a new table.

In the latter situation, creating this new table is done through a Liquibase Changelog model.

Liquibase is an open source, database-independent library for tracking, managing, and applying database schema changes. Liquibase is built on a simple premise: All database schema changes are stored in a human-readable form and managed and versioned using a source control system.

In Flowable Design, go to the Work section, select Liquibase changelog and then select Create.

In the dialog enter a name for your Liquibase changelog model, set the key, select the Customer Service model created above. Then click Create new model to complete the definition.

Database Service Definition Liquibase Changelog Model Creation

The structure of the selected service model and related data object model will be inspected and a default table and column definition is generated. Such a Liquibase Changelog is a single XML resource in which you define your database schema changes.

Database Service Definition Liquibase Changelog Model

More information about all possible options of the Liquibase databaseChangelog can be read in the Liquibase documentation.

In the view mode of the Liquibase model, there is a regenerate button that if clicked regenerates the changelog based on the referenced data objects. Performing a regenerate replaces all manual changes done in the Liquibase changelog.

Example: How To Use the Data Object Model in a Case Model

Let’s use the models from above to create a simple case model. The goal is to create a CMMN case model that can be used to create and manage customer data.

The end result will be a CMMN model that looks like:

CMMN Model

Of course, this is but a minimal model highlighting specifically using a data object model (backed by a service model). A realistic customer case model would have way more steps and details than this example.

Creating the CMMN Model

In Flowable Design, click on Apps in the header bar. Create a new App and name it Customer app. Include the data object and service model we’ve created above by clicking the large + button and selecting Include an existing model into the app.

Now, click the + button again and select Create a new model for the app and Case in the next step. Give the model a name (e.g. Customer Case) and a unique key (e.g. customerCase).

Create CMMN model

Click Create new model. The view will now change to the CMMN editor.

The Start Form

When a case instance is started for this model, we want to show a form that asks for customer data.

Click on the plan model (the only thing shown on the screen right now) and click in the property panel on the Start form property. The New tab is open by default, so fill in a name for the start form and click on Create:

Case Start Form

An empty form model is now shown. Before we model the form, we have to configure it to be bound to a data object model. To do this, click on the Data model property in the property panel:

Case Start Form Data Model Configuration

A popup is now shown that allows us to fill in the data object model we want to reference. Here, we fill in the following:

  • variable name: customer

    • This is how we’ll reference the data object in the form value bindings.

  • Data object definition key: customer

    • This is the key of the data object model.

  • Mode: Create

    • When handling the form, we need to know whether this form will create the data object or only view or modify it.

Case Start Form Data Object Model Popup

This effectively creates a sort of 'scope', similar to the root or parent scope where variables can be stored on. It is also possible to bind the data object instance to a root or parent variable (e.g. using root.customer).

Let’s add some fields to the model:

Case Start Form Fields

The fields here are

  • Name, bound to customer.name and of type text.

  • Active?, bound to customer.active and of type checkbox.

  • Country, bound to customer.country and of type text.

  • Fee, bound to customer.yearlyFee and of type number.

Note that each fields is bound to customer., which is the variable configured for the data object in the popup above.

Publishing the App

Save the CMMN model and go to our app model (it is the model right at the top when going to the Apps tab). The four models (data object, service, liquibase changlog and CMMN model) need to be added to the app model, which should look eventually like this:

App view

Now click the Publish button (this will only work when you have a running Flowable Work or Engage where you can publish against).

Publishing a Liquibase changelog does not perform any update to the database, as this typically is an operation that needs to be done by a system administrator. In order to apply the updates defined in the Liquibase changelog we need to use Flowable Control.

The Liquibase changelog definitions are located in the Data Objects  Schema Definitions section of Flowable Control.

Flowable Control view

Once a definition is selected, we can either:

  • Update database - This uses the Liquibase changelog with the Liquibase update command to perform an update of the database.

  • Rollback database - This uses the Liquibase changelog with the Liquibase rollback command to perform a rollback of the database (delete the tables). This action removes the tables defined in the Liquibase changelog from the database.

Flowable Control Liquibase Model View

Click the Update and confirm the popup that is shown. The table now has been created in the database.

Now go to your Flowable Work or Engage installation, log in, Click the New button and select Work. Type customer in the search field. The customer case is now be selectable:

Definitions View

Select it. The start form is now shown:

Start Form

Filling in the form and clicking Submit will start a case instance and immediately end it, as the case has no tasks to do.

The Work Form

Simular to the start form, we can add a Work Form to the case model. This form can be seen from the case instance view and the goal is to display the customer information, but in a read-only mode. The actual editing will be implemented with a user task later.

Close to the Start form property, there is the Work form property. Create a new form:

Case Work Form Property

Similar to the start form, click the Data model property of the form. Give it the same customer variable and key, but change the mode to View this time:

Case Work Form Data Model Configuration

The fields look exactly the same as for the start form, except that all fields have the Enabled checkbox set to false.

The Customer Update Task

Let’s add a few things to the case model:

  1. Add a stage with name Active

  2. Add a user event listener Inactivate in this stage

  3. Add an exit sentry to this stage and link it to the event listener

  4. Add user task named Change customer details to this stage

  5. Make this task manual activated (select the manual activation checkbox in the property panel)

  6. Make this task (infinite) repeatable (select the repetition checkbox in the property panel)

  7. Add a stage with name Inactive below the other stage

  8. Add an entry sentry to the second stage. Link it to the first stage and select the Exit transition. We want to move to this stage when the first one is terminated

Select the user task again and create a new form:

Update Task Form

Similar to above, configure the data object model for this form. Set the mode to Modify.

Note: Modify actually also allows for viewing data, as will become clear in the next step.

Update Task Form Data Model

Let’s create a simple form, only adding a name and fee field. Set the Enabled checkbox of the Name field to false.

Update Task Form Fields

Let’s deploy the app: either go to the Apps tab, select the app model and click Publish or click the Quick Deploy button in the editor toolbar (the cloud icon with the triangle).

Go to Flowable Work or Engage and, like before, start a new case instance and fill in the start form. After starting the case instance, the view is now more interesting. The two stages are shown in the header and when clicking the Work form tab, the read-only form from above is displayed:

Case View

To start the (manual) user task, we need to click the Change customer details button in the header. This will start the user task, which can be found by clicking the Open tasks tab. The form to update the customer data is shown:

Update Task View

Change the fee to another value. If you’re running the example applications, you’ll see in those applications the output

Update customer Customer{id='8db19819-62df-4baa-b746-12fae1376941', name='John Doe', active=false, country='Belgium', yearlyFee=123456}

Note that the Change customer details tasks can be started an infinite number of times. In reality, you’d probably want to limit this to one. The Max instance count property on the user can be used to make sure there is only one user task open at any given time.

Using the Service Registry Task

This feature is only available from Flowable 3.5.1

Let’s finish up the CMMN model:

Cmmn Model Second Stage

  1. Add an event listener to the Inactive stage with name Remove customer data. The idea is that when the Inactivate event listener is selected, the first stage gets terminated, which brings the customer in an inactive but not yet deleted state. To actually delete the data, the Remove customer data event listener needs to be triggered.

  2. Add a service registry task Delete customer data to the same stage and link it to the event listener with an entry sentry.

  3. Add an exit sentry to the whole case (this is fully optional, as the behavior would be the same without here, but it’s visually clearer).

Above, we’ve configured the service model to be based on a data object model. However, this service model is still available as a regular service model and thus can be referenced from the service registry task.

Select the Delete customer data task and select the Delete operation from the model and operation. In the Input parameters configuration, bind the value to ${customer.id}.

Service Registry Task Configuration

Now

  1. Deploy the app again and start a new case instance.

  2. Click the Inactivate button in the header. This brings the case instance to the Inactive stage.

  3. Click the Remove customer data button in the header.

The customer data is now deleted. When running with the example appliaction, in the logging you can now see something like

Deleted customer Customer{id='3465f3ae-e8e9-43e2-a10e-27887270e764', name='John Doe', active=false, country='Belgium', yearlyFee=123456}

If you would query the database table using any SQL tool, you can see the customer data has been created now:

Database table rows