Data Management

This document describes how FNZ Studio organizes and stores business data. "Data Class" Business Objects describe the data in your app and form its data model. When the app is executed, FNZ Studio only stores data for as long as needed. By default, all data inputted within a Process is managed in a "Value Store" until the end of the corresponding Process Instance. If a piece of information needs to live beyond this time frame, it can be stored in a (relational or non-relational) database.

Data Model

An app's data model describes how its data is organized. It represents the type of information needed during the app's execution, and the relationships between these pieces of information.
For example, an app to open a bank account typically handles information about the account itself, about any natural persons or legal entities linked to this account, and about those entities' relationship with the account (for example, an account holder or beneficial owner).

Figure 1 : Simple data model for a bank account opening app

An FNZ Studio data model is domain-specific - it can be defined freely for a particular business purpose. It is object-oriented, consisting of a collection of "Data Class" Business Objects. For example, "Account", "Entity", "NaturalPerson" and "LegalEntity" are Data Classes in the diagram above. Each Data Class can have a list of properties, either of simple or of structured type.
Simple data types are "Primitive Type" objects in FNZ Studio. These include:

String - a piece of text, e.g. a natural person's first name
Integer - a number, e.g. an account number
Boolean - a false/true value, e.g. whether an account is active or disabled
Date - a date, e.g. a legal entity's date of incorporation

Structured data types are other Data Classes. For example, an "Account" Data Class can have a property called "accountHolder". The value of this property is an instance of either "NaturalPerson" or "LegalEntity", themselves Data Classes.

For more information on creating and editing a data model, see the Data Class Business Object on designing Data Classes.

Data Entities

Data Classes and Primitive Types are used in other business objects such as Processes, Screens or Integration Links to represent business data. At runtime, instances of these data objects are created and modified. An instance of a Data Class or a Primitive Type is called a "Data Entity".
A Data Entity can be a single element, an indexed collection (array), or a named collection (map). In the diagram below, the instances of "Account" and "NaturalPerson" are both examples of Data Entities.

Figure 2 : Data Entity examples

Short-term Storage: Value Stores

By default, FNZ Studio manages all Data Entities in a container called "Value Store". Data related to a Process instance is stored for the duration of that instance, regardless of any system restart in the meantime. Once the end of the Process is reached, the data for that instance is deleted automatically.

For example, a Process to open a bank account involves inputting data about a customer, for example "Summer Glaw". If her birth date is modified, the corresponding "NaturalPerson" instance - a Data Entity - is automatically updated. Once her bank account has been opened and the Process reaches its end, the Value Store for that process instance is deleted, including the Data Entity relating to Summer Glaw.

Data Entities can be created outside the context of a Process, for example in a standalone Screen or Integration Link. This data is stored in a Value Store in exactly the same way. It only exists during the lifetime of its context Business Object, e.g. the time it takes to render a Screen or process an Integration Link message.

FNZ Studio does not store data in a database by default. To save information beyond the duration of a Process, see the Long-term Storage section.

Value Store Structure

A Value Store is the default container for all data within a Process Instance. It consists of a set of scopes containing variable definitions and variable values, also known as Data Entities.

Each Data Entity can be a Primitive Type instance (Data Value), a Data Class Instance (Data Object), an Indexed Collection (Data Array), or a Named Collection (Data Map).

All Data Entities together build the data graph which is used during the lifetime of a process to keep track of the user input.

Figure 3 : Value Store

Every Process Instance has one Value Store. In order to keep track of data, processes rely on variables defined at every level, e.g. for the root process (level 0), or for a Business Object contained in that process (level 1). Each Value Store has several scopes, one for each level. A scope contains variable definitions and the values (i.e. Data Entities).

Figure 4 : Example Process

In the example Process above, two variables are defined at the process level, $action and $person:

Figure 5 : Process variable definition

At the Screen level, two other variables are defined. $action is inherited from the Process level, and $myPerson is assigned.

Figure 6 : Screen variable definition

The Value Store contains one scope for each level where variables can be defined. In the example above, there are two scopes, one for the Process Instance and one for the Screen belonging to it.

Figure 7 : Example of Value Stores

Scopes are structured into a hierarchical tree. Every scope can either have one parent scope, or none if it is the root of the tree, i.e. the Process Instance to which the Value Store belongs.

In this example, the scope tree is very simple: the Process Instance scope is the parent of the Screen scope.

Figure 8 : Example scope structure

Scopes contain the definitions of variables, which refer to Data Entities. The Data Entities can be in the same scope or in another one. For example, the variables $person and $action defined at the Process instance level are local. This means that they immediately point to values "located" in the same scope.

Variables can also point to values held in other scopes. For example, the inherited $action and the assigned $myPerson variables in the Screen scope refer to values in the root process scope. While an inherited variable always triggers a search for the corresponding value in a parent scope, an assigned variable points to a value in any scope within the Value Store. The following diagram shows the references from both scopes to Data Entities for our example process.

Figure 9 : Example of scope references to Data Entites

All data that is referenced via variables is persisted in Value Stores. The scopes are registered at the Value Store so that the process engine can persist them when necessary.

The benefit is that it is enough to define a variable at the level of a Business Object for the engine to take care of storing it. On the other hand, a Value Store can grow very large if all variables are defined at the root Business Object level.
The following set of best practices help to maintain the size of Value Stores reasonable:

Does a specific value need to be persisted or not? If you no longer need a value, set the corresponding variable to "null".
Define variables as close as possible to the Business Object where they are needed. This ensures that, if a scope is cleaned up because it is no longer needed, all variables and values it contained are also removed, thus reducing the Value Store size automatically.
Avoid creating variables that point to objects that you can obtain using an ID.

For example, do not load all the records of a Catalog and assign this collection to a Process or Screen variable. Instead, store the ID of the Catalog and of a specific record.

Similarly, avoid creating collections of User objects and assigning them to Process or Screen variables. Instead, store the user's ID and retrieve the corresponding User object when you need it.

Value Store Persistence

Value Stores are persisted as XML structures using a configurable store implementation. By default, a file system store is used. Alternatively, you can choose a JDBC or Cassandra (NoSQL) store. You can create additional implementations of the store interface if needed.

Every Data Entity that is assigned to a variable in a scope is automatically persisted along with its entire child entity graph as part of the Value Store's XML file.

Value Stores are completely loaded into memory in order to access scopes and the variable values. If a user executes an action in a Process Instance, the Value Store is loaded, modified and then committed.

Figure 10 : Value Store request-response cycle

By default, a Value Store is created when a Process Instance is started. This Value Store exists as long as the Instance it belongs to is alive, and is destroyed when that Instance is terminated.

Figure 11 : Value Store lifecycle

Pros and Cons

:-----------| :-----------| |Pros |Cons
|Data Entities are automatically stored in the short term. You don't have to execute any commands. The whole Value Store lifecycle is handled transparently by FNZ Studio. |Value Stores are loaded as complete objects. This means that large Value Stores or large entity graphs are loaded completely, whether they are used or not. This may result in an overhead in memory usage (RAM) and load time (CPU). Data stored in Values Stores is not easily accessible from outside FNZ Studio.

Long-term Storage: Business Data Storage

FNZ Studio does not store business data in a database by default. If you need to save information beyond the duration of a Process, you can use the Business Data Storage (BDS). Business Data Storage (BDS) allows FNZ Studio developers to easily persist and retrieve Business Data gathered through an FNZ Studio process to a Relational Database. Data can then be accessed by other FNZ Studio processes, reports and dashboards, or exported to other systems (e.g. using WebAPIs). BDS provides:

Transparent synchronization of selected FNZ Studio Data Classes to a database.
Convenient and easy-to-use functionality to Save, Load and Delete Data Class instances from the database
Thorough user interface in FNZ Studio Studio, which allows the developer to configure and synchronize Data Classes, and check the database content

The complexity of the underlying Database is hidden to the developer.

For more information, see:

The Business Data Storage main article (related documentation is presented in the introduction).
The Supported Databases section in the Technical Requirements article.

Additional Resources

To know more about Data Management you can also browse these additional resources: