Agents Tech Note 0504

(1)

Agents – Advanced Topics

(2)



Copyright 2008

Pegasystems Inc., Cambridge, MA

This document describes products and services of Pegasystems Inc. It may

contain trade secrets and proprietary information. The document and product are

protected by copyright and distributed under licenses restricting their use,

copying distribution, or transmittal in any form without prior written

authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the

document may be made from time to time at the discretion of Pegasystems. This

document remains the property of Pegasystems and must be returned to it upon

request. This document does not imply any commitment to offer or deliver the

products or services described.

This document may include references to Pegasystems product features that have

not been licensed by your company. If you have questions about whether a

particular capability is included in your installation, please consult your

Pegasystems service consultant.

For Pegasystems trademarks and registered trademarks, all rights reserved. Other

brand or product names are trademarks of their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any

publication may contain inaccuracies or typographical errors. This document

could contain technical inaccuracies or typographical errors. Changes are

periodically added to the information herein. Pegasystems Inc. may make

improvements and/or changes in the information described herein at any time.

This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 Phone: (617) 374-9600 Fax: (617) 374-9620 www.pega.com

PegaRULES Process Commander Software Version 5.4

(3)

Overview

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 e-mail 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 could be thought of as two types: • task-driven

• schedule-driven

Task-driven agents are agents where the processing that the agent is to accomplish is

based on the work object processing in the system. Part of this work object processing creates a task that the agent must accomplish; these tasks are put into a queue

somewhere in the system, and then the agent retrieves the task and processes it. For example, a user opens a work object to record a customer call; that work object creates a task for an agent to look up some data in an external system for that customer; and the agent later retrieves that task out of the queue and researches the information. Most agents are task-driven.

Schedule-driven agents do not require a queue of tasks for their processing. Instead, they

run at a specified interval and do system-wide processing. An example of a schedule-driven task would be an agent which runs every morning to create a report on the previous day’s calls. This report would not be run based on one particular work object, but would report on whatever work objects were created on the previous day.

In order for task-driven agents to do their processing in a PRPC system, they need certain functionality. First, they would need somewhere to store all the tasks that they need to process – a task queue. There will have to be some functionality to put those tasks into the queue during the standard work item processing – to enqueue the tasks.

Next, the system needs a way to retrieve these entries from the queue for the agent to process. This functionality must handle agents on multiple nodes processing the tasks; there must be some way to lock the queue entries so that two nodes running the same agent don’t try to process the same task and collide. There should also be some way to indicate how many entries the agent should process each time it wakes up.

The system must handle a failure of processing – if there is an error at some point, is the entry re-queued, or lost, or is an error reported?

Once a task has been successfully retrieved, the agent must process it. It is assumed that this task has something to do with a work item, so the agent must switch its context from the agent’s RuleSet List to the RuleSet List required to properly process this work item. In addition, if the task requires updates to the work item, the agent will need to lock the work item before changing it.

And finally, once the task has been finished, the agent must complete the processing. If the processing was done successfully, the changes must be committed to the database, and the work item must also be updated. If the processing failed for some reason, any intermediate changes must be rolled back, and the error handled. The lock taken out on the work item must be released.

(6)

Version 5.4 Functionality

IMPORTANT: This tech note is intended to be a companion piece to the articles on the Agents page of the PDN (KB 25156). That page includes descriptions of the new Agents rule form, the new fields on that form, the Queue Modes, and creating a standard agent. As the rest of this document assumes that readers are familiar with that information, it is strongly recommended to read those articles first.

Vers ion 5.4 Functionality

Prior to Version 5.4, when a developer created a task-driven agent, they would also have to create the queue to store the tasks, and then direct the agent activity to retrieve these tasks from the queue. This resulted in a lot of duplicate code and complex processing. In addition, when writing the agent activity, the developer had to include not only the business logic, but also any transactional steps that might be needed, such as opening and locking the work object that needed to be updated, and handling commits or rollbacks of the changes to the database.

Beginning in Version 5.4, agent functionality has been enhanced to make it much easier to write agents. Standard queue functionality and transactional functionality have been provided in the system; these features are now separated from the agent activity, so that the agent activity only handles the business logic of the agent task.

In Version 5.4, the following structures were added to the product, so the developer doesn’t have to create everything “from scratch”:

• EstablishContext activity

• the System Queue (agent queues)

• Queue-For-Agent method and QueueForAgent activity

EstablishContext Activity

This activity is defined on the System-Queue-DefaultEntry class. When processing for an agent begins, the system opens the System-Queue-DefaultEntry queue item for that agent, creates a page of that class, and loads all the queue entry data onto it. This page, with all the queue entry information, is then passed into the default version of the

EstablishContext activity, which opens the work object, and tries to obtain a lock on this

object.

The System Queue

In Version 5.4, a standard System Queue was introduced. This is a database table (pr_sys_queues), which is associated with classes descended from System-Queue-. Entries for all agent tasks are stored in this queue, and identified by the agent RuleSet (which is also the name of the Agents rule) and the agent name.

(7)

A standard class has been created for the basic Standard agents: System-Queue-DefaultEntry. This class will be used automatically for all task-driven agents which do not require any custom structures.

For more complex agent setups, it may be necessary to create additional classes inheriting from System-Queue-. In these cases, the new classes may also point to the pr_sys_queues database table, or if desired, additional tables may be created for agent tasks by creating a copy of the pr_sys_queues table with a new name, and using a Data-Admin-DB-Table entry to link the new table with the new class. (This should rarely be necessary.)

As part of the queue functionality, there are now three Queue Modes: • Legacy

• Standard • Advanced

This document will describe setups using Standard and Advanced modes.

IMPORTANT: For the standard case of a Standard agent, the PDN articles (mentioned

above) refer to separate Agent Queues for each agent. In order to understand the agent queue functionality in the standard case, where much of the functionality is transparent to the user, it is easier to think of each agent as having its own queue. However, behind the scenes, all of the agent queues are actually stored in the pr_sys_queues table, and will be described as “the System Queue” in this tech note, as the more advanced scenarios may require changing the basic setup.

Reporting Entries in the Sys tem Queue

Since this class is now standard in the system, any ListView or SummaryView rule could be used to report on the current entries for one or multiple agents. Developers can create their own report to display entries per class, or by agent name or RuleSet.

Role Acces s to Sys tem-Queue- Clas s

The class Rule-Access-Role-Obj gives certain roles specific access to classes. If a role is not given access to a class, they cannot create or modify instances of that class.

As part of agent processing, customers will run the Queue-For-Agent method, which creates entries in the System-Queue- (or other) class. Therefore, the roles of those users creating the entries must allow them access to the appropriate class.

The system comes with read/write access to the System-Queue- class for the following roles: • ProArch4 • SysAdm4 • SysArch4 • User1 • User4 • WorkManager

(8)

If developers create other roles which need to enter items into the System Queue, they must specifically give access to the appropriate class.

NOTE: If developers give roles access to the System-Queue- class, then all classes that inherit from that class (both pattern inheritance and directed) will inherit the role access as well.

Likewise, if developers create an agent which enters data into a class other than Work- (such as Data- or History-), they must be certain that the roles which create the entries also have access to write to those classes, since the agent uses the user context to process the agent task. (In other words, even though the user isn’t directly writing to Data- or History-, because the agent is using the user’s access group, and the agent has to write to those classes, the user must have access to create instances of those classes.

(9)

Queue-For-Agent method

This method is called to create a queue entry into the System Queue.

There are four parameters:

Parameter Description Example

AgentRuleSet The RuleSet in which the agent is stored. This should also be the name of the Agents rule in which this agent is contained.

AcmeCo

AgentName This parameter contains the name of the agent (as defined on the Agents rule).

CallCtrLookup

MaxAttempts This parameter holds the number of times the system should try to process this entry; the default is 1. If the maximum number of attempts is made, and the entry is still

unsuccessfully processed, the system will treat the item as a failure.

3

MinimumAgeFor Processing

This parameter specifies the minimum length of time (in milliseconds) that an entry must remain in queue before it may be processed; the default is 0 (the item may be processed as soon as it is entered into the agent queue).

(10)

The Step Page called with this method is very important, as it must be the page of the work object where the task information is stored - so the agent can find that information later, when it runs. For example, if a user is going to queue a task to do a data lookup for a customer and then update the work object, the Step Page should be the pyWorkPage. If the agent task is to update an assignment, the Step Page might be New AssignPage. If called from a flow, the primary page will probably be used as the step page.

The queue entry being created by this method needs a page that inherits from the System-Queue- class to store all the task information. If the class of the step page does

not inherit from System-Queue- (as most work objects wouldn’t), the Queue-For-Agent

method then creates a page of the System-Queue-DefaultEntry class, and stores that as a new entry into the System Queue for this agent. This entry includes all of the above parameters; in addition, it stores:

• the key to the work object [as pxInsHandles(1)]

• the page name of the work object [as pyPageNames(1)]

This information will be used to open the work object later, when the agent needs it for processing.

A customer might not call the Queue-For-Agent method directly (with a step page), but instead call the activity QueueForAgent (defined on @baseclass) which calls this method. Note that in this activity, the method is called with a blank step page. This is because it is assumed that when this activity is called from within the work object processing, it would be called with a step page of the work object, which then becomes the primary page for the activity.

Auto Queue Manager

The Auto Queue Manager handles the queue entries themselves. If AQM is enabled on the Agents form (which is the default), then when a queue entry is retrieved for processing by the agent activity, AQM will lock that entry until a commit or rollback occurs at the end of processing, so only one agent/node is trying to process that entry (has exclusive rights to that entry). If some kind of issue occurs (like the agent can’t get a lock on the work object), AQM can re-queue the task and try again (depending on the settings described below).

If AQM is disabled, then the system will immediately remove entries from the System Queue, instead of locking them and leaving them in the database table. When AQM is disabled, the system will perform the commits or rollbacks on the work being processed, but the queue entry will not persist in the database. If a rollback occurs, that entry is now gone and cannot be requeued.

AQM uses the following properties (defined on the System-Queue- class) to control the status and processing of the queue entries. The properties MaxAttempts and

MinimumAgeForProcessing are exposed as parameters of the Queue-For-Agent method.

For agent queue entries, the .pyItemStatus property is automatically set to “Scheduled;” the other properties may only be changed in a custom “enqueueuing” activity (described later in this document).

(11)

Version 5.4 Functionality .pyItemStatus

This property defines the status of the queue entry. The following is a list of valid status values:

Status Description

Scheduled Signifies that this is an agent task which should be handled by agent processing.

Immediate Signifies that this is a services task, which will be handled by services processing (services also use the System Queue; a description of that use is beyond this article).

Now-Processing Indicates that this item is currently locked and is being processed by a node. This status will only be displayed for

queue entries whose agents have AQM enabled.

Success Indicates that this entry was successfully processed; the item was retained in the queue (see RetainOnSuccess below). This

status will only be displayed for queue entries whose agents have AQM enabled.

Broken-Process Signifies that processing failed on this entry; it has been retained in the queue. This status will only be displayed for queue

entries whose agents have AQM enabled.

The entry’s status must begin as either Scheduled or Immediate; AQM will then update the status as the entry is processed.

.pyMaxAttempts (MaxAttempts parameter)

This property holds the number of times the system should try to process this entry; the default is 1. If the maximum number of attempts is made, and the entry is still

unsuccessfully processed, the system will treat the item as a failure and follow the procedure for RetainOnFailure.

If, for example, a customer has an agent which (among other processing) updates the status of a work object, then the agent must obtain a lock on that work object before changing its status. The first or second time that the agent attempts to get a lock on that work object, it may fail, if an operator has that work object open at the same time. This property allows the developer to handle that situation without an immediate failure; the agent can try the specified number of times to obtain the lock on the work object before failing.

.pyMinimumAgeForProcessing (MinimumAgeForProcessing parameter)

This property specifies the minimum length of time (in milliseconds) that an entry must remain in queue before it may be processed; the default is 0 (the item may be processed as soon as it is entered into the System Queue).

As an example, a customer may have an entry with a Max Attempts value of “3.” If the work object is locked (example above), trying to process it again immediately will probably

(12)

not give the user any time to close it, so the next attempt should be delayed a little; this property puts some time in between tries. Or, an Agents entry may be created by work object processing. If the agent happens to “wake up” and process this entry immediately after it was entered, the work object would still be in use (and locked) by the user, causing agent processing to fail. Therefore, putting a small delay in before trying to run the agent process could give the user enough time to close the work item and go on to something else.

.pyRequeueOnSuccess

This property indicates whether the entry should be re-queued for recurring processing; the default is false. If this property is set to true, then after the entry was successfully processed, a new entry would be created (with a new Item ID, but the same property values) and re-queued for processing.

.pyRetainOnSuccess

This property defines whether an entry will be kept in the System Queue database table after it has been successfully processed; the default is false. If this property is set to false, the entry will be deleted after the agent processing is complete and the transactions have been committed to the database. If this property is set to true, the entry will remain in the System Queue table, and the item status will be changed to “Success.”

This property should always be set to false for agent processing, to avoid large numbers of retained records in the database. (Services processing, which also uses the System Queue, occasionally needs to keep the entries.)

.pyRetainOnFailure

This property defines whether an entry will be kept in the System Queue database table after the processing has failed; the default is true. If this property is set to false, then the entry will be deleted when the agent processing has gone as far as it can and the

transactions have been rolled back. If this property is set to true, then the entry will remain in the System Queue table, and the item status will be changed to “Broken-Process.”

.pyDuplicateProperty

This property is used to determine whether an entry into the System Queue is a duplicate of an existing entry. The developer should determine whether this functionality is required for their application.

For example, a bank might batch up changes from customer calls, and enter them into their legacy system-of-record at the end of each day. A customer might call in one day with an address change; and then another update to that work item might include a telephone number change; and yet another update may enter an employer name change. For each of these updates, the process creates another queue entry to record the change from the same work object. Since at the end of the day, all the most-current information in the work object will be copied to the system-of-record, there is no need to copy that same information three times (once for each update); copying it once will do. Therefore, only one queue entry per work object is needed, to signal that that work object has been changed. (In other words, the changes themselves aren’t saved to the queue entry; just the fact that that work item has been changed.)

(13)

In another situation, a user is processing a call through its flow. At one point in the flow, a queue entry is created to do a data lookup for the customer and update specific fields in the work object with that information. At another point in the flow, the SLA information has to be updated (again, by an agent), and at a third point, an email has to be sent internally to the Legal department to notify them that a new assignment is in their workbasket. In this case, the developer should not set.pyDuplicateProperty to prevent multiple entries for one work object, because each of these entries is doing something different.

Once the developer has determined that they do wish to prevent multiple queue entries for one work object, they should set .pyDuplicateProperty to a property reference from the queue information. When processing entries from the queue, AQM will check this value against all other entries in that class. If a duplicate is found, the current entry would be discarded. No error is displayed.

Example:

.pyDuplicateProperty set to .pyInsHandles(1)

This Property-Set would check the instance handle of each associated work item in each of the unprocessed queue entries. If there is already a queue entry for this particular work item, then the current task would not be entered into the queue.

NOTE: The developer would have to determine what property from the queue data would best indicate a duplicate entry, depending upon what processing the agent is doing. The .pyInsHandles property may not be best for all situations, as a work object flow might have several different agent tasks to enter for each work object (doing an external lookup of data for a customer at one point, sending an SLA email to an internal manager if a goal is missed, sending a notifying email to the Legal department that the task has been moved into their workbasket, etc.). If the developer wishes to prevent multiple SLA emails from being sent to a manager (one per hour, for example), then perhaps the email address of the manager might be the property value to check.

Queueing Examples

To illustrate queueing functionality, consider the following queue. The entries in this queue are all for the same agent; these are the tasks that agent should perform:

A B C D

This agent has the MaxAttempts property set to 3, so three tries will be made on any entry (if necessary).

Example 1

The agent starts processing entry A. As part of processing, the ItemStatus changes from

Scheduled to Now-Processing.

For whatever reason, processing this entry fails (it couldn’t get a lock on the work object or something). Since MaxAttempts is set to 3, the system requeues this entry. The

(14)

• its status is reset from Now-Processing to Scheduled • pyAttempts is incremented

• the last-processed time for this record is updated Now the queue is ordered thus:

B C D

A (requeued)

The agent processes B, C, and D successfully, and then retries A. If A fails again, it is requeued as before. However, since there are no other entries in the queue, it is retried again immediately. If the third attempt fails, A’s status is set to Broken-Process. With no more entries in the system, the agent then goes to sleep for its specified interval.

Example 2

In this example, in addition to MaxAttempts set to 3, the property

MinimumAgeForProcessing is set to 5 seconds. This provides a delay in re-processing

after requeueing.

Again, the agent tries to process A, and fails. A is requeued. The agent processes B, C, and D successfully, and then looks at A again. If five seconds or more has passed since A was requeued – if it took 5 or more seconds to process B, C, and D – then the agent tries to process A again.

However, if five seconds has not passed (B, C, and D were quick), then A will not be “ready” to process; the agent will find no entries ready to process in the queue, and will go to sleep for its specified interval; A will be tried for the third time after the agent wakes up (the next interval).

This might also occur if A was ready to process the second time, but failed again. In Example 1, the agent tries to process A for the third time immediately after the second try, as there are no other entries in the queue. When MinimumAgeForProcessing is set to 5 seconds, however, after A is tried and fails the second time, it is requeued with the 5-second delay; again, as there are no other entries in this queue, and A isn’t ready, the agent would go to sleep, and A would be tried again after the agent wakes up.

Example 3

The agent tries to process entry A, and fails. A is requeued. In this example, B, C, and D also all fail. All are requeued.

If MinimumAgeForProcessing is set for this agent, then (depending upon the time that has passed), the agent would either retry A, or (if A isn’t ready yet) goes to sleep. The agent keeps trying again on B, C, and D, until they are either successfully processed, or – after 3 tries – are set to the Broken-Process status.

(15)

Standard Mode

Standard Mode

The Standard mode covers many agent conditions, including a number of custom setups. (In other words, developers shouldn’t jump right to the Advanced mode just because they want to do some agent customizations.) Different aspects of the agent structure may be customized, including:

• the EstablishContext activity • the “enqueuing” activity

• defining a custom System-Queue- class

Depending upon the kind of agent the developer is creating, any or all of these might be customized. The below chart summarizes the custom structures required for different types of agents:

Agent type Custom

EstablishContext Activity New “enqueueing” Activity New System-Queue- Class

Creating a basic agent no no no

Setting additional properties

no Yes no

Using two or more work objects

no Yes no

Recurring queue entry no Yes Yes

(recommended) Completely custom

agent

Yes Yes Yes

The next sections describe examples of setting up each of these types of agents.

Creating a Basic Agent

The agent feature has been enhanced to make the creation of a standard agent much easier, while still providing functionality to handle more complex cases.

Creating a basic agent is described in the PDN articles on the Agents page. Since it is expected that most agents will use this setup, much of the agent functionality is designed to be transparent to the user; they have no need to know in detail how a queue entry is stored into the database table, or what class it is defined on; they do not need to change or call the EstablishContext activity. Thus, none of that is mentioned in the description in these articles.

NOTE: The basic agent described on the PDN is a task-driven agent, which uses an agent queue. To create a schedule-driven agent, which does not use a queue, it is necessary to use Advanced mode (described later in this document.)

(16)

Standard Mode

When a developer creates one of the basic agents, they must start by determining the agent processing required by the work object. They inject the Queue-For-Agent method into their work object processing, either by putting the method itself into an existing activity, or by calling the QueueForAgent activity. If the step page is not specified for the Queue-For-Agent method, it will default to the primary page for the calling (work object) activity, which is assumed to be the page on which the agent will later do processing.

The system will see that this page is not descended from the System-Queue- class, and will automatically create a page of class System-Queue-DefaultEntry and populate it with the necessary information to create a queue entry. It will then save that information as an entry into the System Queue for that agent.

When the agent wakes up, it checks the System Queue to see if there is an entry matching that agent’s RuleSet and Name. If at least one entry exists, the system will automatically call the EstablishContext activity. This activity will open a page of class System-Queue-DefaultEntry and populate it with the data from the queue entry.

EstablishContext will then try to open the work object (specified by the queue entry), and

get a lock on that object. If it succeeds, it calls the agent activity to process that entry. If it fails, it does not call the agent activity. If this agent is set to try more than one attempt at processing, it will try again to obtain the lock, up to the MaxAttempts number of tries; after that, the AQM will set the queue entry Item Status to Broken-Process, and the developer would have to reset the entry (for later processing) using the System Management Application. (See the Viewing Agent Queues in the SMA section later in this document.)

Setting Additional Properties in a Standard Agent

The above section describes the basic agent functionality, and how the background agent structures are used. Depending upon what the developer is trying to do, any or all of these structures may be customized.

For example, a developer may wish to set more of the Auto Queue Manager properties, such as RequeueOnSuccess. These properties are part of the System-Queue- class, but are not exposed as properties of the Queue-for-Agent method. In this case, the developer should create a custom “enqueueing” activity, defined on the class where the work object is (as it must be available to the system when the queue entry is created).

This activity must contain several steps:

1. Create a page of the System-Queue-DefaultEntry class.

2. Do a Property-Set of the properties defined on this class which are desired for this agent (such as .pyRetainOnSuccess).

3. Do a Property-Set of the following properties (to identify the page of the object being processed by the agent - the work object or assignment or whatever):

• .pyPageNames(1) • .pyInsHandles(1)

4. Call the Queue-For-Agent method, using the page from Step 1, to create the queue entry.

(17)

Standard Mode

NOTE: In this case, since the class of the page is descended from System-Queue-, the

Queue-For-Agent method knows it doesn’t have to create a new page; it uses the one

defined by this activity.

This activity should then be used as the “enqueueing” activity. As this setup is still using the default class (System-Queue-DefaultEntry), none of the other structures needs to be changed.

Creating an Agent with Two or More Work Objects

The basic agent setup assumes that the customer has one work object which will be processed by an agent at one time. (For example, a bank might have an agent run to open each work object, extract the customer’s social security number, look up their credit rating in an external system, and then update the work object with that information.) Some agent processing, however, might need to be done on two or more work objects simultaneously. An agent might have to update a work object and its folder, or a work item and an assignment, etc. In this case, the developer must again create a custom “enqueueing” activity. This activity may be defined on the default System-Queue-DefaultEntry class, or the developer can create a new System-Queue- class (although in this case, that is not required).

1. Create a page of the System-Queue-DefaultEntry class (or the new class, if one was created).

3. Do a Property-Set of the .pyPageNames and .pyInsHandles properties. Since these are StringList properties, the developer needs to specify as many sets of these properties as there are work objects that the agent needs to update:

.pyPageNames(1) = “pyWorkPage” .pyInsHandles(1) = pyWorkPage.pzInsKey .pyPageNames(2) = “pyAssignPage” .pyInsHandles(2) = NewAssignPage.pzInsKey .pyPageNames(3) = “pxFolderPage” .pyInsHandles(3) = FolderPage.pzInsKey etc.

(18)

Standard Mode

This activity should then be used as the “enqueueing” activity. If this setup is still using the default class (System-Queue-DefaultEntry), none of the other structures needs to be changed.

Specifying a Recurring Queue Entry

It is possible to have scheduled tasks entered into a queue dynamically by an external application, to be handled by an agent. For example, a customer might set up an auto unit

testing function in Process Commander. This function could queue up entries to run any

of a number of different unit tests to be executed at differing intervals. Rather than creating many different agents, each with a different wakeup interval, it is possible to create just one agent to wake and check the queue regularly, and to put the differing intervals on the queue entries themselves.

Like the example of a “complex” agent, for this type of application, it is advisable to create a separate System-Queue- class (“System-Queue-RecurEntry”). The developer must create a new “enqueueing” activity, along with the agent activity, and define them both on this new class. Depending upon what kind of work objects are being used for this testing function, the EstablishContext activity might (or might not) need to be rewritten; even if the activity itself will work without customization, it must at least be saved into the new class. The “enqueueing” activity must contain several steps:

1. Create a page of the new System-Queue- class.

3. Do a Property-Set of the following properties (to identify the page of the object being processed by the agent - the work object or assignment or whatever):

• .pyPageNames(1) • .pxInsHandles(1)

Note: This is an example. It is not required to set these specific properties; other properties may be used in other situations.

The additional processing comes in Step 2. There are a number of properties which may be set to define the recurring queue entries, depending upon what intervals are desired. The first property that must be set to true is .pyRequeueOnSuccess. This boolean property determines whether queue entries should be set up for recurring processing. The default is false, meaning that once this entry is processed, it will not be re-entered.

After a queue entry is processed successfully, the system will check the value of .pyRequeueOnSuccess. If this property is set to true, the system then checks the next property: .pyRecurrenceDetails. This page property (defined on the class Data-Event-Recurring), holds the properties which define a recurrence pattern that would be used to initially delay processing of this entry. These values also automatically requeue the entry to be processed at the next valid date/time (as specified by the interval chosen).

(19)

Standard Mode

If .pyRequeueOnSuccess is set to true, the System Queue checks for the

.pyRecurrenceDetails embedded page. If it is not present, then a new, duplicate queue entry will be created in the System Queue and set for immediate processing.

If the .pyRecurrenceDetails page is present, the system uses the values on that page to compute a new value for the .pyMinimumAgeForProcessing property (in the queue entry), which determines the delay before the new queue entry is processed. The most important property, .pyType, holds the type of recurrence desired. Values for this property include:

• DAILY-EVERYNDAYS • DAILY-EVERYWEEKDAY • WEEKLY-EVERYNWEEKS

• MONTHLY-EVERYNDAYOFEVERYMMONTHS (“M” months is correct here) • MONTHLY-SPECIFICDAYOFEVERYNMONTHS

• YEARLY-EVERYDAYOFMONTH • YEARLY-SPECIFICDAYOFMONTH

Each of these values is supported by a number of properties which define the pattern. These properties are all stored in .pyPattern, which is a page property of class

Embed-Data-Event-Pattern, and must be set as well in the enqueueing activity.

The property .pyStartDateTime holds the time that the queue entry is available for processing, as well as the first date that this entry may be processed. NOTE: This is not necessarily the time that the entry is processed, because the agent must wake up on its own schedule, and then process this entry after that.

DAILY-EVERYNDAYS

This type should be used for an entry which should be processed every n days.

.pyPattern properties Description

.pyDailyInterval The number of days to delay between executions

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) every other day at 11:30 PM. Using this type, this queue entry would be processed on:

• Sunday • Tuesday • Thursday • Saturday • Monday • Wednesday • Friday • Sunday • etc.

(20)

Standard Mode

Property-Sets required:

PropertiesName PropertiesValue

.pyRequeueOnSuccess true

.pyRecurrenceDetails.pyStartDateTime date/time value in GMT. Example:

20071030T233000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “DAILY-EVERYNDAYS” .pyRecurrenceDetails.pyPattern.pyDailyInterval 2

DAILY-EVERYWEEKDAY

This type should be used for an entry which should be processed every n days, but exclude the weekends.

.pyDailyInterval The number of days to delay between executions

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) every other day during the workweek, at 11:30 p.m. Using this type, this queue entry would be processed on: • Monday • Wednesday • Friday • Monday etc. Property-Sets required: PropertiesName PropertiesValue .pyRequeueOnSuccess true

20071030T233000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “DAILY-EVERYWEEKDAY” .pyRecurrenceDetails.pyPattern.pyDailyInterval 2

(21)

Standard Mode WEEKLY-EVERYNWEEKS

This type should be used for an entry which should be processed on one day only every n weeks.

.pyWeeklyInterval The number of weeks to delay between executions

.pyDaySelection The selection of the day on which to execute. This property holds a comma-delimited list of booleans, one for each day of the week (starting on Sunday). For example, to execute only on Tuesday, the value for this property should be

“false,false,true,false,false,false,false”

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) every Monday morning at 8:00 a.m.

20071030T080000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “WEEKLY-EVERYNWEEKS” .pyRecurrenceDetails.pyPattern.pyWeeklyInterval 1

.pyRecurrenceDetails.pyPattern.pyDaySelection “false,true,false,false,false,false,fal se”

NOTE: The customer can have the queue entries ready to process on more than one day every week by changing the Day Selection:

For Monday and Thursday: “false,true,false,false,true,false,false”

MONTHLY-EVERYNDAYOFEVERYMMONTHS

This type should be used for an entry which should be processed on one day every n months.

.pyDayOfMonth The integer representing the day of the month (1-31). .pyDayOfMonthInterval The number of months to delay between executions.

(22)

Standard Mode

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) on the first day of each quarter (every 3 months).

20071030T233000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “MONTHLY-EVERYNDAYOFEVERYMMONT HS” .pyRecurrenceDetails.pyPattern.pyDayOfMonth 1 .pyRecurrenceDetails.pyPattern. pyDayOfMonthInterval 3

NOTE: The customer may only enter these queue items for one day of the month. If they wished to run this test on the 1st and the 15th of the month, for example, they would have to create two queue entries (with two enqueueing activities), and have .pyDayOfMonth set to 1 for the first, and 15 for the second.

MONTHLY-SPECIFICDAYOFEVERYNMONTHS

This type should be used for an entry which should be processed on one specific day every n months.

.pyMonthlyWeekSelection The integer representing the week of the month (1-4). .pyMonthlyDaySelection The integer representing the day of the week (1-7). .pyMonthlyInterval The number of months to delay between executions.

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) on the second Tuesday of each month.

(23)

Standard Mode

20071030T233000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “MONTHLY-SPECIFICDAYOFEVERYNMONT HS” .pyRecurrenceDetails.pyPattern. pyMonthlyWeekSelection 2 .pyRecurrenceDetails.pyPattern. pyMonthlyDaySelection 3 .pyRecurrenceDetails.pyPattern. pyMonthlyInterval 1

NOTE: As in the previous example, the customer may only enter these queue items for

one day of the month.

YEARLY-EVERYDAYOFMONTH

This type should be used for an entry which should be processed on the specified day of the specified month every n years.

.pyYearlyMonth The integer representing the month of the year (1-12). .pyYearlyDay The integer representing the day of the month (1-31).

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) on the last day of each year.

(24)

Standard Mode

.pyRecurrenceDetails.pyPattern.pyType

“YEARLY-EVERYDAYOFMONTH” .pyRecurrenceDetails.pyPattern.pyYearlyMonth 12

.pyRecurrenceDetails.pyPattern. pyYearlyDay 31

one day of the year.

YEARLY-SPECIFICDAYOFMONTH

This type should be used for an entry which should be processed on the specified day of the week in the specified month every n years.

.pyYearlyMonthSelection The integer representing the month of the year (1-12). .pyYearlyWeekSelection The integer representing the week of the month (1-4). .pyYearlyDaySelection The integer representing the day of the week (1-7).

Example:

The customer wishes to have the agent process a queue entry (to run a unit test) on the second Tuesday after the New Year.

20071030T233000.000 GMT .pyRecurrenceDetails.pyPattern.pyType “YEARLY-SPECIFICDAYOFMONTH” .pyRecurrenceDetails.pyPattern. pyYearlyMonthSelection 1 .pyRecurrenceDetails.pyPattern. pyYearlyWeekSelection 2 .pyRecurrenceDetails.pyPattern. pyYearlyDaySelection 3

(25)

Standard Mode

one day of the year.

Creating a Fully Custom Standard Agent

Some agents may not handle work objects at all. For example, suppose that the customer wished to create an agent which would process a message coming in from an external system via a SOAP service request (or other service), and stored in a data object. In this case, all the agent structures must be customized.

1. Define a class for the agent.

The class created for the agent must inherit from System-Queue-, either through pattern inheritance (“System-Queue-AcmeAgent”) or directed inheritance (“Acme-Agent”, which inherits from System-Queue-). Note that this class must have a key of .pyItemID. After creating this class, then enough properties must be defined on the class in order to track all the appropriate information for all objects to be processed by the agent. For example, the external system information must be stored for each object, plus whatever other data would be required from each message for the agent processing.

2. Create an “enqueuing” activity.

Because data must be stored from a data object (not a work object), the standard

QueueForAgent activity cannot be used. The developer must define an activity to create

queue entries for this agent, and name it appropriately (“AutoSystemQueueEntry”). It does not have to be defined on the class created in Step 1, but may be defined on other classes (perhaps the data object class). It must be present when the system needs to create the queue entry.

A. Create a page of the new System-Queue- class (“System-Queue-AcmeAgent”) B. Do a Property-Set of all the properties defined on this class which are required for this agent (from the SOAP request), to gather all the data currently on the clipboard for these objects

C. Do a Property-Set of the following properties (to identify the page of the object being processed by the agent - the data object or whatever):

• .pyPageNames(1) • .pxInsHandles(1)

D. Call the Queue-For-Agent method, using the page from Step A, to create the queue entry

(26)

Standard Mode

3. Create a new EstablishContext activity.

The existing EstablishContext activity is defined on System-Queue-DefaultEntry. Since that class is probably not available through inheritance to the new class System-Queue-AcmeAgent, it is necessary to resave that activity into the new class, and then edit it to handle the processing required by this agent.

The default EstablishContext does an Obj-Open on work objects, which require locking. Since in this example, a data object is being opened, then this activity must do an Obj-Open-By-Handle on that object. A lock may or may not be required, depending upon the class. (NOTE: A failure to obtain a lock should result in a Broken-Process entry.) In addition, if there is no locking required, then ReleaseOnCommit should not be used.

4. Define the agent activity.

The agent activity must also be defined on the new class (System-Queue-AcmeAgent). Other than that, it should only contain the business logic, as the EstablishContext activity should have provided it with the correct data to process on the clipboard.

(27)

Advanced Mode

Advanced Mode

For agent processing which is so complex that it cannot be handled in Standard mode, even with customizations, the Advanced mode is provided. In Advanced mode, the agent activity is again responsible for both transactional and business processing. However, unlike the Legacy mode, the agent activity in Advanced mode can still use the System Queue functionality; it just must do so explicitly (rather than the Standard mode, where the System Queue is engaged automatically). So when the agent “wakes up,” it runs the activity directly, and the activity calls the queue functionality.

Advanced mode allows the developer to determine if and how to use the System Queue.

Activities for Retrieving Queue Items

If an Advanced mode agent will be using the System Queue functionality, there are several activities which are provided to make the developer’s job easier when retrieving entries from the queue:

• GetFirstByClass • GetFirstByAgentName • GetByInstanceKey

It is not required that these be used, but this saves the developer from having to write more Java steps. If the developer does wish to use these, the Advanced agent must be defined on a class that inherits from System-Queue-, and must use the System Queue. Note that these activities only retrieve entries from the queue. The developer is still responsible for calling the database commits or rollbacks in the agent activity, as well as all the business logic.

GetFirs tByClas s

This activity will retrieve the “oldest” entry in the queue for the specified class. It contains the following parameters:

Parameter Description

PageName* The name of the page onto which all of the queue entry information will be loaded. This page should be defined on the same class (inheriting from System-Queue-) as the agent. ClassName* The name of the class (inheriting from System-Queue-) on which

the agent (and the page) are defined.

Lock Whether to lock the queue entry (see explanation below). Remove Whether to remove the queue entry (see below).

(28)

Advanced Mode

The Lock or Remove settings are providing some of the Auto Queue Manager functionality (available in Standard mode, but not for Advanced). If Lock is set to true, then when a queue entry is retrieved for processing by the agent activity, that entry will be locked until a commit or rollback occurs at the end of processing, so only one agent/node is trying to process that entry (has exclusive rights to that entry). If some kind of issue occurs (like the agent can’t get a lock on the work object), the queue entry can be re-queued to try again (depending upon its settings).

If Remove is set to true, then the system will immediately remove items from the System Queue, instead of locking them and leaving them in the database table. In this case, the system will perform the commits or rollbacks on the items being processed, but the queue entry will not persist in the database. If a rollback occurs, that entry is now gone.

IMPORTANT: It is not possible to have both Lock and Remove set to true. Only one of

these may be enabled (although it is possible to choose neither as well). If both are enabled, then at runtime, an exception will occur.

GetFirs tByAgentName

This activity will retrieve the oldest entry in the queue for the specified agent name. It uses the following parameters:

PageName* The name of the page onto which all of the queue entry information will be loaded. This page should be defined on the same class (inheriting from System-Queue-) as the agent. AgentRuleSet* The RuleSet that the agent is saved into.

AgentName* The name of the agent.

Lock Whether to lock the queue entry (see explanation in

GetFirstByClass section).

Remove Whether to remove the queue entry (see explanation in

*required value

GetByIns tanceKey

This activity will retrieve an entry in the queue using the ID of that queue entry (the ItemID). It contains the following parameters:

ItemId* The Item ID of the queue entry.

PageName* The name of the page onto which all of the queue entry information will be loaded. This page should be defined on the same class (inheriting from System-Queue-) as the agent.

(29)

Advanced Mode

Lock Whether to lock the queue entry (see explanation in

Remove Whether to remove the queue entry (see explanation in

*required value

Creating a Schedule-Driven Agent

As stated earlier, a customer may wish to have an agent perform processing which is not task-driven. A customer may wish to have a report run every morning on whatever calls were entered into the system the prior day. A customer may also wish to have all idle requestors in the system cleared out every night at midnight, or other such system procedures. In this case, using the System Queue functionality is not necessary. A developer creating one of these agents should set the Queue Mode to Advanced, and uncheck the Auto Queue Manager on the Agents form. They should define their agent activity on the class which holds the data they wish to process.

The agent activity itself must handle all processing, both business and transactional. (The

EstablishContext activity would not be used.) The developer must write the activity to

open any necessary objects, obtain appropriate locks, and make required updates in the database. The activity must also handle any error conditions, such as not being able to obtain locks, or not being able to save data into the database for some reason, and should also track database operations for possible rollback in case of error.

Creating a Custom Agent Activity

If all of the above features still don’t provide the desired agent functionality, it is possible to use Java steps to create a completely custom agent activity.

An example might involve an automated testing facility, where an agent would be used to run an automated test every night. Due to the complexity of this testing, the task takes an extremely long time to run (in computer terms): 30 to 40 minutes. During this time, while the testing (and the agent) are still running, if the server node crashes for some reason, that task never finishes. The queue entry would remain in the Now-Processing status, because the task did not complete; however, since the node crashed and was then brought back up (presumably), this process is now orphaned, because although the status is still Now-Processing, that process is no longer running on the node. With the current agent functionality, there is no way to update the status of that orphaned item, short of manually finding the entry in the System Management Application and changing it there. For agents whose tasks take a very long time to run like this, a check could be included to determine whether there are “orphan” processes for this agent on this node, before beginning processing. The sample activity ProcessAgentItems shows how this custom agent could be defined.

(30)

Advanced Mode

The first step in this activity does an obj-browse. This sets up the page to use for processing, and then checks through all the existing entries to see if any are set to

Now-Processing.

The second step contains the below Java code. For each of these items, the system deletes the item from the queue and then creates a new queue entry:

oLog.infoForced("Found orphaned item: " + myStepPage.getString(".pyItemId"));

try {

// Get item page by key

PRQueueManager qm = tools.getThread().getQueueManager(); ClipboardPage item =

qm.dequeue(myStepPage.getString(".pyItemId")); if (item != null) {

oLog.infoForced("Found orphaned item in db");

// Delete immediately from database and requeue it tools.getDatabase().delete(item, false);

// Reset properties

item.putString(".pyItemStatus", "Scheduled"); // Enqueue it for agent processing

(31)

Advanced Mode

String id = qm.enqueue(item); oLog.infoForced("Requeued as: " + id); }

} catch (DatabaseException ex) {

throw new PRRuntimeException("Problem processing orphaned items", ex);

}

The third step, also Java code, does the actual task processing (the very long automated test – not shown here).

(32)

Agent System Functionality

Agent Sys tem Functionality

Starting Agents – the Agent Manager

The “Agent Manager” is a process in the engine which runs the startup and configuration of Agents rules. When the PegaRULES system is started, the Agent Manager gathers and caches the agent setting information from the prconfig.xml file. The startup process checks prconfig.xml to be sure that enable is set to (the default value of ) true.

NOTE: If enable is set to false, no agents will be configured or run on this system. Note also that the settings in the prconfig.xml file are only read once, at server startup.

Changes to this file will require a restart of the server for the settings to be read and used. Master Agents are used to start the agents. There are actually two Master Agents in PegaRULES:

• Requestor-Timeout Master Agent • Master Agent

The first type of Master Agent is the Requestor-Timeout Master Agent. Every interval (defined by requestortimeoutwakeup in the prconfig.xml file), this Master Agent checks all the requestors currently in the system to see if they’ve timed out. (The actual timeout interval is hard-coded for each type of requestor [batch, browser, app], and adjusted using the timeout node in the prconfig.xml file.) If the requestor hasn’t been accessed in the specified number of seconds (for example, if the user closes the session without logging out), the Requestor-Timeout Master Agent will terminate the requestor for that Agent Activity.

The Master Agent is the agent used to start up and run all agents in Agents rules. There is an initial delay before starting the Master Agents, in order to give the whole system time to start up, stabilize, etc., before starting the agents running.

After that, the Master Agent launches the initial startup of all agents by checking the Agents rules and reading all agent settings. For each Agents rule, the Master Agent then checks if there is a corresponding Agent Schedule (Data-Agent-Queue) instance for the

server node. If the Master Agent does not find an Agent Schedule instance for the current

node, one is created and stored as a new Agent Schedule instance. Then, the Agent Schedule settings in the instance are used to start the agents.

Note that these settings may be different than the Agents rule settings for that RuleSet. The system will not modify the Agents rule to match the new settings, but will use the Agent Schedule settings during run-time.

NOTE: If the minimumwakeup entry in the prconfig.xml file is set, it will override any

Intervals in the Agents rule and Agent Schedule instances that are less than the value of

the minimumwakeup. (This entry is read in at the beginning of system startup.) The Master Agent then starts the enabled agents after an initial delay. For details on running the agents, please see the Overview of Agent Processing article on the PDN.

(33)

Running Agents

Once PegaRULES has been started and the agent activities have been enabled, the activity tasks must be run at their stated intervals.

Each agent activity started by the Master Agent is run in its own separate thread for processing, but when the agent wakes up, it queues the activity in a batch requestor that runs in a thread pool (of size specified in prconfig.xml threadpoolsize) from which these threads are obtained. This means that no more than the number of threadpoolsize agent

activities will run concurrently, irrespective of the wakeup intervals on the queues.

Some agents (such as external lookup agents) may take more time to run their task (15 to 20 seconds) than other agents (.1 second). Threads for these different queues run concurrently. The agents will run and then “sleep” for some interval, until it is time again for their processing, at which point the Java code will “wake” the queue (the Master Agent is not needed to wake the agent activity). For example, the Email_CheckIncoming agent is set to run once every 30 seconds. Once the Master Agent has started this agent, it will run automatically every 30 seconds until it is shut down or until there is a change to the Rule-Agent-Queue instance.

Changing Agents during Runtime

Every interval (the newqueuewakeup setting in prconfig.xml), the Master Agent “wakes up” and scans for new or modified Agents rule definitions. As with the startup, it then checks to see if there is a corresponding Agent Schedule instance, creates one if there isn’t one existing, or uses the existing one if one is found.

If the Master Agent finds that there were changes in an Agents rule, the appropriate changes will be made to the Agent Schedule, either at system startup or Master Wakeup: • If an agent is appended to an Agents rule, it will be appended to the existing Agent

Schedule instance

• If an agent is inserted into an Agents rule, it will be inserted into the existing Agent Schedule instance

• If an agent is removed from an Agents rule, the corresponding row (by class & activity name) will be removed from the corresponding Agent Schedule instance

• If an agent’s class and/or activity name is modified in the Agents rule, the old row will be removed from the Agent Schedule instance, and a “new” row will be added The Master Agent then stops all agents defined by that Agents rule, implements the change, and starts the agents again with the new configuration.

If an agent runs longer than its configured interval (for example if it is configured to run every 5 seconds, but takes 20 seconds to run its tasks), then after the task has completed, it will wait its interval (5 seconds) and then begin the task again. If the task is still running

when the time of an interval passes, the system will not start another duplicate task – it waits for the first one to complete before starting again.

Note that when a new agent is added to an Agents rule using the above process, there will be some period of time when the changed Agents rule and the existing Agent Schedule for the customer RuleSet will be out of synchronization. This synchronization will occur after the Master Agent wakeup period (see the Running Agents section for details).

(34)

This delay will also occur if a change is made directly to the Agent Schedule instance. If an Access Group is added or changed, or an Interval is edited, that change will take place

after the Master Agent newqueuewakeup period.

Terminating and Restarting Agents

If agents all have the Enabled? field checked, they will run automatically. If this box is not checked, the agent will not run.

If the Enabled? field is unchecked by the user in the Agent Schedule instance while the system is running, there will not be an immediate change in the system; however, the next time the Master Agent polls the Agents rule and the corresponding Agent Schedule instance, it will implement the change in the Agent Schedule setting by not starting that agent.

Important: When an agent is terminated due to exception, its corresponding Enabled

flag is cleared in its Agent Schedule instance. This means that the agent will not be restarted until that flag is enabled, or the agent is restarted in the SMA, even if the entire node is restarted.

In addition, details about the exception (stack trace) are saved to the Agent Schedule instance, in that agent’s row data under the property pyFatalMessage. This termination data is not displayed in the form, but is viewable in the XML using the “Rule Data” button. If the agent is restarted using the SMA (see the System Management Application document), the Enabled field for that agent on the Agent Schedule instance will have a check displayed (be enabled). At this point, the exception information stored in the record will be cleared.

NOTE: One kind of exception is handled differently: OutOfMemoryErrors tend to be transient and depend on server load. For these, the Agent Manager will just restart the agent, instead of making a system administrator manually restart them when an exception happens.

Validation

A new property has been added to the Rule-Agent-Queue class:

.pyMustUseQueueManager. This is a boolean property which is set to true if the Agents

rule is a new (Version 5.4 or later) rule. Agents rules created in versions prior to 5.4 and then upgraded to Version 5.4 or later will have this property set to false.

The Rule-Agent-Queue.Validate activity has been updated for Version 5.4. This activity checks whether .pyMustUseQueueManager = true; if it is, then the Queue Mode dropdown box must be set to either Standard or Advanced. Legacy may not be chosen for new agents.

If the .pyMustUseQueueManager property is missing or blank, this Agents rule will be treated as a legacy agent, and the new validation will not be enforced.

Agents Tech Note 0504

Agents – Advanced Topics



Copyright 2008

Pegasystems Inc., Cambridge, MA

This document describes products and services of Pegasystems Inc. It may

contain trade secrets and proprietary information. The document and product are

protected by copyright and distributed under licenses restricting their use,

copying distribution, or transmittal in any form without prior written

authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the

document may be made from time to time at the discretion of Pegasystems. This

document remains the property of Pegasystems and must be returned to it upon

request. This document does not imply any commitment to offer or deliver the

products or services described.

This document may include references to Pegasystems product features that have

not been licensed by your company. If you have questions about whether a

particular capability is included in your installation, please consult your

Pegasystems service consultant.

For Pegasystems trademarks and registered trademarks, all rights reserved. Other

brand or product names are trademarks of their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any

publication may contain inaccuracies or typographical errors. This document

could contain technical inaccuracies or typographical errors. Changes are

periodically added to the information herein. Pegasystems Inc. may make

improvements and/or changes in the information described herein at any time.

Contents

Overview ... 1

Version 5.4 Functionality ... 2

EstablishContext Activity ... 2

The System Queue ... 2

Reporting Entries in the System Queue ... 3

Role Access to System-Queue- Class ... 3

Queue-For-Agent method ... 5

Auto Queue Manager ... 6

Queueing Examples ... 9

Standard Mode ... 11

Creating a Basic Agent ... 11

Setting Additional Properties in a Standard Agent ... 12

Creating an Agent with Two or More Work Objects ... 13

Specifying a Recurring Queue Entry ... 14

Creating a Fully Custom Standard Agent ... 21

Advanced Mode ... 23

Activities for Retrieving Queue Items ... 23

GetFirstByClass ... 23

GetFirstByAgentName ... 24

GetByInstanceKey ... 24

Creating a Schedule-Driven Agent ... 25

Creating a Custom Agent Activity ... 25

Agent System Functionality ... 28

Starting Agents – the Agent Manager ... 28

Changing Agents during Runtime ... 29

Terminating and Restarting Agents ... 30

Validation ... 30

Authorization Contexts and Access Groups ... 31

Access Groups for each Agents rule ... 31

Access Groups at the BATCH Requestor Level – Version 5.4 ... 32

Multiple Access Group Functionality ... 32

Terminating an Agent ... 33

prconfig.xml Settings for Agents ... 35

Viewing Agent Queues in the SMA ... 36

Overview

Vers ion 5.4 Functionality

EstablishContext Activity

The System Queue

Reporting Entries in the Sys tem Queue

Role Acces s to Sys tem-Queue- Clas s

Queue-For-Agent method

Auto Queue Manager

Queueing Examples

Standard Mode

Creating a Basic Agent

Setting Additional Properties in a Standard Agent

Creating an Agent with Two or More Work Objects

Specifying a Recurring Queue Entry

Creating a Fully Custom Standard Agent

Advanced Mode

Activities for Retrieving Queue Items

GetFirs tByClas s

GetFirs tByAgentName