You are on page 1of 45

Agents Advanced Topics

PegaRULES Process Commander

Copyright 2008 Pegasystems Inc., Cambridge, MA


All rights reserved.

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 Updated: March 27, 2008

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 Running Agents ..............................................................................................29

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 Tracing the System Queue Process ...............................................................40

Overview

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 scheduledriven task would be an agent which runs every morning to create a report on the previous days 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 dont 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 agents 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.
1

CONFIDENTIAL

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 doesnt 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.

CONFIDENTIAL

Version 5.4 Functionality

A standard class has been created for the basic Standard agents: System-QueueDefaultEntry. 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 DataAdmin-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

CONFIDENTIAL

Version 5.4 Functionality

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 isnt directly writing to Dataor History-, because the agent is using the users access group, and the agent has to write to those classes, the user must have access to create instances of those classes.

CONFIDENTIAL

Version 5.4 Functionality

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

There are four parameters: Parameter AgentRuleSet Description The RuleSet in which the agent is stored. This should also be the name of the Agents rule in which this agent is contained. This parameter contains the name of the agent (as defined on the Agents rule). 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. 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). Example AcmeCo

AgentName

CallCtrLookup

MaxAttempts

MinimumAgeFor Processing

30,000

CONFIDENTIAL

Version 5.4 Functionality

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 wouldnt), 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 cant 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).

CONFIDENTIAL

Version 5.4 Functionality

.pyItemStatus This property defines the status of the queue entry. The following is a list of valid status values: Status Scheduled Description Signifies that this is an agent task which should be handled by agent processing. 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). 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. 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. 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.

Immediate

Now-Processing

Success

Broken-Process

The entrys 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
CONFIDENTIAL 7

Version 5.4 Functionality

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 arent saved to the queue entry; just the fact that that work item has been changed.)
8 CONFIDENTIAL

Version 5.4 Functionality

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 couldnt get a lock on the work object or something). Since MaxAttempts is set to 3, the system requeues this entry. The database entry is left in the table, but the following updates are made:
CONFIDENTIAL 9

Version 5.4 Functionality

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, As 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 5second delay; again, as there are no other entries in this queue, and A isnt 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 isnt 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.

10

CONFIDENTIAL

Standard Mode

Standard Mode
The Standard mode covers many agent conditions, including a number of custom setups. (In other words, developers shouldnt 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 no no New enqueueing Activity no Yes New SystemQueue- Class

Creating a basic agent Setting additional properties Using two or more work objects Recurring queue entry

no no

no

Yes

no

no

Yes

Yes (recommended) Yes

Completely custom agent

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.)

CONFIDENTIAL

11

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 QueueFor-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 agents 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.

12

CONFIDENTIAL

Standard Mode

NOTE: In this case, since the class of the page is descended from System-Queue-, the Queue-For-Agent method knows it doesnt 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 customers 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-QueueDefaultEntry class, or the developer can create a new System-Queue- class (although in this case, that is not required). This activity must contain several steps: 1. Create a page of the System-Queue-DefaultEntry class (or the new class, if one was created). 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 .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. 4. Call the Queue-For-Agent method, using the page from Step 1, to create the queue entry. NOTE: In this case, since the class of the page is descended from System-Queue-, the Queue-For-Agent method knows it doesnt have to create a new page; it uses the one defined by this activity.

CONFIDENTIAL

13

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. 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) .pxInsHandles(1)

Note: This is an example. It is not required to set these specific properties; other properties may be used in other situations. 4. Call the Queue-For-Agent method, using the page from Step 1, to create the queue entry.

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-EventRecurring), 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).
14 CONFIDENTIAL

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 EmbedData-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 .pyDailyInterval

Description 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.

CONFIDENTIAL

15

Standard Mode

Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT DAILY-EVERYNDAYS 2

.pyRecurrenceDetails.pyPattern.pyType .pyRecurrenceDetails.pyPattern.pyDailyInterval

DAILY-EVERYWEEKDAY This type should be used for an entry which should be processed every n days, but exclude the weekends. .pyPattern properties .pyDailyInterval Description 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 .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT DAILY-EVERYWEEKDAY 2

.pyRecurrenceDetails.pyPattern.pyType .pyRecurrenceDetails.pyPattern.pyDailyInterval

16

CONFIDENTIAL

Standard Mode

WEEKLY-EVERYNWEEKS This type should be used for an entry which should be processed on one day only every n weeks. .pyPattern properties .pyWeeklyInterval .pyDaySelection Description The number of weeks to delay between executions 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. Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T080000.000 GMT WEEKLY-EVERYNWEEKS 1 false,true,false,false,false,false,fal se

.pyRecurrenceDetails.pyPattern.pyType .pyRecurrenceDetails.pyPattern.pyWeeklyInterval .pyRecurrenceDetails.pyPattern.pyDaySelection

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. .pyPattern properties .pyDayOfMonth .pyDayOfMonthInterval Description The integer representing the day of the month (1-31). The number of months to delay between executions.
17

CONFIDENTIAL

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). Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT MONTHLYEVERYNDAYOFEVERYMMONT HS 1 3

.pyRecurrenceDetails.pyPattern.pyType

.pyRecurrenceDetails.pyPattern.pyDayOfMonth .pyRecurrenceDetails.pyPattern. pyDayOfMonthInterval

NOTE: The customer may only enter these queue items for one day of the month. If they st th wished to run this test on the 1 and the 15 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. .pyPattern properties .pyMonthlyWeekSelection .pyMonthlyDaySelection .pyMonthlyInterval Description The integer representing the week of the month (1-4). The integer representing the day of the week (1-7). 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.

18

CONFIDENTIAL

Standard Mode

Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT MONTHLYSPECIFICDAYOFEVERYNMONT HS 2

.pyRecurrenceDetails.pyPattern.pyType

.pyRecurrenceDetails.pyPattern. pyMonthlyWeekSelection .pyRecurrenceDetails.pyPattern. pyMonthlyDaySelection .pyRecurrenceDetails.pyPattern. pyMonthlyInterval

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.

.pyPattern properties .pyYearlyMonth .pyYearlyDay

Description The integer representing the month of the year (1-12). 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. Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT
19

CONFIDENTIAL

Standard Mode

.pyRecurrenceDetails.pyPattern.pyType

YEARLYEVERYDAYOFMONTH 12 31

.pyRecurrenceDetails.pyPattern.pyYearlyMonth .pyRecurrenceDetails.pyPattern. pyYearlyDay

NOTE: As in the previous example, the customer may only enter these queue items for 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.

.pyPattern properties .pyYearlyMonthSelection .pyYearlyWeekSelection .pyYearlyDaySelection

Description The integer representing the month of the year (1-12). The integer representing the week of the month (1-4). 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. Property-Sets required: PropertiesName .pyRequeueOnSuccess .pyRecurrenceDetails.pyStartDateTime PropertiesValue true date/time value in GMT. Example: 20071030T233000.000 GMT YEARLYSPECIFICDAYOFMONTH 1

.pyRecurrenceDetails.pyPattern.pyType

.pyRecurrenceDetails.pyPattern. pyYearlyMonthSelection .pyRecurrenceDetails.pyPattern. pyYearlyWeekSelection .pyRecurrenceDetails.pyPattern. pyYearlyDaySelection

20

CONFIDENTIAL

Standard Mode

NOTE: As in the previous example, the customer may only enter these queue items for 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. This activity must contain several steps: 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 NOTE: In this case, since the class of the page is descended from System-Queue-, the Queue-For-Agent method knows it doesnt have to create a new page; it uses the one created by this activity.

CONFIDENTIAL

21

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-QueueAcmeAgent, 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 ObjOpen-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.

22

CONFIDENTIAL

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 developers 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 PageName* Description 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. The name of the class (inheriting from System-Queue-) on which the agent (and the page) are defined. Whether to lock the queue entry (see explanation below). Whether to remove the queue entry (see below).

ClassName*

Lock Remove *required value

CONFIDENTIAL

23

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 cant get a lock on the work object), the queue entry can be requeued 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: Parameter PageName* Description 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. The RuleSet that the agent is saved into. The name of the agent. Whether to lock the queue entry (see explanation in GetFirstByClass section). Whether to remove the queue entry (see explanation in GetFirstByClass section).

AgentRuleSet* AgentName* Lock

Remove *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: Parameter ItemId* PageName* Description The Item ID of the queue entry. 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.

24

CONFIDENTIAL

Advanced Mode

Lock

Whether to lock the queue entry (see explanation in GetFirstByClass section). Whether to remove the queue entry (see explanation in GetFirstByClass section).

Remove *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 dont 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.

CONFIDENTIAL

25

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 NowProcessing. 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
26 CONFIDENTIAL

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).

CONFIDENTIAL

27

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 theyve 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 hasnt 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.

28

CONFIDENTIAL

Agent System Functionality

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 isnt 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 agents 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).

CONFIDENTIAL

29

Agent System Functionality

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 agents 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.

30

CONFIDENTIAL

Agent System Functionality

Authorization Contexts and Access Groups


As stated in the article Access Groups for Agents (on the PDN), beginning in Version 5.4, access groups are only needed for Legacy or Advanced mode agents. For Standard-mode agents, each queue entry will be processed in the authorization context of the user whose processing (work object, assignment, etc.) generated that entry. (Access groups are needed for releases prior to Version 5.4.) Beginning in Version 5.4, agent functionality will automatically store an authorization context for each queue entry, which will include the access group of the person whose processing created that entry. When the agent processes an entry, the stored context (RuleSet List, etc.) will be used, so that the agent processing occurs in the same context as the work object itself was originally processed. When the queue entry is processed, the system will automatically switch to using the RuleSet List that was saved as the authorization context; it will switch back at the end of processing that task. For Advanced and Legacy mode agents, which are not required to use the System Queue, this context is not automatically restored during agent processing. Therefore, if a developer wishes to preserve the context of the user doing the original work object processing, they must save this context as part of the queue task, and then restore it as the context to run the agent activity. Otherwise, for these agents, they must provide Access Groups which give the agent access to the appropriate objects required to complete the task.

Acces s Groups for each Agents rule


For any non-Pega RuleSets that Legacy or Advanced agents must use, an Access Group should be created which contains that RuleSet - plus any prerequisites - with an appropriate name that signifies that this is an Access Group for Agents (AcmeApp: Agents). For customer or application RuleSets (Acme), where the developer has access to edit the Agents rules, the Access Group information must be added to the Agents (RuleAgent-Queue) form for that RuleSet, in the Access Group field on the Security tab, in order for the agent to be properly initialized in the system. NOTE: This is different from the Pega- agents, where the Access Group information is added into the Agent Schedule.

CONFIDENTIAL

31

Agent System Functionality

PegaRULES Best Practices recommends that customers set up an Agent Access Group for each new non-Standard-mode Agents rule created in a non-Pega RuleSet. Since each RuleSet contains only one Agents instance, the Access Group can be specific to the Agents and Activities in that instance. (In other words, it is not necessary to have all your Agents run out of one Access Group; one Access Group for each RuleSet is recommended.)

Acces s Groups at the BATCH Reques tor Level Vers ion 5.4
As stated in the Access Groups KB article, all processes in PegaRULES are run as requestors on the PegaRULES server, whether they are user sessions or Agents. The Data-Admin-Requestor class holds four types of requestor: APP BATCH BROWSER PORTAL

Agents use the BATCH requestor type, which contains access to the standard Process Commander RuleSet. (NOTE: When users log in, they are using the BROWSER requestor type.) When you change an agent activity and have to add Access Group information, you could add it to the appropriate Agent Schedule record for each node of the system. That can be hard to track, though, if there are many nodes, or if nodes are continually being added or removed. Therefore, if you know that you will need access groups for all your agents, it may be easier to put that information in the BATCH record.

Multiple Acces s Group Functionality


Beginning in Version 5.4, you can put multiple access groups into the BATCH requestor. However, only one access group can be marked as the default. If you have agents in different RuleSets which should use different access groups, you need to put in additional custom code to point an Agents rule to its specific access group. There are two steps in this process: using the AccessGroupToSwitchTo Rule-Utility-Function to determine an access group name using the setActiveAccessGroup API to use that access group

The AccessGroupToSwitchTo Rule-Utility-Function uses the class name of the work object (PegaSample-Task) to obtain the name of the RuleSet where that class is stored. It then sees whether the current access group has access to that RuleSet. Input: class name Return values: empty string (means that the current access group contains the appropriate RuleSet) (none) none of the available access groups work other string the name of the access group which provides access to the appropriate RuleSet
32 CONFIDENTIAL

Agent System Functionality

Both the Rule-Utility-Function and the API would need to be called in custom code. An example of this custom code is below: // Now see if we need to switch access groups for the ruleset of the class of the work object String strAccessGroup = pega_rules_utilities.AccessGroupToSwitchTo( [work object class] ); if (strAccessGroup.equals("(none)")) { [handle the case where no access group is found] } else if (!strAccessGroup.equals("")) { // The ruleset is not contained in the current access group, // but the agent does have this ruleset listed in other access groups it has access to. // Switch to the first one that we found. Note that this does a rollback. String errMessage = ""; try { com.pega.pegarules.priv.authorization.PegaAuthorization auth = (com.pega.pegarules.priv.authorization.PegaAuthorization) tools.getAuthorizationHandle(); boolean switchSuccess = auth.setActiveAccessGroup(tools.getThread(), strAccessGroup); if (!switchSuccess) { [handle failure to switch to this access group] } } catch (InvalidLocaleException ile) { [handle this exception] } catch (BadRulesetException bre) { [handle this exception] } catch (InvalidConfigurationException ice) { [handle this exception] } }

Terminating an Agent
For Legacy and Advanced mode agents, any exception which is thrown from the agent activity (i.e., not caught and handled within the activity processing) will disable that agent. The agent will show in the exception column in the System Management Application, and must be restarted manually by the system administrator. For agents in Standard mode, the System Queue functionality allows an agent to fail to process one or more queue entries without disabling the entire agent; the entries which are not processed are marked Broken-Process and can be requeued or deleted. However, there may be times when a developer does want to disable the entire agent. Suppose that a customer has an application which processes customer calls for a busy
CONFIDENTIAL 33

Agent System Functionality

call center. This call center receives 10,000 calls per day; when users create a work object for each call, part of the processing creates a queue entry for an agent to send an email to the customer with information about their call (their item number, status, etc.). This agent would therefore be processing 10,000 email tasks per day. If the email server went down for several hours, the agent couldnt send any emails; this would result in several thousand queue entries being marked Broken-Process, all of which the system administrator would have to either delete or requeue. In this case, if there is a problem with some functionality outside the agent that would prevent all of the entries from being processed, it might be easier to disable the agent itself rather than having to deal with thousands of broken queue entries. To do this for Standard mode, a new Java method was created: PRQueueTerminateException. The developer should determine what situation would require terminating the agent. In the call center email agent example, the activity might test to verify that the email server is running. If it is, then process the email tasks. If it isnt, then terminate the agent by calling the above method in a Java step in the agent activity: throw new PRQueueTerminateException(message) where message is a String object detailing the reason for the termination. This line has the same effect as clicking the Terminate button in the System Management Application, or throwing any kind of exception in a Legacy or Advanced mode agent.

34

CONFIDENTIAL

prconfig.xml Settings for Agents

prconfig.xml Settings for Agents


There are a number of settings in the prconfig.xml file which relate to agent processing. These values override the settings in the Agent Schedule instances.

prconfig.xml entry agent/minimumwakeup

Description Defines a sleep period, in seconds, for each agent. The default is 30 seconds; the minimum value is 5 seconds. NOTE: This value would override the Interval value in the Agent Schedule instance if minimumwakeup is a larger value.

agent/newqueuewakeup

Defines how often the Master Agent wakes up to scan for new or modified Agent Queue rules. The default value is 600 seconds. Defines the number of Java threads (requestors) on which agents and other BATCH requestors may run. This setting controls the portion of system resources used for background processing, by adjusting the size of the batch requestor pool. The default is 5.

agent/threadpoolsize

CONFIDENTIAL

35

Viewing Agent Queues in the SMA

Viewing Agent Queues in the SMA


Agent queue information may be viewed in the System Management Application. Under the Agent Management link, the System Queue Management link will display information about entries in the agent queues.

The display shows the entries grouped by Status, and displays the following columns: Column Name Status Description Status of the queue entry. Valid statuses include: Scheduled entries which should be handled by agent processing Broken-Process processing failed on these entries Immediate entries which should be handled by services processing Now-Processing these items are currently locked and being processed Success these entries were successfully processed, and re-queued.

Item Count Queue Classes

The number of entries of this Status in the System Queue. The number of unique classes amongst the entries for this Status. The date/timestamp of the oldest entry for each Status. The date/timestamp of the most recent entry for each Status. The sum of the number of times attempts were made to process any queue entry.

Oldest Item Newest Item Total Retries

36

CONFIDENTIAL

Viewing Agent Queues in the SMA

In the above example, there are six entries which have a status of Broken-Process. Only one Queue Class is present, and the Total Retries is also 6, leading to the conclusion that this is one problem agent which has tried to run entries in the system each time, it failed to process its task. (The developer should check whether this agent has MaxRetries set to higher than one it might be useful to have the system try again before setting entry status to Broken-Process.) NOTE: If all entries were successfully processed, and RetainOnSuccess is set to false, then this section would always be blank. To see individual entries for a Status, click on the radio button next to the appropriate Status and then click the Details button at the top of the screen. The entries will be displayed:

This display shows the entries grouped by Class, and displays the following columns: Column Name Class Item ID Enqueued Description The class of the entry (must inherit from System-Queue- ) The unique Queue item key for this entry The date/timestamp this item was entered into the System Queue The date/timestamp of the time this entry was last locked for processing The number of attempts the system had made to process this entry The node where this entry is being processed. NOTE: This column will only display data for entries which have a status of Now-Processing

Last Processed

Attempts

Current Processing Node

CONFIDENTIAL

37

Viewing Agent Queues in the SMA

There are also a number of buttons at the top of the screen. View Clicking on the radio button next to one of the entries and then clicking the View button shows the XML code for that queue entry. Output for SystemQueueManagement / PerformAction / 1.0 <?xml version="1.0"?> <pagedata> <pxInsName>SYSTEM-QUEUE-EXECUTIONREQUEST-SERVICE-DEVTEST1 9802514FC24572135521D1F532E77EA4 1187198285426000</pxInsName> <pyPackageName>DevTestSOAP</pyPackageName> <pyProcessorName>mySOAP</pyProcessorName> <pyServiceMethodName>Create</pyServiceMethodName> <pyAccessGroup>AblalApp54:Dev</pyAccessGroup> <pyRequestParameterPage mode="J">rO0ABXNyABFqYXZhLnV0aWwuSGFzaE1hcAUH2sHDFmDRAwACRgAKbG9hZEZhY3 RvckkACXRocmVz aG9sZHhwP0AAAAAAAAx3CAAAABAAAAACdAANcHhRdWV1ZUl0ZW1JRHQAYFNZU1RFTS1RVUV VRS1F WEVDVVRJT05SRVFVRVNULVNFUlZJQ0UtREVWVEVTVDEgOTgwMjUxNEZDMjQ1NzIxMzU1MjF EMUY1 MzJFNzdFQTQgMTE4NzE5ODI4NTQyNjAwMHQACVBob25lQm9va3QABk15VGVzdHg=</pyReq uestParameterPage> <pyRetainOnFailure>true</pyRetainOnFailure> <pyItemId>SYSTEM-QUEUE-EXECUTIONREQUEST-SERVICE-DEVTEST1 9802514FC24572135521D1F532E77EA4 1187198285426000</pyItemId> <pyServiceType>SOAP</pyServiceType> <pyServiceClassName>PhoneBook</pyServiceClassName> <pyActivityName>Create</pyActivityName> <pyItemStatus>Success</pyItemStatus> <pzInsKey>SYSTEM-QUEUE-EXECUTIONREQUEST-SERVICE-DEVTEST1 SYSTEM-QUEUEEXECUTIONREQUEST-SERVICE-DEVTEST1 9802514FC24572135521D1F532E77EA4 1187198285426000</pzInsKey> <pyActivityClass>SampleBase-PhoneBook</pyActivityClass> <pyRetainOnSuccess>true</pyRetainOnSuccess> <pxCreateDateTime>20070815T171805.426 GMT</pxCreateDateTime> <pyMinimumDateTimeForProcessing>20070815T171805.426 GMT</pyMinimumDateTimeForProcessing> <pzStatus>valid</pzStatus> <pyMaxAttempts>3</pyMaxAttempts> <pxObjClass>System-Queue-ExecutionRequest-Service-DevTest1</pxObjClass> <pxLastExecutionDateTime>20070815T171805.614 GMT</pxLastExecutionDateTime> <pyAttempts>1</pyAttempts> <pyRequestPrimaryPage> <pxInsName>MYTEST</pxInsName> <pzInsKey>SAMPLEBASE-PHONEBOOK MYTEST</pzInsKey> <pxObjClass>SampleBase-PhoneBook</pxObjClass> <Title>MyTest</Title> <Contact REPEATINGTYPE="PageList"> <rowdata REPEATINGINDEX="1"> <FirstName>Alex</FirstName> <pxObjClass>SampleBase-Contact</pxObjClass> <PhoneNumber>111</PhoneNumber>
38 CONFIDENTIAL

Viewing Agent Queues in the SMA

<LastName>Jake</LastName> </rowdata> </Contact> </pyRequestPrimaryPage> </pagedata> Remove Clicking on the radio button next to one of the entries and then clicking the Remove button will delete that entry out of the queue. The entry will be locked first, to verify that its not being processed by another agent, and then it will be deleted. (This button would be used for an agent getting re-queued and then erroring out.) This button would not be valid for entries with status Now-Processing.

Defer Clicking on the radio button next to one of the entries and then clicking Defer will change that entrys status to Broken-Process. This button is only valid for entries with status Scheduled or Immediate.

Stop Clicking on the radio button next to one of the entries and then clicking Stop will interrupt the requestor/agent that is now processing, and set that entrys status to Broken-Process. This button is only valid for entries with status Now-Processing.

Requeue Clicking on the radio button next to one of the entries and then clicking Requeue will change this entrys status from Broken-Process to Scheduled, and reset its process time. This button is only valid for entries with status Broken-Process.

CONFIDENTIAL

39

Tracing the System Queue Process

Tracing the Sys tem Queue Proces s


The System Queue can generate tab-delimited trace files to show what operations are performed and how the queue entries have been processed. If the System Queue does not seem to be processing correctly (performance is slow), or if a developer wishes detailed information on what agents were run for a given process, then a trace file can be generated to aid in troubleshooting. This data can be reported for an entire node, or for just one requestor. Be careful when enabling this tracing for an entire node! This should never be done in production, as the amount of data produced can be overwhelming. To trace System Queue processing for an entire node, use the following prconfig.xml setting: <env name="agent/SystemQueue/dumpStats" value="true"> Again, this setting should never be enabled in a production system. Enabling tracing for just one requestor is not done through the prconfig.xml file; rather, the property pxRequestor.pyQueueTraceEnabled must be set to true either in the EstablishContext activity or the actual agent activity. These trace files are written to the StaticContent/Global directory, with names such as: QueueOperations_20071030T144516_640_GMT.txt The following information is recorded in the file: Column Name Sequence Description the step number (sequence number) of this entry the date/timestamp when this entry was processed The ID of the requestor on which this entry was processed The name of the Thread where this entry was processed The type of oepration that was done on the queue putting a task in (enqueue), removing a task from the queue (dequeue), etc. The ID of the queue entry. Example Entry 1

DateTime

20071030T144538.640 GMT

Requestor ID

(AC224423B3659FA1716DA 1DFEBF4F58FD) STANDARD

Thread Name

Queue Operation

enqueue dequeue commit rollback SYSTEM-QUEUEMIRATJUNITTEST 1193755538484000AB5017 975302AB0E5823DADD731 6DC11


CONFIDENTIAL

Item ID

40

Tracing the System Queue Process

Item Status Item Class

The status of this queue entry. The class (inheriting from SystemQueue-) on which the queue entry and the agent is defined. Notes explaining what happened in this process step

Now-Processing System-QueueMiratJUnitTest

Details

successfully dequeued item attempting to commit item

CONFIDENTIAL

41