Agent Variables

Agent Variables provide the ability to add variables to agents in order to make agent programming more flexible.

Using Agent Variables, saved queries can be used to look up values not currently available to agents. These values can then be plugged into agents and used to perform specific actions.

Agents support variable assignments and variable references in agent actions. Variables are also allowed in saved queries, which can then be used in agent saved conditions.

Variables are global, and can be used in the saved query screen, the finder screens, and the action tab of the agent manager.

As shown below, the syntax for variables is (where the $ sign indicates the use of a variable):

$varName

In Agent Actions

Oracle Transportation Management provides an agent action to perform variable assignments from a saved query. This is done through the Agent Manager (Agent Manager is accessed via Business Process Automation > Agents and Milestones > Automation Agent. It is on the Actions tab). This action has two input fields:

Variable Name
Saved Query Name

In the following example, created through the Agent Manager, the result of the SQL query SLG is assigned to a variable called $sourceLocationGid. This variable is then used in the agent as defined.

Variable Name: $sourceLocationGid

Saved Query Name: SLG

select source_location_gid from shipment

where shipment_gid = $shipmentGid

In Saved Queries

The following is an example of variables in a saved query (in this example you would name the query what you wanted -- this shows the SQL and the variables assigned in it). This can be created through a saved query in the Agent Manager, or through saved queries in Power Data.

select shipment_gid from shipment_stop

where shipment_gid = $gid and stop_num = $stopNum

Pre-Defined Variables

A set of predefined agent variables for events has been set up in the system. The following pre-defined variables are defined:

All Events

Name	Type	Description
$agent_instance	String	the unique hash ID for the agent workflow. This matches the agent ID included in the logs.
$child_event_gids	String	comma separated list of child event GIDs
$document	String	document GID, if applicable
$documentType	String	document definition GID
$event_Gid	String	agent event GID, if applicable
$gid	String	Primary key of event. For transaction agents, the i-transaction_no of the transaction record.
$log_process	String	the Log process ID for the top-level process triggering the agent.
$transaction	String	the transaction ID. This is only available when the agent is triggered as part of an inbound transmission.
$transmission	String	the transmission ID. This is only available when the agent is triggered as part of an inbound transmission.

All Shipment Events

Name	Type	Description
$shipment_gid	String	shipment GID

Error Block

These agent variables are available to the Error block if an error is encountered in the normal action block. For more on handling errors, see the Error Handling topic.

Name	Type	Description
$error.action.gid	String	the GID context of the faulty action
$error.action.name	String	the name of the faulty action
$error.action.parameters	String	the parameters of the faulty action
$error.action.sequence	Number	the database sequence number of the faulty action
$error.action.type	String	the data query type for the faulty action
$error.message	String	the error message for the first exception causing the fault

Shipment Status Events / Shipment Group Status Events

Name	Type	Description
$i_transaction_no	Number	event transaction number
$event_date	Date	time stamp for the event
$status_code_gid	String	status code of the event
$status_reason_code_gid	String	reason code of the event
$insert_date	Date	insertion time for the event
$event_group_gid	String	event group
$event_group	Map	event group attribute map
$location_gid	String	event location
$location_xid	String	event location XID
$stop_num,stopNum	Number	stop number
$ship_group_gid	String	shipment group or the event (shipment group status events only)

Shipment Stop

Name	Type	Description
$shipment_gid	String	shipment GID
$stop_num	Number	stop number

Shipment Special Service

Name	Type	Description
$shipment_gid	String	shipment GID
$shipment_spcl_svc_seq	Number	shipment special services sequence number

Order Base Status Events / Order Release Status Events

Name	Type	Description
$i_transaction_no	Number	event transaction number
$event_date	Date	time stamp for the event
$bs_status_code_gid	String	status code of the event
$bs_status_reason_code_gid	String	reason code of the event
$insert_date	Date	insertion time for the event
$event_group_gid	String	event group
$event_group	Map	event group attribute map
$order_base_gid	String	order base of the event (order base status events only)
$lines, $obLineGid	String	comma separated list of order base line GIDs (order base status events only)
$order_gid	Number	order release of the event (order release of the event only)
$lines, %orLineGid	String	comma separated list of order release line GIDs (order release of the event only)

Tracking Events

Name	Type	Description
$AHEAD_LATE	Date	gets the hours early or late by taking the difference between planned arrival and estimated arrival times
$AHEAD_LATE_ABSOLUTE VALUE	Date	subtracts the planned time from the ETA – always a positive number
$CAR_DEST_ETA	Date	gets the ETA time from the tracking event
$PLANNED_ARRIVAL_TIME	Date	gets the planned arrival time from the associated shipment
$i_transaction_no	Number	event transaction number
$event_date	Date	time stamp for the event
$event_group_gid	String	event group
$event_group	Map	event group attribute map
$status_code_gid	String	status code of the event
$status_reason_code_gid	String	reason code of the event
$event_recieved_date	Date	time stamp of event receipt by Oracle Transportation Management
$location_gid	String	event location
$stop_num	Number	stop number

Following are some additional agent variables for shipments that can be used in expressions for agent actions when listening to the SHIPMENT STATUS - RECEIVED or the SHIPMENT STATUS - TRACKING event:

Name	Type	Description
$i_transaction_no	Number	event transaction number
$event_date	Date	time stamp for the event
$event_group_gid	String	event group
$event_group	Map	event group attribute map
$insert_date	Date	insertion time for the event
$location_gid	String	event location
$location_xid	String	event location XID
$status_code_gid	String	status code of the event
$status_reason_code_gid	String	reason code of the event
$stop_num	Number	stop number

Simple Oracle RDBMS expressions are permissible as well. For example, the following is valid:

$weight + $deltaWeight

You can also search for variable results in a Search page. The agent containing the variable definition has to have run and assigned a value to the variable in order for the search page to return a result. For example, if you defined a variable named $contact, then you can search for $contact in the Contact ID field in the Contact tab under Transportation Planning and Execution > Location Management > Location Manager. If the agent containing the $contact definition ran and assigned a value to it, then your search will return a result to you.

Use Nested GID in Agent Data Type Association

This impacts an agent with a Data Type Association sub-loop. E.g., assume you have a Shipment Agent with actions:

LOG: Shipment=$GID

(SHIPMENT TO ORDER RELEASE) LOG: Shipment=$GID

The variable PARENT for these nested loops allows you to write actions like:

LOG: Shipment=$GID

(SHIPMENT TO ORDER RELEASE) LOG: Order=$GID, Shipment=$PARENT

The GID variable is remapped to the order release ID in the second statement while the shipment ID is available in a PARENT variable. Note that this mapping of PARENT and GID is always available for FOR loops.

CHILD_EVENT_GIDS Variable

The CHILD_EVENT_GIDS variable will be populated only for "MOD" events including user-defined MOD events. If there are child events defined and detected for the raised parent event, the child events will be populated as a comma separated list in the "CHILD_EVENT_GIDS" variable.

Example

An agent listens for ORDER BASE - MODIFIED event with child events ORDER BASE - INVOLVED PARTIES MODIFIED, ORDER BASE - DATES MODIFIED, and ORDER BASE - STATUS CHANGED being selected as parameters. If in a transaction the order base dates and status are changed, the ORDER BASE - MODIFIED event with child events ORDER BASE - DATES MODIFIED and ORDER BASE - STATUS CHANGED events will be raised. In this case, the "CHILD_EVENT_GIDS" variable will be populated with "ORDER BASE - DATES MODIFIED, ORDER BASE - STATUS CHANGED".

IN Operator

The IN operator takes the expression to the left of the operator and checks to see if its value exists in the list of values represented by the variable to the right of the operator. This operator works like the "=" operator when used with a variable that evaluates in to a single value.

Usage:

IF ORDER BASE - STATUS CHANGED IN $CHILD_EVENT_GIDS {
&
}
ELSE IF ORDER BASE - DATES MODIFIED IN $CHILD_EVENT_GIDS {

}

Sample Steps

The following is a step-by-step example of how to set up and use agent variables. In this example, there is a multi-leg shipment with three stops. You want to set up an agent that listens for delayed shipments. After detecting a late shipment, it will identify what stop is next, look up the contact for that stop location, and email them a notification.

Create a new Agent.
Name the Agent ID = LISTEN_FOR_DELAYED_SHIPMENT.
Select SHIPMENT as the Agent Type, and mark it as Active.
Select SHIPMENT-STATUS DELAYED as the Event, and do not enter a Condition.
Create a new Action.
Select ASSIGN VARIABLE from the list.
Name the Variable Name = $STOP_CONTACT_GID.
Create a new Saved Query, name it NOTIFY_CONTACT, and do not mark Use In Finder.
Select SHIPMENT for the Object Type ID.
In the SQL Query fields, type:

SELECT C.CONTACT_GID
FROM CONTACT C, SHIPMENT_STOP SS
WHERE SS.SHIPMENT_GID = $GID AND
SS.STOP_NUM = $STOP_NUM
AND SS.LOCATION_GID = C.LOCATION_GID
After saving, create another new Action.
Select NOTIFY CONTACT from the list.
For the Contact type $STOP_CONTACT_GID.

Note: Make sure to appropriately save and finish your work at each point.