Automation Agent

This page is accessed via Business Process Automation > Agents and Milestones > Automation Agent.

The Agent Manager allows you to construct agents that are key components of configurable Oracle Transportation Management processing. An agent listens for an Oracle Transportation Management event, verifies a user-defined condition, and executes one or more actions that you choose from an action library. For example, you could create an agent that listens for order base modifications from a specific order owner. If modifications are detected (usually through integration although an agent can be configured for other sources) the agent can:

fully propagate the order base change by unassigning its order release from an existing shipment and build a new shipment
acknowledge the order modification and set the appropriate statuses
send the order base in XML format to an involved party
notify the planner via email, fax, or some other communication method

You can select specific events, conditions, and actions for each business object. You can also specify the actions to take if errors occur during processing.

An automation agent operates against a specific Oracle Transportation Management business object such as an order base, order release, shipment, etc., and includes a list of events that can occur, optional conditions that are checked, actions that perform an Oracle Transportation Management process, and error controls to alert you when problems are encountered with the agent.

Create an agent using the following tabs that you must follow sequentially:

Agent Header defines basic information such as ID, agent type, and whether the agent is active as well as the events and event conditions that trigger the agent to process actions.
Actions defines the actions that are executed when specific events are met.
Error Handling defines the actions to take when errors occur during the processing of an agent.

Note: Oracle Transportation Management provides sample agents in the PUBLIC domain. It is recommended that all public agents be deactivated upon installation. You can then use copies of them in the non-public domains.

Agent Header

Use the Agent ID field to uniquely identify the agent using any combination of alphanumeric characters.
The Agent Type represents the Oracle Transportation Management business object for which you are creating an agent. The Agent Type determines the events and actions you can use for the agent.
Select the Domain Name in which you want to store the agent when you first add the agent. The domains listed are those to which you have access rights.
Enter a Description if you want to specify a description.
Select the Active check box to turn on the agent. It is best not to activate the agent until you are sure you have created the agent that you want.
Select the Allow Lock check box to hold an object lock during the processing of all agent actions. This check box determines how long Oracle Transportation Management locks the business object of the agent. For example, assume you modify an order release. An agent fires off the modification that calls Set Status and Set Indicator. For each individual agent action, we lock the order release to avoid user modifications of the order while it's being modified. By checking the Allow Lock box, you are telling Oracle Transportation Management to lock the order release for the duration of the entire agent, rather than just individual actions. This provides a transactional view of the agent, since the order will be locked across both the Set Status and Set Indicator actions.

Note that these actions may be published into different queues. If the queues are significantly backed up, using Allow Lock may cause a significant increase in contention on the order. For this reason, it is not enabled by default.
If this agent will process for a long time, select the Long Running Task check box. All long-running agents are interruptible as the agent will check for interruption before the execution of each agent action.
Select a Log Level to override the default set by the glog.agent.defaultLogLevel property. This controls the level of Agent logging for this particular agent. See Configuring Agent Logging and Statistics for more information on using this.
Select a Statistics Level to override the default set by the glog.agent.defaultStatsLevel property. This controls the level of Agent statistics collection for this particular agent. See Configuring Agent Logging and Statistics for more information on using this.

Agent Events

An agent responds to events that occur during the life cycle of an Oracle Transportation Management business object. These events are the same as those standard Oracle Transportation Management events that you can use to configure notifications such as Order Base - Modified, Order Base - Released and so on.

Choose one or more events from the list. The events that appear are specific to the Agent Type that you selected. An agent may listen to one or more events; however, they must apply to the same business object type. For example, an agent can respond to Order Base - Created and Order Base - Modified events. Both of these reflect lifetime events for an order base, and the Order Base ID serves as a context for the agent. An agent cannot respond to both Order Base - Created and Shipment - Tendered events since these events are for different business objects. If you choose multiple events, Oracle Transportation Management initiates action when any event occurs (not all).
Click (if it appears) next to any event to configure restrictions.

Saved Conditions

Before executing any actions for an event, an agent always checks the business object for a Saved Condition. A Saved Condition is one or more Saved Queries that contain search criteria; similar to those that you can create for most business objects through Oracle Transportation Management Managers and Power Data. If the criteria defined in a Saved Condition is met, the agent proceeds to execute its actions; otherwise, the agent is ignored.

You define a Saved Query using the standard Oracle Transportation Management Search pages that are available in most managers and power data options. However, (unlike the Search pages for managers), an agent condition tests a single business object against the search criteria. The available criteria, however, conform exactly to the criteria that is available on the standard Search pages. For example, assume there is an agent for the Shipment - Created event. You can restrict the agent to shipments whose service provider is XYZ Corporation by defining a Saved Query that searches for only XYZ Corporation shipments. When a shipment GUEST.S101 is created, the agent is triggered and tests whether XYZ Corporation is the service provider for the shipment and, if so, the agent executes its defined actions.

Use the Saved Condition field to optionally enter (or find) a condition or create a new one. A Saved Condition consists of an ID and the assignment of one or more Saved Queries. A Saved Query is a collection of criteria which must be met to satisfy a search. To match the condition against one of a set of queries, you define the condition as a set of Saved Queries. If the business object satisfies ANY of the agent's saved queries, the condition is met.

Enter a unique ID, select a domain name (if different than the current domain) and proceed to the saved queries section to find existing query records or create new records.

Threshold

The Threshold Manager can be used to control when modification events occur. For example, you can define a threshold for the ORDER BASE - MODIFIED event that controls whether this event is raised based on the percentage change of weight or volume.

In addition to event restrictions and Saved Conditions, thresholds are another way an agent can be triggered.

When a threshold is defined at the agent level, the threshold checks against data changes related to the events the agent is listening to. If the changes pass the threshold tolerance, the agent will be triggered.

For example, you have an agent with a threshold listening for an ORDER BASE - MODIFIED event. When the event occurs, the threshold is checked to see if has been passed. If it has, the actions on the agent will be triggered.

Thresholds can also be set up for the If and Elseif agent actions.

Note: Agents and agent actions do not support thresholds with object attribute names beginning with "Total." For instance, "Total Gross Weight."

Run As

An action requested by one user can execute with the data security of another. The other user can be specified by:

User Role - then in the user role field, enter the appropriate role.
Object - the action runs as ADMIN user of the business object's domain. If the object is a sequence number, such as a tracking event, then instead of a GID, you must provide a Domain query that returns the domain of the tracking event.

The ability to set up an action to run as another user is restricted by security of the user configuring the action. For actions specified by user role domain, this check can be performed when a user sets up the impersonation. For actions specified by a business object, the check must be performed when the action is run.

Reason for Change

To track updates to an agent, you can enter a reason for changing the agent. The Change History button shows all of the reasons and dates that the agent changed.

Statistics

Clicking the Show/Hide Statistics button will display/hide agent statistics at the top of the page, such as the Run Time, if they are available. If the Agent statistics level is Agent or Actions, the agent header will show the average and maximum Run Time since the Since date. This run time is measured from the publish of the first agent action to the agent process' completion. Note that it does not include the time to evaluate any agent saved condition. If the Agent statistics level is Actions, each action will show the average and maximum completion time for that action. This time is measured from the time the action begins execution to the completion of the action process.