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.

Configure a service to queue a failed service request for another attempt

Updated on September 10, 2021

Summary

Starting in Version 5.4, you can configure your service implementation so that failed service requests are queued for another attempt with the following service types: EJB, HTTP, Java, JMS, MQ, and SOAP.

To configure this kind of service, you specify that it executes synchronously. Then you configure a Queue When condition that defines a specific kind of possible failure – the work object is locked, for example. When the condition evaluates to true, the service queues the request and returns an error message that contains the queue ID of the request. The ProcessQueue agent attempts to run the request again later as a scheduled task. Typically the external application calls back later to retrieve the results.

This article describes how to configure a service that queues a failed service request for another attempt. For background information, see What is asynchronous service processing? and About Agents.

 

Suggested Approach

To set up a service that queues failed service requests for another execution attempt, you start by using the Service Accelerator to generate the rules and data objects as usual. Then you determine which queue class to use for the queued service requests, create the service request processor, and edit the generated service rule. And finally, in most cases you create another service rule to get the results by using the GetExecutionRequest activity.

Generate the service

Select Application > New > Service to run the Service Accelerator and then complete the steps in Creating services with the accelerator.

Identify (and perhaps create) the queue class

Determine whether you can use the standard service queue class (System-Queue-ExecutionRequest-Service-Default) or whether you need to use different queues for different services and in different RuleSets.

If you need more than one queue, create one queue class for each queue you need. Queue classes for service requests must extend the standard Process Commander class named System-Queue-ExecutionRequest-Service.

Do you need to use more than one queue for the same service? If so, create When condition rules that specify when a service request should be routed to that queue. You use the When condition rules in the service request processor that you create for the service. Remember that the When condition rule must apply to the queue class it evaluates.

Create the Service Request Processor

As described in How asynchronous service processing works, a service request processor provides configuration information about where to queue a service request, how many times to attempt to execute it if fails the first time, and so on.

Complete the following steps.

1. From the Rules by Type explorer, select Integration-Resources > Service Request Processors.

2. Click New.

3. In the New form, select the service package and name the request processor.

4. On the Queuing Options tab, specify the name(s) of the queue class(es) to use for the service requests supported by this request processor. The default service queue class is System-Queue-ExecutionRequest-Service-Default.

5. Do one of the following:

  • If you specify one queue class, leave the When to use this queue field blank.
  • If you specify more than one queue class, select When condition rules in the When to use this queue fields. Order the queue classes so the default queue is the last one in the list and do not assign a When condition rule to that queue.

6. On the Dequeuing Options tab, specify how many times the service request should be attempted if it fails the first time.

7. Select both Keep in queue after all execution attempts failed and Keep in queue after successful execution.

8. Save the service request processor.

Create the When rule for the Queue When condition

You also need to create or identify a When condition rule that checks for the error condition that causes the service to queue the request.

To create a When rule, select Decision > When in the Rules by Type explorer and then click New.

Configure the rule to return a value of “true” when the error condition takes place. For example, following is a When rule that returns a value of true when the work object is locked:

Configure the first service rule

Locate and open the generated service rule. Edit the service rule as follows:

1. On the Service tab, verify that the Execution mode field is set to and select Execute Synchronously.

2. Specify the service request processor you created in the Request Processor field.

3. On the Request and Response tabs (HTTP, JMS, MQ, or SOAP) or Parameters tab (EJB or Java), examine and verify that the data mappings generated by the accelerator are appropriate for the default case when the request is successfully processed. Modify them if you need to.

4. Configure the rule to test for a Queue When condition, specify the When condition rule you created, and configure the response message to be returned when the Queue When condition is met. The steps you take to accomplish this task depend on the service type.

For SOAP:
 
Select the Fault tab and configure a fault condition as follows:

  • Select Queue When from the Condition field
  • In the When Key field, select the When condition rule you created.
  • Select Constant from the Map From field.
  • In the Map From Key field, enter a descriptive string. For example “Item was locked. Queued for another attempt.”

For example:

At runtime, when this condition evaluates to “true,” Process Commander generates a SOAP fault. The string you entered in the Map From Key field is used as the Fault String and the value of the pxQueueItemID parameter is used as the Fault Detail. The calling application must catch the Fault and use the queue item ID in the request for results.

For HTTP:

Select the Response tab and insert a Queue When condition before the default response condition. Configure it as follows:

  • Select Queue When from the Condition field
  • In the When Key field, select the When condition rule you created.
  • In the Message Data section, select Clipboard in the Map From field and specify Param.pyQueueItemID in the Map From Key field.

For example:

At runtime, when this condition evaluates to true, the service responds to the calling application with the value of the pyQueueItemID parameter.

For JMS or MQ

Select the Response tab and insert a Queue When condition before the default response condition. Configure it as follows:

  • Select Queue When from the Condition field
  • In the When Key field, select the When condition rule you created.
  • Select Text Message in the Message Type field.

In the Message Data section, configure one data mapping row as follows:

  • In the Data Type field, select String.
  • In the Map From field, specify Clipboard.
  • In the Map From Key field, specify Param.pyQueueItemID.

For example:

At runtime, when this condition evaluates to true, the service responds to the calling application with the value of the pyQueueItemID parameter.

For EJB and Java:

Select the Exceptions tab and configure a Queue When condition as follows:

  • Select Queue When from the Condition field
  • In the When Key field, select the When condition rule you created.
  • Select Constant from the Map From field.
  • In the Map From Key field, enter a descriptive string. For example “Item was locked. Queued for another attempt.”

For example:

At runtime, when this condition evaluates to “true,” Process Commander generates a Java exception of type PRQueuedRequestException that includes the value of pxQueueItemID and the string you entered in the Map From Key field. The calling application must catch the exception and use the queue item ID in the follow-up request for the results.

Create the “get results” service rule

Now create a service rule that uses the standard service activity @baseclass.GetExecutionRequest to deliver the results of the original service request when the external application calls back. Because the Service Accelerator does not allow you to select inherited activities, you create this service rule manually.

New form

In the New form, specify the same RuleSet and RuleSet version that you used for the first service.

Service tab

On the Service tab:

  • Use the same Page Class that you used in the first service.
  • Specify the GetExecutionRequest activity as the service activity.
  • Select Execute synchronously in the Execution Mode field.

Request

On the Request tab for a SOAP, JMS, MQ, or HTTP rule or the Parameters tab for an EJB or Java service, configure the data mapping for the ItemID parameter. For example:

Response

When the service creates its response, all the data from the retrieved service request is on the Clipboard. You can map as much or as little of it as neccessary on the Response tab for a SOAP, JMS, MQ, or HTTP rule or the Parameters tab for an EJB or Java service.

If the external application just needs a confirmation message about whether the request ran successfully, you can configure a data mapping for the pxExecutionStatus parameter. Here’s an example from a SOAP rule:

Next Steps

Next, test your service implementation to verify that it works as expected. For information about tools and methods, see also Testing Services and Connectors.

See also How to configure a service to process requests asynchronously.

 

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