Data Modeling

The New Data Class wizard lets you create a new global Data Class.

Figure 3.1. The New Data Class Wizard

File > New > Data Class

The Axon.ivy Data Class editor lets you configure the process data objects of Axon.ivy. The process data is the data that "flows" through your processes. It represents the state of the respective process.

Use this editor to add new data fields to your process data class, to change the type of a field or to document your Data Class or Data Class Field.

Figure 3.2. The Data Class Editor

1. Axon.ivy Project Tree > double click on a Data Class entry in the tree.

2. New > Data Class > then the editor opens if the class was created successfully

The attributes table specifies the Data Class contents.

The Data Class editor supports Data Class attributes refactoring.

Combine into new Data Class refactoring

Over time the amount of attributes in a Data Class may become excessive. This decreases the maintainability and reusability of your process logic. Therefore the editor allows you to extract multiple attributes from an existing Data Class into a new Data Class. The extracted attributes will be replaced with a delegate field for the new Data Class.

E.g. if you have a Data Class that describes a person you could extract the attributes that belong to the address part into an extra address Data Class.

Before refactoring	After refactoring

Start Refactoring

Select the attributes to extract in the Data Class attribute table. Open the context menu of the selected attributes. Choose Combine to Data Class to open the refactoring wizard.

Wizard Page 1 - Define the new Data Class

The first refactoring wizard page lets you define the location and name of the Data Class. The checkbox 'Include non type safe refactorings within Web Pages (CMS)' enables the refactoring of JSP (macro) expressions within Web Pages. But Web Page modifications are not type safe. This means that attributes that are collected as change candidates may be wrong. So these changes should be inspected in detail in the refactoring preview (page 2) and tested manually.

Wizard Page 2 - Preview modifications

The second page previews all changes that will be applied to your artifacts. You can inspect most of the changes within the textual compare view on the lower part of the page.

The refactoring will modify all programmatic references to the attributes. This means that statements written in Java, ivyScript, JSP or El-Expressions could be changed by this refactoring.

A Business Data value is identified by an identifier given by the repository and its data class.

A unique id is generated if a Business Data value is stored the first time. If there is a field of type String with the name id in the Business Data class, the generated id will be stored into this field too.

It is also possible to use your own id if you set the id to the Business Data value before saving it for the first time.

The handling of identifiers of Business Data values is complex because you have to manage the identifiers in the process data manually. Therefore the Business Data Store can store data in the context of a business case. You can activate this by annotating a data class with the @BusinessCaseData annotation. On the Data Class Editor simply check the BusinessCaseData checkbox in the Annotations section. Now, all values of the annotated data class are automatically associated with the current business case. You can use the get method to load the value associated with the current business case. If no value is associated it simply returns a new object.

It is allowed to add and remove fields in the value data class hierarchy. New fields will be initialized with null, when old values get loaded. Deleted fields will no longer be available. The information will still be persisted until the value gets stored with the new information - which will override the old information.

Business Data supports optimistic locking. It is possible to check if the current version is up to date and save only if this is the case. It is possible to update a value partially so that multiple participant can work on different parts of the same Business Data value. See the Concurrent Modification demo in the WorkflowDemos project for a practical example.

Annotate the main data class of the business case with the @BusinessCaseData annotation:

@BusinessCaseData
public class BusinessCaseDossier
{
...

Get (load or create), modify and save a dossier value in the context of the current business case:

BusinessCaseDossier dossier = ivy.repo.get(BusinessCaseDossier.class);
dossier.getPerson().setLastName("Polo");
ivy.repo.save(dossier);

Note, that the method get either loads the dossier if there is already a dossier associated with the current business case or creates a new dossier.

Create and save:

Dossier dossier = ...
out.businessDataId = ivy.repo.save(dossier).getId();

Load, modify and save:

Dossier storedDossier = ivy.repo.find(in.businessDataId, Dossier.class);
storedDossier.getPerson().setLastName("Polo");
ivy.repo.save(storedDossier);

The search capabilities of the Business Data Store are based on Elasticsearch and therefore fast and powerful.

There is a fluent API to search stored business data. The API supports filtering, ordering and limiting of the results:

List<Dossier> result = ivy.repo.search(Dossier.class)
       .allFields().containsAnyWords("Polo Columbus")
       .execute()
       .getAll();

Also fuzzy search and search engine like query strings are supported:

List<Dossier> result = repo.search(Dossier.class)
       .score()
       .allTextFields()
       .query("Baldwin~1 -Alec")
       .execute()
       .getAll();

Create and save with own Id:

Dossier dossier = ...
String yourId = ... // generate your own id, be sure it is unique!
dosser.id = yourId; // set your id to the Business Data value
ivy.repo.save(dossier);

ivy.repo.find(yourId, Dossier.class) // get your Business Data value 

The WorkflowDemos sample project of the Axon.ivy Designer contains examples on how to use the Business Data Store.

See Public API of BusinessDataRepository for more code samples.

The de-serializer expects an empty default constructor to re-create a Java object. If you have a non default constructor (with parameters) or a factory method to create instances of your object, Jackson annotations are required so that the de-serializer knows how to re-create the object.

For a sample see: https://github.com/FasterXML/jackson-databind/#annotations-using-custom-constructor

The ObjectMapper will only store fields as JSON which are public accessible either by getter method or its field visibility. The re-creation of such field will fail if no setter is public accessible. Via annotations either the serialization of this field can be avoided or the re-creation can be enabled.

Avoid the serialization of a field:

public class MyCar{
    private List<Wheel> wheels;

    @JsonIgnore
    public List<Wheel> getWheels(){
        return wheels;
    }
}

Enable re-creation of a setter-less field:

public class MyCar{
    @JsonProperty
    private List<Wheel> wheels;

    public List<Wheel> getWheels(){
        return wheels;
    }
}

If simple annotations do not solve a serialization task, it's possible to write a completely custom serializer and de-serializer for Jackson. To do so implement a class that extends com.fasterxml.jackson.databind.module.SimpleModule and add your customization code into it. Register the class via SPI: create a file META-INF/services/com.fasterxml.jackson.databind.Module and store the qualified name of your module implementation in this file.

However, if you need to serialize instances of a popular library there could already be a Jackson module available that handles its serialization. See https://github.com/FasterXML/jackson#third-party-datatype-modules

If a module is already public available, simply add its JAR to the classpath of your project.

The New Entity Class wizard lets you create a new global Entity Class.

Figure 3.3. The New Entity Class Wizard

File > New > Entity Class

The Axon.ivy Entity Class editor lets you configure the process data objects of Axon.ivy similar to the Data Class Editor. The process data is the data that "flows" through your processes. Additionally an Entity Class has information where and how to store the data of a class and it's attributes to a relational database.

Use this editor to add new data fields to your Entity Class, to change the type of a field or to document your Entity Class or Entity Class Fields.

Axon.ivy Project Tree > double click on a Entity Class entry in the tree.

New > Entity Class > then the editor opens if the class was created successfully

The Persistence Configuration Editor lets you configure the persistence units you use in your project and the extending projects.

Usually you only need a single persistence unit that manages all of your project's entity data classes. In this case you can simply create a new persistence unit, associate it with a data source (i.e. data base) and you're done. All of the project's entity classes will then automatically be managed by this unit.

However, if you wish to do so, you can divide your entity data classes into subsets and manage each subset through an individual persistence unit. In this case you need to specify multiple persistence units and then define an explicit list of managed entity classes for each unit.

Figure 3.4. The Persistence Configuration Editor (single persistence unit)

Figure 3.5. The Persistence Configuration Editor (multiple persistence units)

Axon.ivy Project Tree > double click on the Persistence label.

On the first wizard page you can specify the environment and the type of the schema generation.

Figure 3.6. Database schema generation option

The second wizard page shows a preview what will be executed on the database.

Figure 3.7. Database schema generation preview

Axon.ivy Project Tree > double click on the Persistence label > Select a persistence unit > Generate Schema.

The Axon.ivy Persistence API is used to load entity objects directly from the database or save/update them on the database. The Persistence API can be accessed by IvyScript anywhere scripting is supported. The Persistence API can only deal with entity objects, means objects of type Entity Classes. The Persistence API can be found under ivy.persistence.<persistence unit>. Here you find all the methods for finding, persisting, updating and querying entity objects. See IIvyEntityManager fore more information. Replace <persistence unit> with the name of a persistence unit. The persistence units can be configured with the Persistence Configuration Editor.

To persist (save/create object on the database) you can use the persist() method of the Persistence API.

Example (Product is an Entity Class):

// persist new created product
Product product;
product.name = "Product name";
product.nr = 12;
ivy.persistence.<persistence unit>.persist(product);

// get id of new created product
Number newProductId = product.id;

To find an entity object by id (select object on the database) you can use the find() method of the Persistence API.

Example (Product is an Entity Class):

// load product with id 1 from the database
Product product = ivy.persistence.<persistence unit>
.find(Product.class, 1) as Product;

To merge (update or save/create object on the database) you can use the merge() method of the Persistence API.

Example update (Product is an Entity Class):

...
// change before loaded product
product.name = "New product name"
Product updatedProduct = ivy.persistence.<persistence unit>
.merge(product) as Product;

Example save/create (Product is an Entity Class):

// save new created product
Product product;
product.name = "Product name";
product.nr = 12;
Product savedProduct = ivy.persistence.<persistence unit>
.merge(product) as Product;

// get id of new created product
Number newProductId = savedProduct.id;

To remove (delete object on the database) you can use the remove() method of the Persistence API.

Example (Product is an Entity Class):

...
// delete the product from the database
ivy.persistence.<persistence unit>.remove(product);

To refresh (reload object from the database) you can use the refresh() method of the Persistence API.

Example (Product is an Entity Class):

...
// change before loaded product
product.name = "New product name"
// reload object from the database and revert local changes
ivy.persistence.<persistence unit>.refresh(product);

With the Persistence API it is possible to execute Java Persistence API Query Language (JPA QL) statements. See IIvyQuery for more information about the Query API. The query language based around the objects that are persisted but with syntax very similar to SQL. You have always to use the names of the Entity Class and the attributes and not the names from the database.

Product product = ivy.persistence.<persistence unit>
.createQuery("select p from Product p where p.id = :id")
.setParameter("id", 1)
.getSingleResult() as Product;

List<Product> products = ivy.persistence.<persistence unit>
.createQuery("select p from Product p where p.price > :price")
.setParameter("price", 10)
.getResultList();

// delete all products
Number deletedRows = ivy.persistence.<persistence unit>
.createQuery("delete from Product p")
.executeUpdate()

// update product name
Number updatedRows = ivy.persistence.<persistence unit>
.createQuery("update Product set name = :newName where name = :oldName")
.setParameter( "newName", "New Product Name" )
.setParameter( "oldName", "Old Product Name" )
.executeUpdate();

ivy.persistence.<persistence unit>
.createQuery("select p from Product p where p.price > :price")
.setParameter("price", 10)

ivy.persistence.<persistence unit>
.createQuery("select p from Product p where p.price > ?1 and p.amount <= ?2")
.setParameter(1, 10).setParameter(2, 80)

List<Product> products = ivy.persistence.<persistence unit>
.createQuery("select p from Product p where p.price > :price")
.setParameter("price", 10)
.setFirstResult(40)
.setMaxResults(20).getResultList();

from Product p order by p.name

from Product p order by p.name desc

from Product p order by p.name asc, p.description desc

select distinct p.description from Product p

from Product p where p.amount = 100
from Product p where p.amount <> 100
from Product p where p.amount > 100
from Product p where p.amount <= 100
from Product p where p.amount between 1 and 10
from Product p where p.name in ('Product A', 'Product B')            

from Product p where p.name is null
from Product p where p.name is not null          

from Product p where ( p.amount / 0.71 ) - 100.0 > 0.0

from Product p where p.name like 'A%'
from Product p where p.name not like '_a_'

from Product p
    where p.name like 'A%' and p.price > 10

from Product p where p.customers is not empty
from Product p, Category c where p member of c.products

from Product p where lower(p.name) = 'product name'
from Product p where upper(p.name) = 'PRODUCT NAME'

from Product p where concat(p.name, p.description) like 'A% B%'

from Product p where size(p.customers) > 10

Number productCount = ivy.persistence.<persistence unit>
.createQuery("select count(p) from Product p").getSingleResult() as Number;                

select avg(p.amount), sum(p.amount), max(p.amount) min(p.amount) from Product p

You can use the Persistence API everywhere you have the ivy variable in the IvyScript. Use ivy.persistence.<persistence unit>. Here you find all the methods for finding, persisting, updating and querying entity objects. Replace <persistence unit> with the name of a persistence unit.