Summary

An agent is an internal background process operating on the server that runs activities on a periodic basis.  Agents route work according to the rules in your application; they also perform system tasks such as sending email notifications about assignments and outgoing correspondence, generating updated indexes for the full-text search feature, synchronizing caches across nodes in a multiple node system, and so on.   Agents are autonomous and asynchronous:  the activities they call run individually on their own schedules, and one activity does not have to finish before another one runs.

Before creating an agent, verify that all the appropriate agent design decisions have been made (see Before You Begin – Design Considerations below).  In addition, you must define the following rules before creating the agent rule:

• the activity which puts the agent task into the agent queue.  See How to enter items into the agent queue.

• the agent activity – an activity which accomplishes the business processing for an agent.  See How to write the agent activity .

NOTE: This article describes how to create a Standard-mode agent.

Suggested Approach

Before You Begin: Design Considerations

There are a number of decisions you must make before creating agent rules, including:

• what processing the agent will accomplish (see How to write an agent activity)
• what “event” in system processing will create the agent task  (see How to enter items into the agent queue)
• how long the agent interval should be
• how many queue entries an agent should process
• in what RuleSet the agent will be saved

Agent Interval

When designing agents, one of the most important decisions you must make is how often the agent should run.  You should consider what kind of agent is being created, in order to have it run at a useful interval – neither too often (which wastes system resources) nor too infrequently (which could slow down processing). 

For example, a bank might have an application to handle mortgage requests.  They get fewer than 10 of these requests each day.  At the end of the process, if the mortgage is approved (maybe 80% of the time), they wish to automatically generate and send a letter to the applicant, congratulating them on getting their mortgage and wishing them well with their new home.  This application might generate one or two letters per day, which the developer wishes to have the agent process.  Due to this low volume, having the agent check for letter requests every five seconds would result in excessive processing; running the agent every hour or even once a day might be sufficient. 

Another application might create invoices for an international retailer, with a daily volume of 10,000 invoices.  For each of these invoices, the user opens a work object to create the invoice; at a certain point in the processing, the invoice is put into the Pending-Research workbasket to look up that day’s exchange rate for the invoiced items.  An agent takes all these tasks out of the workbasket, accesses an external database to get the appropriate exchange rate, and then updates the assignment and returns it to the user.  Given an eight-hour day, the system would handle 1250 invoices an hour, or a bit over 20 each minute.  In this case, if an agent were used to look up the exchange rate, having the agent run every five seconds is not only necessary, but that might even be a bit slow.

For details on setting up agent intervals, see Agent Scheduling Intervals.

Setting the Max Records Value

As stated in the Agent Interval section above, you must judge how many queue entries your application will produce, to determine how often the agent should run.  Linked with this decision is the determination of the number of entries the agent should process from the agent queue before going to sleep for that interval. 

If the application produces thousands of queue entries that the agent must process, the developer must balance completing all these entries in a timely manner with having the agent run too long.  For example, on a multi-node system, if the agent “drains” the queue when it runs, then the agent on one node will do all the work, possibly affecting performance for that node.  It is much more efficient to set up the agent rule so that the agent on each node works on a batch of entries and then goes to sleep, leaving some entries in the queue for the next node to process.  If the agent is set to run every 5 minutes, and to process 50 entries, then the processing will be spread around the nodes, and no one node would have to churn through all the entries in the queue.

Saving Agents into RuleSets

As with all rules, there will be a RuleSet to which an agent and its associated activities will logically belong.  This might be in your base company RuleSet, if the functionality applies across all the company’s applications.  If the agent has specific functionality which is used in only one application, it might go into that application RuleSet.  You must determine into which RuleSet to save your agent.

Only one Agents rule can be defined on each RuleSet; therefore, after determining which RuleSet your new agent should be saved to, see if there is an Agents rule already defined for that RuleSet.  If there is, add your new agent to that existing rule.  If there is no Agents rule defined, create a new Agents rule for that RuleSet with your new agent information.

Important:  Since Agents have system-wide functionality, they must run on system-wide RuleSets, with system-wide access groups.  It is not possible to run Agents rules or Agent Schedules from a personal RuleSet, or with an Access Group saved to a personal RuleSet.

Create the Rule

Create or open the rule form

Determine whether there is an existing Agents in the RuleSet where this new agent will be saved.  If there is not, create a new Agents rule:

1. From Rules by Type, expand the SysAdmin link.  Right-click on Agents, and click New.

2.  On the New form, in the RuleSet - Name field, enter the RuleSet where this Agents rule will be defined.  (This must be a valid RuleSet in the system.)  Enter the version for this RuleSet, and  click Create.

Add an agent to the rule

For each new agent, enter into the Agents form the agent name, class, activity, and schedule, based on the prior decisions you made and the rules you created.

1.  Agent Name – Enter the name of this new agent.

2.  Pattern - Choose the appropriate Pattern from the drop-down list.  (See Agent Scheduling Intervals.)

3.  Interval - If the Pattern chosen was Periodic, enter a time interval, in seconds, into this field, specifying how often this agent should run. 

            If the Pattern chosen was Recurring, specify the recurrence timeframe for this agent (daily, weekly, monthly).

4.  Choose the Queue Mode from the dropdown box.  For most agents, this should be Standard.  (See How Agent Queues Work -- Queue Mode.)

5.  Check the Enabled? field to enable the agent.

6.  Click the orange arrow to the left of the agent to display the additional agent fields.

7.  Class - Enter the name of the class on which the agent is defined.  This class should be the same as the class of the work object which this agent will be processing.

8.  Activity Name - Enter the name of the agent activity that was created for this agent.  This activity should be defined on the class specified above.

9.  Params - If there are parameters for this activity, click the Params button, and enter values for the parameters which are displayed.

10.  Enter the maximum number of records to be processed by this agent into the Max Records field.

11.  Verify that the Auto Queue Manager box is checked, to enable the Auto Queue Manager functionality.  For almost every agent, AQM should be enabled.  (See Agent Queues -- Auto Queue Manager.)

Configure agent-wide settings

1.  Verify that the Enable this agent box is checked.  This enables all the agents in the list, and allows the system to create the Agent Schedule instance(s).

2.  For the agents in the form which have a Pattern of Periodic, you may also specify a default Interval for all the agents in the Agent-Wide Settings field.

3.  If necessary, enter the name of the access group that was created in the Access Group field on the Security tab.

4.  Save the rule form.

5. After a period — typically 10 minutes or less — the system automatically creates Agent Schedule data instances, one for each node — corresponding to the new agent rule. If the Enable this agent box in the agent rule is checked, it is also enabled in the Agent Schedule instances, and processing begins. (You can cause the system to create the Agent Schedule instances directly by stopping and restarting the system.)