Summary

When designing agents, one of the most important decisions you must make is how often the agent should run.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).

Suggested Approach

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 want to automatically generate and send a letter to the applicant, congratulating them on getting their mortgage and wishing them success with their new home. This system 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.

Agent scheduling is specified in two fields on the Agents rule form and Agent Schedule instances:  Pattern and Interval.  There are two values available for the Pattern field, allowing you two choices for when agents run:

• Periodic
• Recurring

Important:  The values entered in the Agents rule for either Periodic or Recurring processing become a default for that agent.  It is possible to override these values for any agent in the appropriate Agent Schedule instance.  (For details, see How to modify an existing agent.)

NOTE:  Depending upon the agent type - task-driven or schedule-driven - different processing occurs when the agent runs: 

• task-driven agents check the queue for a task
• schedule-driven agents run the agent activity without checking the queue for a task

Because the goal of the following sections is to describe the scheduling function, rather than the difference in processing, the generic phrase “processing an agent task” will be used; it should be understood that this could refer to either type of agent, and would mean something different based on which type is chosen. 

Periodic

“Periodic” processing refers to agent processing which is run at the interval specified in the Interval column.  The Agent Manager wakes this agent every interval to do its processing.  For example, if the interval is set for 30 seconds,  then after the Agent Manager runs this agent, it sleeps for 30 seconds, and then “wakes up” and runs again.

Note that an interval period begins only after the agent completes the processing for the previous cycle.  For example, if the Interval is set to 30 seconds, but processing the agent task requires 60 seconds on average, then the agent wakes up and begins processing only every  minute and a half (approximately).

The Interval value should be the largest value possible (the longest time) consistent with the amount of time required for processing the agent task, and the number of tasks generated in a specified time period.  For example, if on average, three tasks for this agent are available in a day, then having an Interval value of 30 seconds would mean a lot of wasted system resources trying to process these three tasks – unless it were vital that these tasks be processed immediately.  However, if a task for this agent is generated every 10 seconds, and takes 10 seconds to process, having the agent run every 5 minutes means that it would get hopelessly behind very quickly, leaving unprocessed tasks. 

Recurring

The Recurring feature allows you to specify a recurring pattern of days, weeks, etc.  for this agent to run.  An interval period may cross a “day” definition – for example, an agent could run processing from 11:59 to 12:01, crossing from one date to another – or it might run at a different time each day, depending upon the interval and the length of time the processing takes.  If you want to know when an agent will run, you can specify a recurring time period - assuming that the agent processing to be done is appropriate for a recurring time period, rather than having to be done every 30 seconds.

When you choose Recurring in the drop-down, an Advanced button appears in the Interval column.   Clicking on the Advanced button displays a dialog box, which allows you to choose at what interval the agent task should be processed:

The Start field holds the desired time of the first execution of the agent; subsequent executions are the specified period later (24 hours or multiples of 24 hours).  

NOTE:  If the time entered has already passed, the agent will not run that day.

The time zone field holds the local time zone.  This is an optional field; if it is left blank, then the system will use the time zone local to this server. 

Important:  To specify the time zone in this field, enter the “long” time code designations (“America/New_York”) rather than the three-letter designations (“EST”).  The three-letter designations do not handle Daylight Savings Time, so you would have to update this field every time Daylight Savings Time starts or ends (“EST” – “EDT” – “EST”).

Tip:  The time zone field does not have a SmartPrompt to allow you to choose your time zone.  To see a list of possible time zone designations, choose Tools > Locale Settings and view the Use Time Zone drop-down list.   (Don’t change your time zone setting!  Just note the designation, and copy it into the Recurrence window.)

In the Recurrence dialog box, there are a number of Pattern types available:

• Daily
• Weekly
• Monthly
• Yearly

Important:  Just as with the Start field, whatever is designated in the Pattern Types will wake the agent at the first available time.  Thus, if Weekly is chosen, and the interval is Every 2 weeks on these days:  Monday, if the day the form is completed is Wednesday, this agent does not wake until the next appropriate Monday.

Daily

For the Daily pattern type, there are two interval choices:

• Every weekday (which does not include running on either Saturday or Sunday)
• Every [number] days  (i.e., every 10 days)

Weekly

The Weekly pattern allows you to determine the week interval (every 2 weeks, every 10 weeks) and then to specify the day that the agent should wake.  At least one of the days must be selected, and more than one day may be selected. 

NOTE:  If all the days are selected, then this choice can become equivalent to the Daily choice.

Monthly

The Monthly pattern type allows two specifications:

Day [number] of every [number] month(s)  - This choice allows a numeric designation of both the days and the month.

Example:

Day 1 of every 2 months

Day 15 of every 6 months

The [first] [day] of every [number] month(s) – There are numerous choices for these dropdowns:

• first
• second
• third
• fourth
• last

• day
• weekday
• weekend day
• Monday
• Tuesday
• Wednesday
• Thursday
• Friday
• Saturday
• Sunday

Examples:

• The first day of every 2 months
• The last Tuesday of every 6 months
• The third Sunday of every 1 month
• The first weekend day of every 12 months

Yearly

The Yearly pattern type allows a choice of:

• Every [month] [number] – where number is the day of the month.
• Example: 
• Every January 1
• Every June 30
• Every December 25

The [first] [day] of every [month] – These dropdowns are the same as the dropdowns for the Monthly pattern type, with the addition of the month dropdown.

Examples:

• The first day of every January
• The last Tuesday of every July
• The third Sunday of every October
• The first weekend day of every December