MCF Platform: AGENTS 101 - STERLING MCF SERVICE DEFINITION FRAMEWORK

Answer

AGENTS 101 - STERLING MCF SERVICE DEFINITION FRAMEWORK

Most of the information here can be found in the Sterling MCF Application Platform Configuration Guide included with the Sterling MCF Documentation.  The rest of this article will refer to this guide as the APC Guide. 

Configuring a Transaction/Agent

Before beginning, make sure you have the APC Guide handy.

1) Prepare/look up JMS Connection Details

You will need to either create or look up the names of each of the following before creating/configuring an agent transaction.  For information on finding/creating these, refer to your application server or JMS Server's documentation.

JMS Connection Factory - Used by an agent thread to connect to the JMS server.
JMS Server - One or more transactions can use the same server based on your needs.
JMS Queue - The destination where the messages generated by the agent will be sent.

2) Configure Criteria Details

Each "Agent Criteria" is basically a different way to call/trigger the agent.  If you want to run multiple threads of this transaction at a time and have each thread use a separate Agent Server or JMS queue, etc., you will need to create a separate criteria for each.

If you require messages to be consumed from the JMS queue in first-in-first-out (FIFO) sequence, you should not use multiple JMS queues for the same agent.

Agent Server - Use an existing agent server or create a new one and associate it to this agent criteria.  One Agent Server per agent is recommended.

Configure the other fields as explained in Section 4.2.6.1.2 of the APC Guide.

3) Configure Criteria Parameters

Find the transaction in the APC Guide, Appendix A.3 - A.6. The transaction listed in the guide may not match the Transaction name exactly.  For example, the transactions "CLOSE_PURCHASE_ORDER" and "CLOSE_SALES_ORDER" will both use the "CLOSE ORDER" agent, except each will pass a different document type.

The APC Guide will explain the parameters for this agent.

4) Configure Transaction Details

"This transaction is time-triggered" should be checked.

If you want to trigger an action for any of the transactions events, double-click the event, configure its details if needed and drag/drop the action you want triggered into the Event Handler window.

For more details see section 4.2.6.1 of the APC Guide.

STARTING THE AGENT SERVER

For the Agent to run the Agent Server you configured, it must be started.  Sterling MCF provides a nice easy way to do this.  Run the following command from the <INSTALL_DIR>/bin folder:

agentserver.sh <agent_server>

or run it in the background using the following command:

nohup agentserver.sh &

In this mode, screen output will be written to $YFS_HOME/bin/nohup.out

Additionally, you can use the System Management Console (under the System tab in the MCF Console menu)

TRIGGERING THE AGENT CRITERIA

For the agent to actually execute, you must trigger the Agent Criteria you configured in the Transaction Details.

Option 1) Configure the Agent Criteria Details to automatically schedule a trigger message for the agent periodically.

Option 2) Send a trigger message from the command line (or from Unix cron, etc.) with this command:

triggeragent.sh <agent_criteria>

HOW DOES THE AGENT KNOW WHICH RECORDS TO PICK UP?

If the flag "This transaction is task based" is checked in Transaction Details (Others tab), the previous transaction(s) in the pipeline will insert a record in YFS_TASK_Q so this transaction will know to process that document.  The agent will determine which documents to process by querying the YFS_TASK_Q table.

In general, you would typically set this flag for pipeline transactions like SCHEDULE_ORDER and RELEASE_ORDER, and leave it unchecked for on-demand transactions such as AVAILABILITY_MONITOR and REQUEST_COLLECTION.

TASK BASED:

An agent selects a YFS_TASK_Q record for processing if:

-The TRANSACTION_KEY matches the agent's TransactionID
-The AVAILABLE_DATE field is valid

The first agent to find a record with the agent's TransactionID specified will process the document and delete the YFS_TASK_Q record when finished.

QUEUE-BASED:

If the agent is configured to consume messages from a JMS queue, the triggeragent script or method will send a message to the JMS queue configured for the agent criteria passed in to the script.

The JMS message specifies the TransactionID that should be triggered as well as some additional parameters (probably the agent criteria parameters configured above) if needed. 

As soon as an active Agent Server that is monitoring this queue sees a message with its TransactionID, the agent will execute and consume the message.

There is also another type of message called a "GET" message.  This is the message inserted into the queue by the triggeragent.sh script.  When you use triggeragent, the script will insert a message into the agent queue with message type "GET" and the transaction ID, etc.  Agents will sit dormant until they see one of these GET messages in the queue for that transaction ID.  Once the agent sees this, it will start consuming messages as mentioned above based on the configurations of that agent criteria.

INPUTS, OUTPUTS AND TEMPLATES

The input for the agent comes from the JMS message.  The output given by an agent is defined within the agent itself.  If you want the agent to publish data to a queue, table or external system using a specific template, etc. you can do this by configuring one of the agent's user exits or events to do this publishing.

For more information about user exits, see the Customization Guides.  For more information about configuring events and other Process Modeling entities, see the Platform Configuration Guide.

TROUBLESHOOTING AGENTS

You can start/stop/monitor agents using the System Management Console.  Additionally, you can view performance data and graphs related to the agents from here.

You can modify the trace level in the System Management Console by setting trace level for the agent, or you can configure the log4j properties for that agent server to use a certain level of logging. (INFO, ERROR, TIMER, DEBUG, SQLDEBUG, VERBOSE, etc.)

For additional information, please see Appendix A of the Sterling MCF Application Platform Configuration Guide.