Entity initialization

You can define how to initialize entities independently from agents that act on them. Use the business model to define a relatively simple initialization or use the Decision Server Insights Java™ API to implement more complex operations, such as accessing a database to retrieve data. If an event is related to several entities then each of the entities can be initialized by applying an initialization.

Business model initialization

An entity that is defined in the model can be implicitly initialized by using a statement for each entity type you want to initialize. The initialization is always in response to one or more events. If an incoming event is related to an entity that does not exist then an entity with the given identifier is created by the initialization.

An initialization statement cannot contain conditions, and actions are optional. For example, the following statement defines how an entity named vehicle is initialized from an event named vehicle activity.

a vehicle is initialized from a vehicle activity, where this vehicle comes from the vehicle of this vehicle activity.

Important: When a statement defines no actions, the entity is created with only the entity ID.

Defining an entity initialization in the business model from an event type causes the event to be routed to the runtime when it occurs. The routing happens regardless of whether the agents within the solution listen for this event type or not. If the bound entity exists the event is still routed.

The initialization of an entity happens before any rule agent reacts to an incoming event. However, when an event triggers the initialization of several entities, a rule might be executed before a remote entity is initialized. To make sure that all entities are initialized before a rule executes, you can add a condition in the rule so that it sends an event if the entity is null.

Java API entity initialization

When you implement an initialization by using the Java API, you use the Entity Initialization Extension wizard to create a dedicated EntityInitializer API class. The class is associated to an entity type by using the @EntityInitializerDescriptor annotation. The generated EntityInitializer class contains two methods.

createEntityFromEvent(Event)

The createEntityFromEvent(Event) method is called when a specific event type occurs, the business model contains an initialization statement for the entity type, and the bound entity does not exist. Use the method to create an entity instance or choose to create an instance of any subtype. You can overrule the request for the entity initialization in the business model by returning the value null. Or you can read the event and initialize the bound entity with data contained in the event.

The default implementation creates an uninitialized instance of the entity type that is defined in the business model.

    @Override
    public Vehicle createEntityFromEvent(Event event) throws ComponentException {
        Vehicle entity = super.createEntityFromEvent(event);
            
        // TODO Initialize the attributes of the entity that depend on the event
            
        return entity;
    }

intializeEntity(Entity)

The intializeEntity(Entity) method is called when an entity is initially created. You can use this method to access external data sources, update entities other than the bound entity, and emit events. It has access to the solution properties and the model factories, but it cannot access the initializing event. The intializeEntity(Entity) method is also called if you create the entity with the REST or TestDriver methods.

The default implementation creates the identity function, and nothing else.

    @Override
    public void initializeEntity(Vehicle entity) throws ComponentException {
        super.initializeEntity(entity);
        
        // TODO Initialize the attributes of the entity
        
    }

It is possible to call one EntityInitializer implementation from another. For example, a CarInitializer extension might extend an extension that is named VehicleInitializer.

Tip: You can use a single extension project to package multiple initialization extensions, and include DataProvider extensions that share common APIs and registration information.