Data model structure

Tree structure

The data model has a tree structure that makes it easier to map the hierarchical structure of business domain objects.

Leaves of the tree represent the most detailed element of the structure. Leaves, called fields, no longer have any other child elements and represent a single data field. Examples may include "customer name" or "bank account number."

Nodes of the tree represent objects composed of other objects and/or fields. Examples: "correspondence address", "customer income".

Figure 1. Tree structure

It is possible to change the order of nodes and leaves on the tree by holding and dragging them. Reordering is possible only within the same hierarchy level and while working in draft mode. This modification is purely visual and does not affect the model's logic.

Nodes

Each data model node has the following attributes:

• a key unique among its siblings (children of the same node)
• multiplicity expressed by the formula n..m meaning from n occurrences at minimum to m at most, e.g.:

  • 1..1 - the object occurs only once
  • 0..1 - the object is optional
  • 1..null - the object occurs at least once, with no limit on the maximum number of occurrences
• description of the object's meaning for the application

Nodes can therefore be uniquely identified using a key created by concatenating the keys of parent nodes, e.g.: client.email.

Leaves

In addition to node attributes, leaves also have:

• data sources - define how and from where the value is retrieved
• default value - what the field will return if none of the data sources returns a value

A field can have a defined list of data sources. Resolving the field value consists of calling the data sources in the order they were defined until a non-empty value is obtained. Therefore, the first source to return a non-empty value wins.

We can retrieve data from the model only for single keys selected by us, i.e. we cannot retrieve the values of keys that have children below them, just as we cannot retrieve the entire model in a single query.

Arrays in the data model

Model nodes marked as multiple (maximum multiplicity >1) create an array of simple values (for fields) and complex objects (for nodes that are not leaves). It is also possible to define nested collections.

Keys and identifiers

When referring to data model nodes defined as an array (or being descendants of an array), you must always use array notation:

• array[].field - retrieves all occurrences of the field; depending on the API used, it will return either a collection or a single string with the "," separator
• array[0].field - retrieves a single value resolved by the collection row indicated in the key (in the example, 0 means the first array element),
• array.field - will cause an error; there is no way to refer to an array node without array notation,

Defining an array

To define an array field, it is necessary to:

• the multiple data model node must have a multiplicity greater than multiplicityMax=1, e.g.: 1..null,
• the multiple data model node must have defined sources pointing to an array; the indexes of this collection will be used to index repetitions of the model value,
• nodes below a multiple data model node can use, in the mapping, the index of the iterated model node to indicate specific elements of the service output,

  • the parent node will always expose its current index in the execution context (while resolving values for the collection) under the identifier nodeNameIdx,
  • iterated fields by the parent should point to objects inside the collection over which the parent iterates,
  • however, this is not strictly necessary; it is possible to use this index to iterate over a completely different field or to extract fields that are not arrays at all.

For example, having a service result that consists of a constant field and two arrays - known to have the same length (arrayA, arrayB, fieldC) - it is possible to create a mapping in which the model iterates over arrayA, but its subfields extract successive fields from arrayB and the constant value from fieldC.

Binding a provider to the data model

A provider is a local data source written in ScriptCode, which defines how to retrieve values for model fields. It can be used by fields to supply their values. A data source can be a function:

• script-based,
• calling an external REST service,
• referring to another element of the model,
• retrieving a value from the application configuration.

The provider described below is the data source for a data model leaf. It is used to retrieve the current currency exchange rate from an external API (NBP):

• exchangeRate is a leaf (field) in the tree,
• this field has no children and represents a single value (currency exchange rate),
• it can be nested in a node, e.g.: exchangeRates.exchangeRateEUR.

Figure 2. Example of a provider retrieving the current currency exchange rate from the API (NBP)

Execution flow:

• the key, i.e. the currency code, is taken from the provider's input parameters (currencyCode), e.g. "EUR" or "USD",
• this value is passed to the provider from the data model,
• the provider executes a GET request to the configured endpoint nbpExchangeRate using api.rest.v1.get,
• path parameters (pathParams) build the request address in the form: /rates/A/{currencyCode} (the letter "A" denotes the table of average exchange rates published by the NBP),
• the response from the API contains an object body, which contains the array rates, and the first element is taken from the array (rates[0]), then its field mid, which represents the average exchange rate,
• the provider returns an object containing the field exchangeRate, the value of this field corresponds to the retrieved exchange rate and can then be used in the data model or form.

Configuring data sources for a field

Each field in the data model can have data sources. The configuration is available by clicking the pencil icon next to the selected field, which opens the data source settings drawer associated with that field. If data sources have already been defined for a given key, their names are visible in the panel - in the example shown, this is exchangeRateFromNBPProvider. After selecting a source, it is possible to configure input parameters and output mapping.

Figure 3. Example of using a provider as a data source in a model

In the Parameters tab, the values passed to the provider are defined. In the described case:

• key: currencyCode
• value: EUR

This parameter is used by the provider to call the external API.

In the Mapping section, it is determined which data from the provider's response will be assigned to the field in the model. In this example, the value exchangeRate.

The obtained value can then be used in the data model or directly in the form. More about using the data model in the application can be found in the tab Data model on the interface.