Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

How asynchronous service processing works

Updated on September 13, 2021

Introduction

With the exception of the File service type, services typically process service requests synchronously. That is, they immediately perform their requested processing and then provide a response while the external application waits. Starting in V5.4, six service types —EJB, HTTP, Java, JMS, MQ, and SOAP— can use the agent queue functionality to process service requests asynchronously.

Following are the two main use cases:

  • A service is configured to run synchronously, but if the request fails for a temporary reason – perhaps because a work object is locked – the service queues the request and returns an error message that contains the queue item ID of the request. An agent named ProcessQueue (from the Pega-IntSvcs agents rule) attempts to execute the request again later as a scheduled task.
  • A service is configured to run asynchronously. In this case, it responds to the external application’s request by queueing the request and returning a queue item ID that identifies the request. Process Commander then immediately begins processing the service request.

In both cases, the external application can call back later to retrieve the results of the service request because the service requests are stored as persistent objects in the PegaRULES database.

Quick links:

 

Agents, queues, and service requests

Starting in version 5.4, you can use of queues for the work that an agent processes. The standard system-wide queue is a database table named pr_sys_queues that is associated with any Process Commander class that extends a standard class named System-Queue-. The classes represent queues and the tasks to be completed by an agent are stored as instances of such Process Commander classes.

For information about agents, see About Agents.

When configured to do so, the six service types use the new agent queue infrastructure to store service requests as persistent objects in a queue represented by the standard queue class named System-Queue-ExecutionRequest-Service-Default. When a service queues a service request, the queued item contains all the service request content: the activity, the service class, the primary and parameter pages, the request input, the operator ID to use if it needs to run as an authenticated user, and so on.

When the service request is processed, a batch requestor retrieves the service request object from the queue, restores the original service context, and executes the request. When processing is complete, the requestor stores the results with the service request object. That way, the results can be retrieved by the GetExecutionRequest service activity when the external application that made the original request calls back for the results.

Top of Page

Service Request Processors

In addition to information about the task that a service request performs, a queued service request contains configuration information. For example, how many times should Process Commander attempt to run the service request if it fails the first time? You provide this information through service request processor definitions.

Service request processors, instances of Data-Admin-RequestProcessor-Service, specify the following for the services they support:

  • The queue class to use – that is, into which queue should the request be saved. You can either use the standard service queue class (System-Queue-ExecutionRequest-Service-Default) or create a separate queue class for the service requests processed by that service. If you create one, it must extend the System-Queue-ExecutionRequest-Service class so the ProcessQueue agent can find and process the requests in the queue.
  • How many times to run requests if they fail the first time.
  • Whether or not to store the results of successful and/or failed service requests with the queue items and to leave queue items in the queue. If the external application calls back for results, Process Commander should keep the service request in the queue until after the results are retrieved.

You specify which service request processor to use on the Service tab of the service rule. The first key to a service request processor is the name of a service package and a service request processor must belong to same service package as the service rules.

Top of Page

Queue Item IDs

When a service request is queued, you want the service rule to respond to the calling application with the ID of the queue item.

Asynchronous services

For all six service types, the service API writes the queue item ID to the parameter page of the service when a service is configured to run asynchronously. You can configure the data mapping for the response to include an entry for the .pxQueueItemID parameter.

Synchronous services that queue failed requests

When a service is configured to run synchronously and queue failed service requests, how the queue item ID is provided depends on the service type:

  • For HTTP, JMS, and MQ services, you create a data mapping for the .pxQueueItemID parameter in the response.
  • When a Java or EJB service queues a failed request for another attempt, the service returns an exception of type PRQueuedRequestException that contains the queue item ID.
  • When a SOAP service queues a failed attempt for another attempt, the service returns a SOAP fault with the queue item ID as the Fault Detail.

Top of Page

Service Request Execution Results

Use the standard service activity @baseclass.GetExecutionRequest as the service activity for the services that retrieve the results of a queued service request. The GetExecutionRequest activity has one input parameter: ItemID. The calling application must provide the value of a valid queue item ID in a parameter named ItemID.

Top of Page

Queue Maintenance

If your implementation processes many queued service requests, the system's queue table can grow quite large. You can use the System Management Application to remove individual queue items from individual queues. However, its best to talk to your database administrators about purging old service requests from the queue table on a regular basis.

Top of Page

Request Processing Overview

There are enough differences in the way service requests are processed for the two cases (asynchronous vs. synchronous but queue failed) that the following section provides separate descriptions for each.

When synchronous services queue failed requests for another attempt

The following section describes how the processing works when a service is configured to queue service requests if they fail for a specific reason. This description uses an example with two services, UpdateWorkObject and GetResults. UpdateWorkObject is configured to run synchronously and to queue service requests when they fail because the work object is locked. Therefore the data mappings on its Response tab are configured to handle both conditions: when the service request is successfully processed and when it is queued. The GetResults service is configured to run synchronously when the external application calls it to obtain the results from a queued service request.

First service request (UpdateWorkObject)

1. An external application sends a request to the service named UpdateWorkObject.

2. UpdateWorkObject attempts to process the request, but Process Commander returns an object locking error to the service.

3. UpdateWorkObject uses a when condition rule to determine whether the service request failed because the work object was locked. Such a condition is called a “queue when” condition.

4. Because the queue when condition evaluates to “true,” UpdateWorkObject uses the agent queue functionality to create a queue item, set the item’s status to “Scheduled,” store the queue item in the database, and write the ID of the queue item to the pxQueueItemID parameter. When it creates the queue item, UpdateWorkObject determines the following from its service request processor:

  • The name of the queue class.
  • How many times the ProcessQueue agent should attempt to execute the request if it fails.
  • Whether to store the results when the request execution succeeds.

5. UpdateWorkObject returns the ID of the queue item to the external application and closes the connection.

Note that if the work object is not locked, the service runs synchronously. It performs the requested processing and returns the results to the external application without queuing anything.

ProcessQueue agent from the Pega-IntSvcs Agents rule runs

By default, the ProcessQueue agent from the Pega-IntSvcs Agents rule runs every two minutes. When ProcessQueue runs, it processes the item queued by UpdateWorkObject along with all the other scheduled queue items from the queues it monitors.

ProcessQueue does the following for the queue items with a status of Scheduled:

  • Obtains a lock for the queued service request
  • Runs the service request
  • If it successfully runs the request, it changes the status of the item to “Success” and stores the results in the queue with the service request queue item.
  • If the request fails, the agent increments the number of failed attempts for the item and then checks the MaxAttempts setting in the service request definition. If MaxAttempts is set to more than one attempt, it keeps the status of the queue item set to “Scheduled.” The next time the agent runs it tries to execute the service request again. If there are no more attempts left and the service request continues to fail, the agent changes the status of the queue item to “Broken-Process.”

Second service request: GetResults

1. At some later time, the external application sends the queue ID from the original response in a parameter named ItemID to a service named GetResults.

2. GetResults, which is configured to run synchronously, calls the standard service activity @baseclass.GetExecutionRequest and passes it the ItemID parameter.

3. The GetExecutionRequest activity uses the queue ID to retrieve the information about the item from the queue and maps the results to the response properties configured on the service's Response tab.

4. If necesary, the GetResults service could also send the value from the pxExecutionStatus parameter (success or fail).

Note that the external application must be configured to respond appropriately to either case. That is, if it receives the information it requested from the first service it can continue with its processing but it if receives a queue ID instead of the results, it must call back later to retrieve the results.

Top of Page

When a service is configured to run asynchronously

The following section describes how the processing works when a service is configured to process service requests asynchronously. The description uses an example with two services: CreateWorkObject and GetResults. CreateWorkObject is configured to run asynchronously; it queues the service request for immediate execution and returns the queue item ID.

First service request: CreateWorkObject

1. An external application sends a request to a service named CreateWorkObject.

2. CreateWorkObject uses the agent queue functionality to create a queue item for the service request, set the status of the execution request object to “Immediate,” and write the ID of the queued item to pxQueueItemID parameter. When it creates the queue item, CreateWorkObject determines the following from its service request processor:

  • The name of the queue class.
  • How many times the ProcessQueue agent should attempt to execute the request if it fails.
  • Whether to store the results when the request execution succeeds.

3. The service spawns a batch requestor to run the service request.

4. The service returns the queue item ID to the calling application and ends the service call.

The batch requestor

The batch requestor immediately uses the agent queue functionality to lock the service request (queue item) and attempts to execute it.

  • If it successfully runs the request, the requestor changes the status of the item to Success and stores the results with the request object.
  • If the service request fails, the requestor increments the number of failed attempts and then checks the MaxAttempts setting in the service request definition. Depending on the value of MaxAttempts, it either changes the status of the queue item to Scheduled or Broken-Process.
  • If status is set to Scheduled, the request is now queued for the ProcessQueue agent in the Pega-IntSvcs agents rule. The next time the agent runs, it attempts to run this service request.

Second service request obtains the results

At a later time, the external application sends the queue ID from the original response in a parameter named ItemID to a service named GetResults. This service behaves exactly as described above in Second service request: GetResults.

Top of Page

Next Steps

Continue to:

This article links to multiple PRKB articles that are published as a group and can be read in sequence.
The PDN contains other articles about asynchronous services, in addition to those in this group. Click the blue Contents for Category button or use search to access additional articles.

  • Previous topic Configuring a service to process requests asynchronously
  • Next topic Configure a service to queue a failed service request for another attempt

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us