Understand entity relationships

In this tutorial, the aim is to introduce simple counting analytics to your solution. You can use analytics when you link an entity to another entity in your model. 

1. About relationships

The entity model in your current solution is very simple. The model contains two entities, your entity for purchase orders and the Axway Decision Insight (DI) entity for User. There is no relationship between these two entities.  

In your search dashboard, you can see both the orders being currently processed and the orders closed during the current day. The dashboard may display these orders, but it does not count the instances of orders because any instance of a purchase order can only see itself. 

Linking another entity with the Order entity provides the solution with a vantage point from which you can see all instances of purchase orders at once. From that vantage point,DI can also perform a number of analytics functions, such as counting instances.

Cardinality rule

In the previous diagram, the relationship implies that the Global entity can be associated with more than one order, but one order cannot be associated with more than one instance of the Global entity. This type of relationship is a 1-to-n, that is a one-to-many relationship (or n-to-1, depending on how you look at it). 

The cardinality of a relationship expresses how entities relate to each other in one-to-many or many-to-one structures. The cardinality rule states that 1-n relations are always configured from the entity with the n cardinality. That means, after you create a Global entity, you will originate a relation from the Order entity towards the Global entity.

Forward and reverse relationships

You are defining a relationship that goes from Order to Global, and makes the Order attributes and analytics visible to the Global entity. The relation is considered as going in a forward direction. That is the observed relationship

When you name an observed relation, Decision Insight also asks you to name the reverse relation. In the current case, the reverse relation is the link from Global to Order. With this information, DI can locate any instance of the relationship in either direction.

Note: In the diagram of your model, only the name of the forward or observed relation is displayed.

Tip: You need the name of the relevant relationship when linking dashboard content to modeled entities.

Naming conventions

Naming conventions are a great way to help your users who might not be familiar with your model identify the different types of attributes in Decision Insight.  This is especially useful as your model evolves and becomes more complex. 

Here are two suggestions:

  • When naming an observed relation, prefix the name of the target with ref2 as in reference to. For example, name the relation from Order to Global ref2Global.
  • When naming the reverse relation, prefix the name of the source with 2. For example, name the relation from Global to Order 2order.

Using these naming conventions groups observed relations together and reverse relations together in your attribute list, which makes them easier to track as your models and attribute list expands.

2. Create the Global entity

A model always requires an entity like the one you are creating here, that is a global entity that can see all instances in the workflow. It is useful to use a convention for naming this entity, just like you used conventions for naming relations. In this tutorial, the convention is to name the entity Global.

Your task is to:

  • Define an observed relation between the Order and Global entities.
  • Name that relation based on the naming conventions in this tutorial.
  • Name the reverse relation.

First, start by creating the Global entity.

Step Action

On the main menu, click the Configuration icon.

2 On the left menu, click Entities, then the New Entity button.

Select the Mono dimensional option, then click Create.

4 On the create entity screen, in the Enter name here text box, enter Global.
5 In the Space drop-down, select Model .

Provide a relevant description for your entity in the Description text box.


Make sure the configuration type is selected. For more information about storage options, see Entity storage options.

Note : When this option is selected and you export your application, all the spaces and entities defined for the application are also exported. When you restore your data from that export, the values of the attributes in these entities are restored at the same time.

8 Create an attribute to act as the entity key for Global. On the left menu, click Attributes.

Click the You can also create a drop-down, and select Observed Attribute.

10 In the Enter name here text box, enter ID.
11 In the Space drop-down, select Model.
12 In the Type drop-down, select String, then click Done.
13 On the left menu, click Keys. Then, click New Key.
14 In the Enter title here text box, enter KeyGlobal.
15 Click Add Attribute, from the Model space, select the ID attribute, then click Done, and Done again.
16 Back on the Create entity screen, click Save.

To check your results, On the left menu, click Diagram. You should see three entities, with no relationships between them.

Entity storage types: Configuration and Transaction

On the Create entity screen, you can choose between two different storage types:

  • Use configuration type for entities containing static data or entities related to your businesses process, such as the Global entity.
  • Use transaction types for entities containing transaction items, such as the Order entity.

3. Link the Order and Global entities

An observed relationship is a type of entity attribute. To create an observed relation from Order to Global, create an observed relation attribute for the Order entity.

You should still be in the Model and Configuration area of the solution, where you left off the previous task.

Step Action

On the left menu, click Entities.


Click the pencil icon under Actions for the Order entity.


On the left menu, click Attributes. The list of Order attributes is displayed.


In the You can also create a drop-down, select Observed Relation.

5 It is recommended to follow the suggested naming conventions for relations. In the Enter title here text box, enter ref2Global, and in the Reverse Name field, enter 2order.

In the Description field, enter an appropriate description.

7 Click the Add Entities button to identify the target of this relation. Select Global, then click Done and Save.

Check the model diagram. On the left menu, click Diagram. Controls are available at the top of the diagram. If you click the Rotate right icon, your diagram should look like this.

When two entities are linked, the model diagram displays only the forward relation between Order and Global, but not the name of the reverse relation.

As you've seen in previous parts of this tutorial, creating an entity is only part of the process. You must also create an instance of that entity. 

Because the Global entity is an entity of type Configuration, instances and attributes for Global will be saved and restored when you create a backup. You can get the same results by using the mapping to a web service option.

4. Create the mapping for the Global entity

Before you can use a mapping with a web service, first create the mapping.

Step Action

On the main menu, click Data Integration.


On the left menu, click Mappings, then the New Mapping button.

3 In the Name field, enter mapCreateGlobal.

Click the Add parameter hyperlink, and add a String attribute named ID.

5 Click the Add Instance Operation, then the Select an entity hyperlink.

Select Global, then click Done.


Did you know: Named constants for time

When creating previous mappings in this tutorial, you supplied the resolution and operations begin times by spelling out, in ISO format, 01 January 2017 at 0:00:00.You can use this date again or you can define a property constant to represent your application start date so you never have to enter the entire date again.

For more information about how to define a property for the application start date, see Create a property for the application start date below.

In both the Resolution and Operations begin text boxes, select Constant then either enter 2017-12-01T00:00:00 (where 2017-12-01 corresponds to the earliest date at which you have data in your application) or enter the name of your property.

8 In the Resolution area, on the line for Key, in the drop-down select, Create an instance of Global if not found at resolution or after .
9 In the Resolution area, for Value, in the first drop-down, select Parameter, and in the second drop-down, select ID.

In the Operations area, click the Add an operation drop-down, and select Set space.


For Space name, in the first drop-down, select Constant, and in the following text box, enter the space key that corresponds to the name of the space where you want to store instances of the Global entity. For example, enter Instances.

Caution: Space Name actually means you have to enter the space key. The space key corresponds to the space name with all whitespace characters removed.

12 Your mapping is complete, click Save.

Create a property for the application start date

Properties provide configuration mechanism for routes and mappings. You identify a property using their name with the following format: {{propertyName}}.

For example, you can create a property that you can use in your mappings to define the time from which a mapping should start being executed, for example, a property that corresponds to the application start date. To create this property, follow these steps.

Step Action

On the main menu, click Data Integration.


On the left menu, click Properties.

3 In the In space drop-down, select Initializers .

Click the New Property button.

5 In the Name field, enter a name like app_start_date.

In the Value drop-down, select Simple.

7 In the text box right of Value, enter the date and time which corresponds to your application start date, that is 2017-01-01T00:00:00, and click Save.

For more information about properties, see How to use properties.

5. Call a web service for the Global entity

Now that you have a mapping, it is time to call the web service.

Previously, you used routes for your mappings to bring data into Decision Insight. Decision Insight supports more than one way to capture data. The one you are about to use is a web service. Decision Insight provides an easy way to create the web service call. Once your mapping is saved, in the Details pane, hyperlinks are available under the Name field for your mapping. 

To create the call to a Web service for the Global entity, follow these steps.

Step Action

Click the a web service link.The Swagger User Interface screen is displayed in a new window or tab.

Swagger User Interface


At the bottom right of the screen, click the highlighted rectangle for Model Schema. The content of Model Schema is pasted in the body text box on the left, which is the body of your service call.


Enter Global between the empty quote marks to the right of ID in the body text box.


Scroll down to the bottom of the page. Click the Try it out! button. Your Web service call is executed.


In the response body area, you might see:

Response Body

If you see this message – about being unable to resolve the instance by key – it means there is an issue with your mapping. Can you remember what might cause the mapping to be unable to resolve an instance? Solve this problem before you can move on.


If you see a response like this one:


That is the positive response from your web service call.

If you have a positive response, you have successfully created the instance for Global.

6. Verify that the relation works as expected

Before you start implementing analytics functions, verify that the relationship is properly set up with the instance editor.

Step Action

From Decision Insight, on the main menu, click Model & Configuration. On the left menu, click Entities.


Click the live instance number hyperlink for the Order entity icon for the Order entity to verify your configuration.

3 Click any order instance in the list of instances to see more details in the Details pane.

 In the Details pane, look at the instance values for the ref2Global attribute.

 All the values for ref2Global are undefined. This must be fixed before trying to use the relation.

Background: Correcting past events

The relation between the instances of Order and the instance of Global has not been initialized. This is expected because you created the relation attribute long after you created the instances of Order. 

Any time you change a model to add a new attribute or relation, Decision Insight adds a placeholder for the value of that attribute or relation. Providing the value is up to you. 

In other circumstances, setting a value for some time in the past could be difficult. With Decision Insight, it is easy. You can correct the data, route, and mapping to build the values and re-run the route as if the past events were occurring in the present time. 

The settings for your time machine controls do not matter. All that matters is the timestamps used for the resolution time in the mapping.

7. Initialize the relation between Order and Global

Update your mapping so that DI considers that the Order and Global were linked ever since the instances of Order were created themselves. Once you re-run your route, the values for ref2Global are populated in the instance editor.

First, update the value of ref2Global in the mapping using the Global entity key.

Step Action

On the main menu, click Data Integration. In the left menu, click Mappings.

2 Select the mapNewOrder mapping.
3 In the Details pane, in the Operations area, click the Add an Operation drop-down, and select the Change value(s) of attribute option. The Select an attribute screen is displayed.
4 Click the Select hyperlink for the ref2Global attribute. A new Set operation is displayed in the Operations area.
5 In the Set operation for ref2global, update the action for the Key. In the drop-down, select the Create an instance of Global if not found at resolution time or after.

In the Set operation for ref2global, update the value for ID. In the first drop-down, select Constant, and in the text box, enter Global.

Note: This corresponds to the same settings you used to call the web service earlier.


Click Save.

Now that the mapping is corrected, you still need to re-run your route to update the data.

Step Action
1 On the left menu, click Routes.
2 Run the rouNewOrder route.
3 Check the logs to make sure there are no errors.

Return to the instance editor and check the values for ref2Global. If at least some values for ref2Global are filled, the initialization was successful.

For information about how to access the instance editor, see Verify that the relation works as expected.

Review: Why did that work?

In the instance editor, the creation time indicates that the link between Order and Global for this instance was created more than a month ago, even though you actually only just created the link. Being able to create such links to manipulate your data in hindsight is one of the strengths of Decision Insight.

Now you are ready to proceed to the next step.

Related Links