Entity Data Task

Overview

An Entity Data Task (or shortly, data task) is a specific type of service task that represents operations with Jmix entities within a process. It can be convenient to use Entity Data Task for manipulations with data instead of regular service Task. You can load entities from the database, modify them, and create the new ones.

To be exact, we talk here about entity instances, not entities themselves.

Graphical Notation

An entity data task is visualized as a rounded rectangle with a small database icon in the top-left corner.

As an Entity Data task is a Jmix extension, 3rd party BPMN modeling tools don’t support it. Take care about compatibility if you need to exchange BPMN models with some of them.

For example, StormBPMN doesn’t allow to create entity data tasks — use service tasks instead with a comment thai it must be the data entity task. And vice versa: when publishing BPMN models from Jmix to Storm, your entity data task visually will be shown as common service tasks, but their properties in the XML will be safe.

XML Representation

Depending on type, the entity data task XML representations differ. See examples in the corresponding task type descriptions.

Here is a newly created entity data task; by default, it is a Load entity task.

    <serviceTask id="entity-data-task" name="Entity Data Task"
        flowable:type="jmix-load-entities-jpql">
      <extensionElements />
    </serviceTask>

Properties

An entity data task has the following properties:

To configure data task:

First, set general task properties.
Then, define a Task type and set the required parameters depending on the selected type.
Create Execution listeners if necessary.
About the Async flag, see details in the Transactions section.

Entity data task doesn’t have multi-instance properties available. But you can use it within an embedded subprocess that is multi-instanced. See the Multi-Instance section.

Data Task Types

You can select a type of data task from a pull-down list:

Here you can create data tasks of the following types:

Load Entities
Modify Entity
Create Entity

To delete an entity, use a service task and call a method doing deletion with the help of DataManager.

Loading Entities

To load entities, you should select the Load Entities task type in the properties panel. Then, define JPQL query and, if needed, the result variable.

JPQL Query

To create a JPQL query, select a JPQL property field and click the Edit button:

And JPQL Query Designer window will open. First, select entity class from a pull-down list, for example, smpl_Order. Entity alias will be set automatically, you can change it later.

Result Types

Next, select the result type:

Entity

In this case, the query always returns a list of entities. If you choose option Save result as a single element, you’ll get the first element from the list, ordered by default or according parameter you set.

This JPQL query will be generated:

select s from smpl_Order s

Entities count

In this cas, the query returns an integer value, the result of counting operation.

This JPQL query will be generated:

select COUNT(s) from smpl_Order s

Tuple

The query of this type returns a collection of field values, including from associated entities. When the Tuple result type has chosen, the Select section appears.

To complete the query creation, you have to select one attribute. For example, customer.name.

This JPQL query will be generated:

select s.customer.name from smpl_Order s

In addition, you can use Distinct check box for receiving only unique items.

And the query will be modified:

select distinct s.customer.name from smpl_Order s

Only one field will be included in tuple, others will be ignored if you add more.

As well, it’s possible to use aggregation functions with tuples.

In this case, the query returns a single numeric value.

For example, this query calculates the sum of all order amounts.

select SUM(s.amount) from smpl_Order s

Query Filtering and Sorting

You can use WHERE and ORDER BY clauses with your JPQL query:

WHERE clause

In JPQL, the WHERE clause is used to specify conditions that filter the results of a query. To apply it, click icon and select an entity attribute, for example, amount:

And define operation:

This JPQL query will be generated and returns a list of orders with amount greater than the value we set in parameter amount1:

select s from smpl_Order s where s.amount > :amount1

Besides, it’s possible to use functions in the WHERE clause. Click icon, select one from the list and then select an attribute that will be used:

This query must return orders with the amount greater than parameter value and within a certain year, defined by another parameter.

select s from smpl_Order s where s.amount > :amount1 and extract(year from s.approvalDate) = :year1

When there is more than one condition in the WHERE clause, they are joined by logical operators and/or, and you can choose desired one:

ORDER clause

The ORDER BY clause in JPQL is used to sort the results of a query in ascending or descending order based on one or more attributes of the entities. It allows you to specify the order in which the retrieved records should be presented.

To add it to your query, switch to the ORDER tab and select an attribute you want to use for sorting.

The query will be modified this way:

select s from smpl_Order s where s.amount > :amount1 and extract(year from s.approvalDate) = :year1 order by s.number asc

By default, an ascending direction is used, but you can change this:

Click the Copy button to copy your query in memory.

Query Parameters

You can set parameters of WHERE, ORDER BY clauses directly in the query body, for example:

select s from smpl_Order s where s.amount < 500

But often you need to define parameter values externally, i.e., at runtime. For this, you have to create named parameters:

JPQL parameters — If there are parameters in your query, define them here:

The name of parameter you create must match the name of the parameter in the query, there is no automatic control.

Parameter values can be passed into the process using two methods:

Process variable
Expression

For example, like this:

Loading Result

To use the result of the loading operation further in the process, define a Result variable. You can select one of the existing process variables or enter an arbitrary name — then a new variable will be created.

If there is an existed process variable with such a name but of the other type, it will be overridden. The type of the result variable will be defined by the type of the query result.

As well, you can choose between two options in the combo box Save result as depending on the query result you expect, a Single element or Collection.

XML Representation

In the XML, the loading entity data task is declared as a service task of the custom type flowable:type.

<serviceTask id="load-orders-task" name="Load orders"
    flowable:type="jmix-load-entities-jpql"> (1)
  <extensionElements>
    <flowable:field name="jpql"> (2)
      <flowable:string>select s from smpl_Order s where s.amount &gt; :amount1</flowable:string>
    </flowable:field>
    <flowable:field name="resultVariable">
      <flowable:string>order</flowable:string> (3)
    </flowable:field>
    <flowable:field name="saveLoadResultAs">
      <flowable:string>collection</flowable:string> (4)
    </flowable:field>
    <flowable:field name="jpqlParameters"> (5)
      <flowable:string>[{"name":"amount1","valueType":"processVariable","value":"targetAmount"}]</flowable:string>
    </flowable:field>
  </extensionElements>
</serviceTask>

1	— Declaring loading data task
2	— JPQL query body
3	— Result variable name
4	— Type of the result
5	— Query parameters in JSON format

Modifying Entities

You can modify an entity stored in one of the existing process variables. Entity type will be detected automatically, and all non-system attributes will be available for changes.

Also, you can specify a process variable directly by typing its name. This is relevant when the variable is not presented in the list. For example, when it is created programmatically in the service task, or it is a result of loading entity by another data task. After that, it is necessary to explicitly define an entity type and proceed with specifying entity attributes.

Specifying Attributes

Click a Create link to specify entity attributes you want to modify.

The value of the attribute can be specified in one of the following ways:

Specifying a direct value by typing in the field:

Or by selecting from the list for Enumerations:
Specifying an expression.

The process variable today must be defined before this data task be executed.
Using a Spring bean.

By default, this option is disabled. To enable this variant in the list, set the property:
```
jmix.bpm.data-task-spring-bean-entity-attribute-enabled=true
```
Then, a Spring bean option becomes available in the Value type field:

Now you can specify a Spring bean and its method to pass a value into entity attribute:

XML Representation

In the XML, the modifying entity data task is declared as a service task of the custom type flowable:type. Attributes for the modified entity are passed via JSON.

<serviceTask id="modify-order-task" name="Modify order"
    flowable:type="jmix-modify-entity"> (1)
  <extensionElements>
    <flowable:field name="entityName">
      <flowable:string>smpl_Order</flowable:string> (2)
    </flowable:field>
    <flowable:field name="processVariable">
      <flowable:string>order</flowable:string> (3)
    </flowable:field>
    <flowable:field name="entityAttributes">
      <flowable:string>[{"name":"approvalDate","valueType":"directValue"}]</flowable:string> (4)
    </flowable:field>
  </extensionElements>
</serviceTask>

1	— Declaring task type
2	— Defining entity class
3	— Defining result variable
4	— Entity attributes in JSON format

Creating Entities

To create an entity, select the entity name from the list. All non-system attributes will be available for specifying using BPMN Inspector.

If you need to use this entity further in the process, set a Result variable parameter or leave it blank if you don’t need it.

Specify all required (mandatory) attributes and other ones you want.

XML Representation

In the XML, the creating entity data task is declared as a service task of the custom type flowable:type. Attributes for the created entity are passed via JSON.

<serviceTask id="create-order-task" name="Create order"
    flowable:type="jmix-create-entity"> (1)
  <extensionElements>
    <flowable:field name="entityName">
      <flowable:string>smpl_Order</flowable:string> (2)
    </flowable:field>
    <flowable:field name="resultVariable">
      <flowable:string>order</flowable:string> (3)
    </flowable:field>
    <flowable:field name="entityAttributes">
      <flowable:string>[{"name":"status","valueType":"directValue","value":"New"},{"name":"customer","valueType":"expression","value":"${customer}"}]</flowable:string> (4)
    </flowable:field>
  </extensionElements>
</serviceTask>

1	— Declaring task type
2	— Defining entity class
3	— Defining result variable
4	— Entity attributes in JSON format

Was this page helpful?

Thank you for your feedback

Something went wrong