OTM – Agent Overview

Agent Overview - Agenda

• What are agents/why have them?
• Agent basics
• More advanced solutions via agents
• Other things agent-related: milestone
monitors and scheduled processes
• What else can fire an agent?
 What are agents? Why have them?

• Listen for OTM events, automate actions

• Configured logic, NOT Customized
(without using a programming language)
Good “C” not Bad “C”
• Hundreds of pre-set actions available
• Allows use of SQL in actions as well
• Logistics IS exceptions and no 2
companies handle them the same way
 Example Agent Actions
• Setting indicators
• Setting statuses
• Checking the weight of an inserted order
and deciding whether to auto plan it or set
an attribute (Mode, itinerary, etc)
• Copying refnums / remarks from orders to
shipments and/or invoices
• Configuring for unique business scenarios
and requirements we don’t have yet
 Configuration Benefits
• Could anyone possibly customize a system to follow every
company’s required response to every real-world scenario?
 Agent Prerequisite

• Before automating a process with an agent, it is

imperative that you have a solid business rule to
automate.
• This does not mean that the process cannot have
branching logic: that is easy to configure with an
agent. I does mean that we must be able to determine
that if “X” happens, and “Y” and “Z” are true, we want
to react by taking option 1.
 Agent Prerequisite: Flow Charted Rules

• If you can build a flow chart Order

Modification

Identify if Order

showing your business logic, Release Type is

either:
Sales_Order
CPU_Order

chances are very good that you Release

Type = Sales
Order?
No
CPU_ORDER

Check Transport
Mode (TM)

can follow the logic using an Yes

Check
Transport
Mode
Is TM =
CPU?
Yes STOP

agent STOP Yes

Is TM = TL
or NULL?
No

Delete TL/LTL
Shipment
Withdraw Tender
and Unassign
Order
No
Delete CPU
Shipment
Withdraw Tender
and Unassign Set TM = CPU
Order

Identify if
shipment
should be DELV 2CPU Change
rated TL or
LTL Send Email to TMS
Team notifying them
that the shipment
which was previously a
TL/LTL is now a CPU
Is Pallet
count >
12?

Yes
Create Direct
Shipment

Set TM = NULL No Set TM = TL

CPU 2DELV Change

Send Email to TMS Team

notifying them that the
shipment which was
previously a CPU is now a TL/
LTL and needs transportation
to be arranged
 Agent Anatomy 101

• There are 47 types of agents, where the type

corresponds to the type of object the events and
actions are related to. (Shipment, Order Release,
Invoice, Voucher, etc)
• An agent has 3 main parts, as depicted on the
Agent screen:
1. Agent Header Tab
2. Actions Tab
3. Error Handling Tab
 Agent Header, part one

The Agent Header is where you define the following:

• You give the agent a unique ID
• You must select an “agent type”. Match the agent
type to the type of object involved with the event(s)
your agent will listened for
• After you set the agent type, OTM fills in the
dropdown showing you the events for which the
agent listen
• After you add an event for an agent, always check
to see if any restrictions are built into that event,
such as “fire for changes by a user, but not from
integration”
 Agent Header, part two

• You can set a saved condition that must pass

before the agent moves into its actions.
• You can set the threshold to tell OTM not to fire the
agent unless a change is greater than some percent
• You can tell OTM to run the agent “as” a specific
user role or using the rights of the domain from the
object firing the agent.
 Example Agent Header

• Here is the agent header screen, showing the

dropdown where you select from the 47 possible
agent types.
 Example Agent Header, continued
• For a “Shipment” type agent, for example, there are
274 pre-defined events you can listen for
 Example Agent Header, continued
• Here are the agent event restrictions for the
SHIPMENT – CREATED event. This agent is
configured to listen for changes made by Integration,
Internal or User sources as shown here.
 Agent Actions

• The actions are the automated instructions that OTM

will execute when the event in the agent header
occurs and all restrictions, saved conditions and
thresholds are met
• Basic examples include setting a green shipment
indicator when a shipment’s tender is accepted or
notifying someone when a shipment gets to a status
of SECURE RESOURCES_NO RESOURCES
 Agent Actions, continued
• On the actions tab you can set up to 100 actions you
want the agent to run (GUI limit)
• The actions are run in order, top to bottom
• Actions include operators such as “IF”, “ELSE” and
“FOR EACH” statements which use saved conditions
to determine if the actions in that loop should execute
• The saved conditions can be made up of queries you
write by hand or queries you write using the OTM GUI
• You can run almost any action that can be run against
the type of object of your agent from the action menus
on a screenset
 Adding an Agent Action
• Click the “+” icon to add an action. Then you can choose an
action (choose a Data Type Association if you wish to affect a
piece of data related to the object that fired the agent.)
 Example Agent Actions

• Here are some of the actions this example agent is

performing
 EventDiagServlet: Check During Testing
• Here is a view of the Event Diag Servlet:
Replace the end of your system’s URL beginning after
glog.webserver.
with this ending:
event.EventDiagServlet (case sensitive)
 Error Handling
• On the Error Handling tab, you can define actions to
run when an error occurs in the execution of the
actions
• You can notify someone when an error occurs, which
is easily done using a specific notification method or
you can defer to the method preferred by the contact
you select
• Errors will cause most agent actions to rollback, but
will not rollback things like Direct SQL updates
• Order Release “Order Modified – Edit Shipment”
errors will often cause disconnected Order / Shipment
pairs. Focus testing here on actions requiring a
cascading update from Order Release to Shipment
Example Error Handling Actions
 Variables
• The $gid shown on the previous example in the
subject of the note is an agent variable
• Variables only “live” while the agent is processing
unless you save them somewhere
• Several variables are automatically saved for you by
OTM any time an agent fires
• $gid is always provided as the object that caused the
agent to fire
• For a full list of variables created, look in the logs
• You can use SQL to capture your own variables
• Your SQL must not return a “null” answer when you
assign a variable, and it must not return >1 result
 Variable Assignment Example

• For example, $hazVal variable receives the result of this

query
 Basic Agent Watchouts
• If you are new working with agents and
remember nothing else from this presentation,
remember these things:
1. Direct SQL must be scrutinized carefully to
avoid data corruption and performance
problems
2. Be very careful not to launch multiple agents on
the same event (deadlocks can result)
3. Test and look at the logs for errors
4. Check EventDiagServlet during stress testing
 Other agent watchouts / suggestions

• It is always wise to limit your agents’ processing so

they do not run when not needed (if possible) (I.E.,
use “Stop” commands where possible to reduce
system resource use
• The ability to send notifications is easy, but resist the
urge to send spam for everything that happens or
people will begin ignoring important notes
• Document your agent using “LOG” actions as much
as possible. Not only does this make it easier to
troubleshoot the agent later when you maintain it, but
it writes helpful “checkpoints” into your system logs
Pay attention to how you’re logging
 Agent Event Setting: “Before Persist”
• Before Persist is a setting on the agent event tab that
can be marked for many events
• Marking “Before Persist” allows agent processing to
happen “in concert” with OTM processing that
launched the agent
• Marking and unmarking this box will cause the list of
actions to change
• RESIST the urge to mark “before persist” and select
an agent action, and then go back and unmark
“before persist.” The GUI will allow this, but you do
not want to do it
• Use “before persist” and the “persist” action together
 Agent Actions-Before Persist
• Here is an example where an order release agent
listens for order modified, with “Before Persist”
unmarked
• The order release changes will attempt to save before
any of this agent’s processing happens
Agent Actions-Before Persist
 Agent Actions-Before Persist
• Now, we re-open the agent and mark the “before
persist” checkbox and save
• With this change in place, we can go see the
differences on the Action tab of the agent
 Agent Actions-Before Persist
• With “before persist” marked, OTM can allow
Shipment edits so it can keep ship unit data (which is
shared between orders and shipments) from getting
out of sync.
 Public Agents

• OTM comes packaged with some of its logic

already exposed (40+ public agents)
• This allows different clients to configure OTM's
behavior without customizing (the Bad “C”)
• Copy PUBLIC agents and edit the copy (Editing
the PUBLIC agent not recommended: changes
lost at upgrades and you lose track of the
“standard” agent configuration
• An example public agent is the
SHIPMENT_EVENT_TRACKER agent
Shipment Event Tracker Agent
 Event Group Example

• The shipment tracker agent relies on the event group

configuration to perform its logic. An example is below
 Expressions
• If you select an IF as the action you want to run, you
can choose a Saved Condition
• In certain cases, however, you can more simply
achieve your goals using the “expression” field as
shown here
Assigning a Variable
 Assigning a Variable, continued

• Here is the assign variable GUI. You can use SQL to

get data, pieces of data or even do computations on
data to store the result as a variable
• Using PL/SQL further extends the possibilities
Using a Variable – Inserting Data
 Copy Refnums Action

• When doing a straight copy (not manipulating the data) of refnum

data, use the “Copy Refnums” actions
 Changing Data
• Here is a SQL statement setting the IS_HAZARDOUS
field to “Y”
 Custom Agent Events
• You can create your own agent events allowing one agent to call
another or hook an agent to an action menu on a screenset
• Here is how you access a screen to add a new agent event
especially useful when you need to be sure nothing else (internal
or agent) can fire your agent unexpectedly
 Custom Event: Column-specific change
• You can create a custom event listening for a change
to one particular column
• You can add the agent event in the AGENT_EVENT
table as normal, but if you also populate the
NOTIFY_SUBJECT,
AGENT_EVENT_TABLE_MAPPING and
AGENT_EVENT_COLUMN_MAPPING
tables, you can cause OTM to listen for a change to 1
column
• Some columns may not be supported (Ship Unit
Count works, Order Release Type seems not to work)
 Example SQL
• Here is some example SQL to add data to the 4 tables needed to listen
for a change to 1 column. (Change domain from “TL” to your domain
name)
• NOTE: You must restart OTM after adding this data in order to use it

• INSERT INTO NOTIFY_SUBJECT

(NOTIFY_SUBJECT_GID,NOTIFY_SUBJECT_XID,NOTIFY_FUNCTION_GID,NOTIFY_SUBJECT_TEXT,SUPPORTS_INVOLVE
D_PARTIES,SUPPORTS_SERVICE_PROVIDER,DOMAIN_NAME) VALUES ('TL.TL SHIPMENT - SHIP UNIT COUNT
MODIFIED','TL SHIPMENT - SHIP UNIT COUNT MODIFIED','SHIPMENT_EVENT','TL SHIPMENT - SHIP UNIT COUNT
MODIFIED','Y','Y','TL')

• INSERT INTO AGENT_EVENT (AGENT_EVENT_GID, AGENT_EVENT_XID,DATA_QUERY_TYPE_GID,

NOTIFY_SUBJECT_GID, AGENT_EVENT_PARENT,EVENT_TOPIC_CLASS, IS_CUSTOM, DOMAIN_NAME,
IS_LIFETIME_MOD) VALUES ('TL.TL SHIPMENT - SHIP UNIT COUNT MODIFIED','TL SHIPMENT - SHIP UNIT COUNT
MODIFIED', 'SHIPMENT', 'TL.TL SHIPMENT - SHIP UNIT COUNT MODIFIED','SHIPMENT - MODIFIED',
'glog.server.workflow.lifetime.shipment.CustomModShipmentEvent','Y','TL','Y')

• INSERT INTO AGENT_EVENT_TABLE_MAPPING (AGENT_EVENT_GID, TABLE_NAME,DOMAIN_NAME) VALUES ('TL.TL

SHIPMENT - SHIP UNIT COUNT MODIFIED','S_SHIP_UNIT','TL')

• INSERT INTO AGENT_EVENT_COLUMN_MAPPING (AGENT_EVENT_GID, TABLE_NAME,COLUMN_NAME,

DOMAIN_NAME) VALUES ('TL.TL SHIPMENT - SHIP UNIT COUNT MODIFIED', 'S_SHIP_UNIT', 'SHIP_UNIT_COUNT','TL')
 Custom Event: Column-specific change
• Here is the agent header for an agent listening for our
custom event
 Custom Event: Column-specific change

• Here is the action this agent performs

• For this demo, we only place a message in the logs
 Custom Event: Column-specific change
• Here is a look at the logs showing the message
appearing after we made a ship unit count change to
shipment TL.01010
 Milestone Monitors

• While Agents listen for things to HAPPEN, Milestone Monitors

can listen for things to happen in the wrong sequence, or for
things to NOT happen by a certain time
• Monitor Profiles are outside the scope of this discussion, but they
use agents to do their automated work, and there is an important
thing to remember:
Agents used by Monitor Profiles are left marked “INACTIVE”
though they are still called to perform actions for the Monitor
Profile
• Remember this when determining whether you need to keep or
migrate agents that are inactive—they may still be important!
 Scheduled Process
• You can also kick off an agent by scheduling a process for a data
query or just by running the process once
• The process below would trigger our custom event for all
shipments matching the SH_HAS_ORDER_WITH_HAZMAT
query
• This mechanism is very useful for checking for conditions
periodically and either automating corrective action or notifying a
contact that an issue exists
 Firing Agents via Screenset Actions
• You can configure OTM to allow users to fire agents
directly from screenset actions. Below is an example
from the Action Manager screen
 Using the Action Menu to Fire Agent
• After adding the new action to a screenset and adding
that screenset to my menu, I can now select a
shipment, then select my Agent Action off the Action
Menu as shown below
 Agent Fired

• After selecting the action, we can see in the logs that our agent
fired because it has an action to write this line in the logs