Creating a bound entity

If the bound entity of an agent is not already in the system, you can create it upon the arrival of an event. You create the bound entity in the action part of a rule. Typically, the creation of the bound entity happens with the first event that is received for this entity.

In a rule, you can create the bound entity and set its values. The values of the bound entity are based on the attributes that are defined in the business model. However, you must not specify the entity ID. The agent sets the identifier of the bound entity. The entity ID is calculated from the information in the routed event and from the entity type that is specified in the agent descriptor.

Important: Do not specify the entity ID. If you specify an entity ID that is different from the ID contained in the event an error is raised.

When the rule is executed, the entity is created in the Insight Server, and the entity life cycle starts.

In the following example, when a new account event is received, the rule checks that there is no account entity. Then, the rule creates a new account entity and populates it with the customer information from the event and the date of the event. The rule also specifies that the account is new.

when a new account event occurs, called 'the event'
if
    'the account' is null
then
    set 'the account' to a new account where
        the customer is the customer of 'the event',
        the opening date is 'the event',
        the status is NEW;

Warning: When you create the bound entity in a rule, avoid adding an else part. This might lead to a confusing result where both the then and else parts would be applied. For more information on this behavior, see Rule actions and Rule behavior.

If you have many rules in your agent, it is inconvenient to check for the existence of the bound entity in each rule. You can use rule priorities to do this check only once for each event type. In the attributes of the rule, you set the highest priority on the rule that creates the bound entity so that its action is executed before the actions of the other rules of the agent. The default priority is 0, so if this rule is the only one with a priority, you can set it to any positive value. For more information, see Setting the priority of a rule.

For example, the following rule checks for the existence of an order entity upon arrival of a pizza order event. The rule creates the order entity if it does not exist.

when a pizza order occurs
if
  ‘the order’ is null
then 
  set ‘the order’ to a new order where
       the customer is the customer of this pizza order,
       the start time is this pizza order,
       the order status is PLACED,
       the pizza store is the pizza store of this pizza order;
  set the pizzas of ‘the order’ to the pizzas of this pizza order;

The last statement of the rule initializes a collection variable. In this type of rule, you initialize collections in a separate statement.

If the priority of this rule is the highest compared to the other rules, you do not have to check that the order is null in the other rules. For example, the following rule has a lower priority, and does not check the existence of the order entity.

when a pizza order occurs
then
  set the price of 'the order' to the price of 'the order' +
  0.5 * the distance between the location of the pizza store of 'the order' and
  the location of the address of the customer of 'the order' in kilometers;