Queue-For-Agent method

Agents Concepts and terms

Many Process Commander functions rely on processes that operate in the background, performing tasks on behalf of the system and its users.

An agent is an internal background process operating on the server on a periodic basis. Agents route work according to the rules in your application; they also perform system tasks such as sending e-mail correspondence and notifications about assignments, generating updated indexes for the full-text search feature, synchronizing caches across nodes in a multiple node system, and so on.

Each system includes three standard agents: Pega-ProCom, Pega-RULES, and Pega-IntSvcs. You can create additional agents to process tasks or requests that are queued for background processing by your application logic.

You cannot add background processing activities to the three standard agents; instead, create new agent rules that run your agent activities.

Agents rules (instances of Rule-Agent-Queue) hold lists of agents activity. Only one agents rule can be defined in each RuleSet. After determining which RuleSet your new agent belongs to, determine whether there is an agents rule already defined for that RuleSet. If there is, add your agent activities to the existing rule. If an agents rule is not yet defined for that RuleSet, create a new agents rule for that RuleSet and add your new agent information to it.

Agents are implemented through two facilities:

Agents rules instances of Rule-Agent-Queue. These rules specify the agents defined for one RuleSet, the activity that each agent runs, how it handles the queue, and the interval at which it runs. See About Agents rules Agent schedule data objects instances of Data-Agent-Queue. Process Commander generates one agent schedule data node for each node in the system, with information copied from the settings in the associated agents rule. See About Agent Schedule data instancesAn agents rule provides a template that specifies the global settings for that agent on all nodes. To modify the configuration settings for an agent, open the generated agent schedule object for a specific node and modify the settings in the agent schedule.

The Agent Manager is a master agent that gathers and caches the agent configuration information set for your system when Process Commander starts. Then, at a regularly scheduled interval, it determines whether any new agents rules were created during the last period. If there are new agents rules, the Agent Manager adds them to its list of agents and generates agent schedule data instances for them for each node. The Agent Manager also notices when updates are made to existing agents rules or agent schedules.

You can use the Agent Management link in the System Management Application to monitor and control agent processing. (For details, see the System Management Application Reference Guide.)

Overview of agent processing

Summary

Suggested Approach

First, determine what processing your application should do in the foreground, and what should be done in the background.

For example, if the application is processing international transactions, you may need to look up exchange rates in an external database. This could be done in the foreground by connecting to the external system, but that would require users to stop work on the item and wait for the system to retrieve the data before they could do further work. The database connection and retrieval of information may also be done by an agent as a background task, so the user doesnt have to wait and may continue processing that work item.

After you have delineated the tasks that agents should accomplish, you must modify each event (item) which creates an agent task (sending email, handling an assignment) to put the appropriate agent task into the agent queue for the agent to process. (For details, see How To Enter Items into the Agent Queue.)

Next, you must create the agent. (For details, see How to create an agent.)

When Process Commander is started, the agents begin running and processing their tasks, as follows:

Agent Startup

1. When Process Commander starts, the Agent Manager (master agent) gathers and caches all the agent configuration information for your system.

2. The Agent Manager launches the initial startup of all the agents by checking each of the Agents rules and reading all the agent settings for those rules.

3. For each Agents rule, the Agent Manager determines whether there is a corresponding Agent Schedule data instance for each node to use to start the agents.

4. If no Agent Schedule data instance exists for this node, the Agent Manager creates one by copying the relevant information from the Agents rule.

Agent Queue Processing

For each agent which is marked Enabled in the Agent Schedule, the Agent Manager checks its Queue Mode.

Legacy or Advanced Mode

1. Agent Manager runs the agent activity.

2. The agent sleeps for the specified interval.

3. When the sleep interval has passed, the agent wakes up and begins processing from Step 1 of this section.

Standard Mode

1. Agent Manager checks the agents queue for entries.

If there are no entries in the queue, this agent will go back to sleep for the specified interval - without running the agent activity - and then check again.

2. If one or more entries are found in the queue, the system opens the first queue entry.

3. The system runs the agent activity for each item in the queue. For each entry:

If agent processing succeeds, then the Agent Manager commits all deferred operations (saves or deletes) to the database.

If agent processing throws an exception on any operations, then the Agent Manager does a rollback of all entries associated with that task.

NOTE: Unless other time settings are configured, the entries are processed in the order in which they were loaded into the agent queue.

4. When all entries are processed, the agent goes to sleep for an interval.

If the Pattern for this agent is set to Periodic, then the agent sleeps for the amount of time specified in the Interval column.

If the Pattern for this agent is set to Recurring, then the agent sleeps until the next scheduled wake-up time, as specified in the Advanced dialog boxes. (For details, see Agent Scheduling Intervals.)

5. When the interval has passed, the agent wakes up and begins processing from Step 1 of this section.

How to create an agent

Article ID

PRKB-25051

Category

System Operations

Applies from

PRPCV504

Last Updated

March 24, 2008

Rate This Article

Currently 3.8/5 Stars.

1 2 3 4 5Rated 3.8/5 stars

Summary

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

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

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

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

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

Suggested Approach

Before You Begin: Design Considerations

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

what processing the agent will accomplish (see How to write an agent activity)

what event in system processing will create the agent task (see How to enter items into the agent queue)

how long the agent interval should be

how many queue entries an agent should process

in what RuleSet the agent will be saved

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

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

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

For details on setting up agent intervals, see Agent Scheduling Intervals.Setting the Max Records ValueAs stated in the Agent Interval section above, you must judge how many queue entries your application will produce, to determine how often the agent should run. Linked with this decision is the determination of the number of entries the agent should process from the agent queue before going to sleep for that interval.

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

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

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

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

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

1. From Rules by Type, expand the SysAdmin link. Right-click on Agents, and click New.2. On the New form, in the RuleSet - Name field, enter the RuleSet where this Agents rule will be defined. (This must be a valid RuleSet in the system.) Enter the version for this RuleSet, and click Create.Add an agent to the ruleFor each new agent, enter into the Agents form the agent name, class, activity, and schedule, based on the prior decisions you made and the rules you created.

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

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

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

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

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

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

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

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

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

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

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

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

Configure agent-wide settings

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

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

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

4. Save the rule form.

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

About Agent Schedule data instances

KeyScheduleSecurityHistoryMore

Purpose

An agent schedule instance (Data-Agent-Queue class) determines whether an agent runs and, for a multinode system, on which server nodes it runs. Agent schedules cannot be created manually. The Agent Manager master agent generates agent schedule instances from agents rules (Rule-Agent-Queue rule type).

The Agent Manager on your Process Commander system generate at least one agent schedule instance for each agents rule. In a multinode system, for each agents rule, the Agent Manager generates one agent schedule instance for each node. For example, if a clustered Process Commander system has five nodes, then there are five Pega-ProCom agent schedule instances generated from the Pega-ProCom agents rule.

When you need to modify the behavior of an agent listed in an agents rule in a locked RuleSet (any of the standard Process Commander agents rules, for example) you do so by editing one or more of the generated agent schedule instances.

By default, the Agent Manager checks for new or updated agents rule once every ten minutes. After you create an agents rule, the Agent Manager generates one Agent Schedule instance for each node running on your Process Commander system the next time it checks for new agents rules.

Note the following about agent schedules and multi-node clustered systems:

With the exception of the agents listed in the Pega-ProCom agents rule, for legacy agents (those created before V5.4), do not enable agents on more than one node. Legacy agents do not use the Queue Manager or queues and there can be issues with locking if more than one of them are running. After the Agent Manager generates the agent schedules, configure them so that the agents listed in Pega-RULES and the three legacy agents listed in Pega-IntSvcs run on one node only. Agents that use the standard queue mode can run on all nodes.

Users logged in on any of the nodes that share the same PegaRULES database can see the agent schedules generated for all nodes.

Access

The Nodes tab on an agents rule lists all the agent schedules generated for that rule. Therefore, the easiest way to access an agent schedule is to open the agents rule and locate the agent schedule on the Nodes tab. You can also use the Rules by Type explorer to list agent schedules: select SysAdmin > Agent Schedule.

Category

The Data-Agent-Queue class holds agent schedule data instances. They are part of the SysAdmin category.

Agent Schedule formCompleting the Schedule tab

Show all

Scheduled Activities

FieldDescription

Server

System NameServer name of a node. Read-only.

Scheduled Activities

Agent NameThe name of the agent. Copied from the agents rule. Read-only.

ClassApplies To class of the agent activity. Copied from the agents rule. Read-only.

NameName of the agent activity. Copied from the agents rule. Read-only.

PatternSpecifies the schedule type for the agent activity:

Periodic The agent runs the activity and then "sleeps" for the number of seconds entered in the Interval column.

Recurring The agent runs the activity based on a specified calendar schedule (for example, every Monday at 5:00 P.M.).

This value overrides the Pattern specified in the corresponding agents rule (from which this agent schedule was generated). For information about configuring the interval or schedule for this agent schedule instance, see Pega Developer Network article PRKB-25048 How to set agent scheduling intervals.

Interval (secs)If the Pattern field is set to Periodic, enter the amount of time, in seconds, that the agent waits before starting (or restarting) this activity after the queue is empty. Enter a value of at least five seconds.

The value you enter in this field overrides the value specified in the corresponding agents rule.

AdvancedIf the Pattern field is set to Recurring, click Advanced to examine or modify the schedule in the Recurrence dialog box.

Completing the Recurrence dialog box

1. Enter a time in the Start field.

2. Specify the time zone in the time zone field. Be sure to use the long designation rather than the three-letter acronym; for example, use "America/New_York" rather than EST. Otherwise you need to edit the schedules twice a year to accommodate the change to and from Daylight Savings Time for example, change EST to EDT in the Spring, and then back to EST again in the Fall.

3. Configure one of the options in the Pattern section.

3. Click OKto close the dialog box. (The values you entered do not appear on the Schedule tab.)

This information overrides the values entered for this field in the corresponding agents rule.

Enabled?Enables or disables the agent. This value overrides the Enabled setting specified in the corresponding agents rule.

Agent-wide Settings

FieldDescription

Agent-wide Settings

Enable this agentEnables or disables all the agents in the list that have their individual Enabled option selected. Select to enable; clear to disable. The value of this option overrides the Enable this Agent option in the corresponding agents rule.

Interval (seconds)The wake-up interval to use for agents whose Pattern is set to Periodic but do not have a value specified in their Interval fields. Enter a wake up interval of five seconds or more.

Queue-For-Agent method

Use this method when constructing the application logic that queues items such as work objects or assignments to be processed in the background by an agent. This method stores a request for processing as a persistent object (entry) in the system queue. The method specifies:

Which agent is to process the queue entry

How many times the agent attempts to process the entry

How long the entry is to remain in the queue before the agent can try to process it the first time.

Alternatively, your application can call the standard activity @baseclass.QueueForAgent, which has a single step that calls this method.

Step Page

Identify in the step page for this method (or for a step that calls the standard activity QueueForAgent) the class of the work object or other item that is to be processed. For example, if the queued item refers to a work object, set the step page to the work page (typically pyWorkPage). If the queued item is an assignment, set the step page to the assignment page.

Parameters

This method has four parameters:

ParameterDescription

AgentRuleSetThe name of the agents rule of the agent that is to process the queue entry. (The name of an agents rule matches the name of a RuleSet.)

AgentNameThe name of the specific agent that processes the queue entry. This agent must be listed in the agents rule identified by the Agent RuleSet parameter.

MaxAttemptsOptional. The number of tries the agent makes to process the queue entry. If the agent attempts to process the entry this number of times without success, it keeps the item in the queue but changes its status to Broken-Process.

Default value: 1

MinimumAgeforProcessingOptional. The minimum age of a queue entry in milliseconds before the agent tries to process it. The dequeuing process ignores (skips over) any entries that are newer than this value.

For example, if users create queue entries while processing work objects, it is important to ensure that a user releases all work object locks before an agent attempts to process the queue entry. To address this requirement, configure a small delay with the MinimumAgeForProcessing parameter.

The default value is 0, which means the agent can process a queue entry immediately, regardless of its age.

DeferredSelect to defer creation of the queue item until the next Commit method is executed. If not selected, the method creates the queue item immediately and cannot be rolled back.

Results

The system creates an entry in the pr_sys_queues database table as an instance of the System-Queue-DefaultEntry class. This occurs immediately, or upon the next Commit method execution, depending on the Deferred parameter setting.

The item remains in the queue until processed by an agent.

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

Broken queue

To see a list of queue items with a Broken-Process status, which means the agent tried to process the item the number of times specified by MaxAttempts without success, select View > System > Broken Queue Items from the Developer portal menus. This menu selection runs the standard list view report System-Queue-.BrokenItems.All.

Users who hold the @baseclass. ReconcileBrokenQueueItems privilege can resubmit or delete broken queue items.

Other System-Queue- classes

Use a Java step and PublicAPI methods, not the Queue-for-Agent method, to create queue items of System-Queue- classes other than the default (System-Queue-DefaultEntry). For an example, see the standard activity Assign-.AddAssign.