Agents

What are agents?

Process Commander provides a facility to run internal background process operating on the server and performing some tasks on a periodic basis. This facility is called agent.

Agents can execute tasks according to the rules defined in an application, or system tasks such as sending email notifications and outgoing correspondence, or synchronizing caches across nodes in a multi-node system.

What are different agent types or modes?

An agent can either be task-driven or schedule-driven.

What is the diff. between task-driven or schedule-driven agents?

Task-driven agents pick their work from a queue. The queue entries are generally created during the work item processing.

Schedule-driven agents, do not use queue entries but rather directly run an activity to perform their tasks. e.g. every morning an agent runs the system cleaner to clean up temporary database entries. A queue entry is not needed before the agent runs this operation.

What are the agent modes provided by Process Commander?

Legacy- This agent mode only provides backward compatibility for agents being upgraded from versions prior to 5.4. New agents cannot use this mode. Only a “Save-As” on existing legacy agent to a higher version is permitted. No queue is involved in the legacy agents processing. They typically just wake up and run.

Advanced- The agent activity is responsible for both transactional and business processing as in the Legacy mode.  Unlike the Legacy mode, the agent activity in Advanced mode may still use the agent queue functionality; it just must do so explicitly. 
When an advanced agent “wakes up,” it runs its activity directly, and that activity may either call the agent queue and performs all the locking and other database operations, or just does processing without a queue.

Standard- This is the default mode setting for agents created in PRPC versions 5.4 and higher. In this mode, the transactional processing is handled by PRPC itself and leverages the agent queue functionality. Consequently, the agent activity contains only business logic

What are the agent queue?

An agent queue is represented in PRPC by a class and the entries by the instances of that class. 

Standard agents queue entries are instances of System-Queue-DefaultEntry class and are typically persisted in the pr_sys_queues database table.

The System-Queue-DefaultEntry class is automatically used for all task-driven agents with no custom structures. 

Can we create own class for custom agent?

When needed, you can create your own class for a custom agent, but it must directly or pattern inherit from the abstract class System-Queue-.

How queue entries are created?

The entries are generated during the work item processing when the “Queue-For-Agent” activity method or “QueueForAgent” activity is called whenever the task is ready to be queued.

What is the primary page of the agent when it performs the task?

The primary page of the activity or method will be the primary page for the agent processing when the agent performs the task. 

Make sure the object referenced by the primary page is saved and committed to the database with all the property values needed for the agent processing before calling the “Queue For Agent” method or activity.

What values does the queue entry holds?

The queue entry holds a reference to the object and a reference also to the primary page among others data.

What AQM does?

The AQM serves two purposes-

1. It provides a facility to manage the state of each agent queue entry as it is moving from “Scheduled” to “Now-Processing” and to either “Broken-Process” when there is an error or “Success” when the entry process runs successfully.
2. It also controls how a queue entry is retrieved for processing. This includes the locking and updating the state of the entry.

Explain how AQM works?

The AQM can either be enabled or disabled on each agent.

• When enabled, any entry retrieved from that agent queue is locked while the entry is being processed until a commit or rollback occurs at the end of the process. If a rollback occurs, AQM puts the queue entry into failure status and stores it into the “Broken-Process” Queue or “Broken” Queue. From there, someone with access to the broken queue, can view it, fix the issue and re-queue the entry for processing again.
• When the AQM is disabled, the agent gets only one chance to process the entry as the entry is removed from the queue rather than being locked. In the case of process failure, the queue entry is not kept anywhere for another possible attempt.

For this reason, as a best practice, always enable AQM for standard agents.

The AQM is enabled through the agent rule form.

Agents are instance of which class?

Agents are instances of Rule-Agent-Queue class and are part of the SysAdmin category.

Keep in mind that there is one “Agents” rule per RuleSet.

If there is an existing one in the RuleSet, use it otherwise create a new one.