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

  1. Specify the name of the agent within the single quotation marks, or keep the default name.

    By default, the agent name is composed of the bundle symbolic name and the agent name that you specified when you created the Java™ agent project: bundle_symbolic_name.agent_name. The bundle symbolic name is in lowercase.

    If you modify the default name of a Java agent, you must also update the name in the blueprint.xml file.

  2. In the <entity> placeholder, select the type of the bound entity.
  3. 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.
  4. In the <event> placeholder, select the event type to process.
  5. Optional: Add a filtering condition on the event by using the construct when <condition>.
  6. In the <source> placeholder, select the variable of the bound entity.
  7. 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.

  8. 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.
  9. 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.

Screen capture of an agent descriptor.
  1. The name of the agent.
  2. The bound entity type.
  3. The priority of the agent.
  4. The event types that the agent listens for and processes.
  5. The bound entity.
  6. The expression to retrieve the string that corresponds to the bound entity in the event.
  7. The filtering on the event.
  8. The time horizon of the event.
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 define a rule that aggregates this data over the past week.

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 and event where the entity ID is based on two fields of the 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
Agent that processes an event where the entity is a parent type of the bound entity
You can bind an event to the parent type of an entity. For example, consider the following business model: 
a person is a business entity identified by a string, named the name.
a patient is a person .
a doctor is a person . 
a message to person is a business event .
a message to person is related to a person.
a message to patient is a business event .
a message to patient is related to a patient.
If the agent is related to a patient entity, you can bind the event to the person entity. In this example, the runtime environment checks whether the person entity of the event is an instance of a patient or a doctor. The agent processes the event only if the entity of the event is a patient.
'healthcare' is an agent related to a patient,
processing events:
    - message to person, where this patient comes from the person of this message to person

Agent with no bound entity

A rule agent must have a bound entity, but you can develop Java agents that are not bound to an entity. An agent can receive a stream of events, and emit outbound events that are based on the event stream, without requiring access to an entity. For example, if you want to trigger an alert when a number of transactions occurred.

To create a Java agent with no entity, you omit the is related to and where <mapping> clauses, as shown in the following example:

'transactionagent.MyAgent' is an agent, 
processing events: 
	- transaction event

What to do next

Write Java code in the Java or predictive scoring agents to perform actions following the reception of events.