Escolar Documentos
Profissional Documentos
Cultura Documentos
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
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.
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.
CONFIDENTIAL
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.
CONFIDENTIAL
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
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
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.
CONFIDENTIAL
.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
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
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
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
Yes
The next sections describe examples of setting up each of these types of agents.
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.)
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.
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.
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.
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
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
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
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.
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
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.
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
20
CONFIDENTIAL
Standard Mode
NOTE: As in the previous example, the customer may only enter these queue items for one day of the year.
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.
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*
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).
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).
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
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
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.
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
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.
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
CONFIDENTIAL
31
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.
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
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
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
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
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.
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.
36
CONFIDENTIAL
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
CONFIDENTIAL
37
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
<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
DateTime
20071030T144538.640 GMT
Requestor ID
Thread Name
Queue Operation
Item ID
40
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
CONFIDENTIAL
41