Completing the agent descriptor

You must complete the agent descriptor (agent.adsc) to define the entity to bind the agent to, the events that the agent processes, and the routing logic.

Before you begin

Your entities and events must be defined in a business model. In the business model, you must set a relationship from the event to the entity to enable the mapping between the entity and the event.

About this task

When you create an agent project, an agent descriptor file is created (agent.adsc).

In the agent descriptor file, you define the routing conditions to apply to the event. The descriptor has a business vocabulary that refers to the event and entity types in the business model.

This agent descriptor file contains a template that you must complete in the editor to define the agent logic.

Procedure

Specify the name of the agent within the single quotation marks, or keep the default name.
In the <entity> placeholder, select the type of the bound entity.
Optional: Add the priority of the agent by using the construct whose priority is <priorityValue>. The value of the priority can be low, medium, high, or a number.
In the <event> placeholder, select the event type to process.
Optional: Add a filtering condition on the event by using the construct when <condition>.
In the <source> placeholder, select the variable of the bound entity.
In the <target> placeholder, define the way to access the entity from the event.
When an event comes into the system, it contains a string, which is the ID of the entity. You must tell the system how to find the entity ID from the event that is received. An agent might process more than one event type, but the ID of the entity must be available in each of the event types that is processed.
Optional: Add the time horizon for which the events are kept in working memory by using the construct with a horizon of <time duration>. The value of <time duration> must be a positive value. The value can be a combination of multiple units, for example 12 days 8 hours. Each event is usable by the agent during the duration that is defined by the time horizon, starting from the time stamp of the event. When the current time reaches the time point that succeeds this period, the event is removed from the working memory and the agent cannot use it anymore. If the time horizon is set to 0, events are not visible to the solution after they are processed. Setting the horizon to 0 can improve performance for event types that occurs in high volume, but that are not used in aggregations or correlations. The maxHorizon solution property limits the maximum time horizon that you can define for an event in the agent descriptor. If the agent's horizon is longer than the maxHorizon property, the maxHorizon property overrides the agent's horizon.
Optional: Define other events to process.

Results

The following agent descriptor shows an airport agent that is bound to an airport entity, and that processes two events.

The name of the agent.
The bound entity type.
The priority of the agent.
The event types that the agent listens for and processes.
The bound entity.
The expression to retrieve the string that corresponds to the bound entity in the event.
The filtering on the event.
The time horizon of the event.

The agent descriptor sets an authoring context that provides variables to reference the entity and events in the rules. For example, if the bound entity is a flight, in the rules of the agent, the entity is referred to as 'the flight'.

You can define event types to process in the agent descriptor without using the data of these events in current rules. The data can then be stored in memory to be used in rules that you create later. For example, if you want to retrieve the average temperature reading of the past week, you can add the following event to the list of events that your agent processes:

- temperature reading,
    where this location comes from the location of this temerature reading
    with a horizon of 7 days

One week later, the temperature readings of the past 7 days are stored in the agent. You can then add the following rule that aggregates this data:

when a temperature reading event occurs,
define 'average temperature' as the average degrees of temperature readings over the last period of 1 week;
if 
    'average temperature' is more than 25
then 
    emit a new temperature warning

Examples

Agent that processes one event

In the following example, the bound entity of the agent is a ticket, and the agent listens for a ticket check-in event. The ID of the ticket entity is the ID that is contained in the ticket check-in event.

'ticket checkin agent' is an agent related to a ticket, 
processing events:
- ticket checkin event, where this ticket comes from the ticket of this ticket checkin event

Tip: In the target placeholder, you can use variables that implicitly refer to the event. For example, instead of writing the ticket of this ticket checkin event, you can write the ticket.

Agent that processes several events with a priority and a condition

The following agent descriptor shows an airport agent that is bound to an airport entity, and that processes two events. The priority of the agent is high. If another agent listens to the same events with a lower priority, the AirportAgent agent processes these events first. This agent description also contains a filtering condition on the airport open event. The agent processes only airport open events that happen in August.

'AirportAgent' is an agent related to an airport, whose priority is High,
processing events:
    - airport closed event, 
    	where this airport comes from the airport of this airport closed event
    - airport open event when the datetime of this airport open event is in August,
        where this airport comes from the airport of this airport open event

Agent that processes several events, where one of the events has a specified time horizon

The following agent descriptor shows an airport agent that is bound to an airport entity, and that processes two events. The agent keeps the airport open events in working memory for a period of 15 days from the time stamp of each event. When the current time reaches the end of this period, the airport open events are removed from the agent's memory. The agent descriptor does not specify a time horizon for the airport closed events, so they are kept in the working memory for the maximal time horizon of the agent or solution.

'AirportAgent' is an agent related to an airport,
processing events:
    - airport closed event, 
    		 where this airport comes from the airport of this airport closed event
    - airport open event,
        where this airport comes from the airport of this airport open event
        with a horizon of 15 days

Agent that processes an event where the entity ID is based on two fields of this event

In the following example, the bound entity of the agent is a customer, and the agent listens for a subscription event. The ID of the customer entity is composed of the first name and last name of the main contact that is contained in the subscription event.

'subscription agent' is an agent related to a customer,
processing events:
    - subscription event, where this customer comes from the first name of the main contact of this subscription event + "/" + the last name of the main contact of this subscription event

What to do next

After you complete the agent descriptor of the rule agent, you can create rules to define the business logic of the agent.