Using Compensating Actions

PegaRULES Process Commander 5.1

! Copyright 2006
Pegasystems Inc., Cambridge, MA
All rights reserved.
This document and the software describe products and services of Pegasystems Inc. It
may contain trade secrets and proprietary information. This information should not be
disclosed to third parties unless otherwise provided for by a contract or business
agreement with Pegasystems. This document and the software are protected by federal
copyright law, international laws, and/or applicable treaties.
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 provided.
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 are 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
(617) 374-9600, fax: (617) 374-9620
www.pega.com

PegaRULES Process Commander
Document: Using Compensating Actions
Software Version: 5.1
Posting Date: June 2006





Using Compensating Actions

In PegaRULES Process Commander (Process Commander), an action in a flow can
have dependencies on later events. For example, perhaps during the life cycle of a
vacation planning work object, a flight reservation and a hotel reservation are booked.
What happens if the hotel reservation is successfully booked but there were no flights
available? Do you need to cancel the hotel reservation? If so, you can add a compensating
action to the flow that cancels the hotel reservation automatically if the flight reservation
part of the flow was unsuccessful.
A compensating action associates an activity (and, optionally, some data) with a work
object. Compensating actions are pertinent to connectors because connectors interact with
external systems that can be gating factors to the resolution of a work object.
This document describes how to use compensating actions, using one of the flows in the
SOAP connector sample posted on the Integration Services pages of the Pega
Developers Network to illustrate the concepts described.
This document contains the following sections:
! Overview
! The Compensating Action Activities
! Summary of Steps
The example referenced in this document is available at the following location:
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp

2 Using Compensating Actions


Overview
A compensating action associates an activity and, optionally, some data with a work
object. The activity is called when a utility function named compensate is invoked by the
flow.
For an example, see the flow named ApplyForCreditCompensate in the SOAP connector
sample posted on the Integration Services page of the Pega Developer Network. In the
sample flow, a SOAP connector asks a Web service for a customers credit report.
Requesting the credit report affects the customers credit rating. As a courtesy to
customers, if the application for credit is canceled, another SOAP connector sends a
request to the service to restore the customers credit rating to the value it held before the
credit report was generated. That processing uses the compensating action feature.
The compensating action feature is implemented through four standard activities, all of
which apply to the Work- base class: CAAddAction, CAAddActionData,
CACompensate, and CACompensateClear. Additionally, the SOAP and dotNET
connector forms provide fields for setting compensating actions and action data.
To use the activities, insert Utility flow shapes at the appropriate spot in your flow and
then select the appropriate activity.
Note: Compensating actions are intended for use when a flow action, an assignment,
or a decision determines that certain work object processing should be reversed. It is
not intended to help you recover from catastrophes such as system failure or the
system going offline unexpectedly.
Compensating Activities
A compensating action is accomplished by an activity. Before you can configure a
compensating action, you must create an activity that performs a compensatory task. In
the SOAP connector sample, the compensatory task is to call the RollbackCreditReport
SOAP connector. Therefore, the connector activity ConnectSamples-SampleWork-
ApplyForCreditCompensate.RollbackCreditReport is the compensating activity.
When you configure a compensating action, you specify the name of the activity to run if
it becomes necessary to perform the compensatory task.


Using Compensating Actions 3


Compensating Action Data
Compensating action data is one or more activity parameter name/value pairs stored with
the name of the compensating activity in the work object. When the compensating
activity runs, it uses the action data to perform its task.
Typically, you use action data to save the state of the work object. If the compensate
function is invoked at some point later in the flow cycle, the value can be retrieved by the
compensating activity and the work object can be rolled back to the state it was in when
the compensating action was set.
In the SOAP connector sample, action data stores the value of the report ID returned by
the CreateCreditReport Web service as an activity parameter named
ActionDataReportID. Then the RollbackCreditReport activity uses the value of that
activity parameter as input for the rollback request.
In another example, imagine that an account balance is incremented or decremented at
some point later in the flow, and the compensating activity needs to restore the account
balance to its current state if a certain condition is met after the balance adjustment. In
this case, you could add action data that sets the current value of the balance property to
an activity parameter (Balance = .AccountBalance, for example) and code an activity that
uses that value to restore the balance to that value (.AccountBalance = Param.Balance).
The Compensating Container
All information about a compensating action the activity and the action data is stored
on the pyWorkpage page in a Page List property named
pyCompensatingActionContainer. This property is of class Embed-
CompensatingActionContainer.
When building a flow that uses compensating actions, be sure to use the clipboard to
examine the values stored on this page regularly to verify that you are getting the desired
results from your compensating actions and action data.




4 Using Compensating Actions


SOAP and dotNet Connectors
The SOAP and dotNET connector rule forms provide fields for setting a compensating
action and action data, which means for these connector rules you can set compensating
actions without using Utility shapes in the flow. (You still have to use a Utility shape to
run the compensate function, however.)
The compensating action fields are on the Response tab. The action and action data
specified on the tab are written to the pyCompensatingActionContainer property of the
work object after the connector receives the reply from the external Web service and
maps the data to a Process Commander property.
Note that if you specify action data that stores a value from the response, but the data
mapping in the connector rule fails, the compensating action will also fail.
Using Compensating Actions 5


The Compensating Action Activities
As mentioned, Process Commander provides four standard activities that implement the
compensating action feature. Each of the activities uses a Java step to call a function
(instance of Rule-Utility-Function) from the compensating action library (Rule-Utility-
Library). Figure 1 shows the function each activity calls.

Activity Rule Utility Function Rule
Work-.CAAddAction addAction
Work-.CAAddActionData addActionData
Work-.CACompensate compensate
Work-.CACompensateClear compensateClear
Figure 1. The Standard Compensating Action Activities and the Functions They Call
The rest of this section describes each activity in detail.
CAAddAction
This activity sets a compensating action in the pyCompensatingActionContainer property
on the work object page. It takes three parameters:
! Action Class Name the Applies To class of the activity that performs the
compensatory task, that is, the compensating activity
! Action Activity Name the second of the two keys to the compensating activity
! Action Label a name that identifies the action
To use this activity, select it from a Utility flow shape or call it from another activity.
When you are creating a SOAP or dotNET connector and want to add a compensating
action after the connector successfully runs, use the Compensating Action fields on the
Response form of the rule. In all other cases, including if you want to set an action before
a SOAP or dotNET connector runs, use the CAAddAction activity.




6 Using Compensating Actions


CAAddActionData
This activity sets action data for the compensating action that was set in the
pyCompensatingActionContainer property on the work object page. Sequence matters:
you must use this activity directly after the CAAddAction activity that created the action
that you want to set action data for.
CAAddActionData takes two parameters:
! Name the name of an activity parameter used by the compensating activity
! Data the value for the parameter
To use this activity, insert a Utility flow shape directly after the Utility shape that calls
the CAAddAction activity and select Work-.CAAddActionData. If you need to set more
than one activity parameter, use an activity that calls the CAAddActionData activity to
set each of the activity parameters.
When you are creating a SOAP or dotNET connector and want to add action data to a
compensating action after the connector successfully runs, use the Compensating Action
Data fields on the Response form of the rule. In all other cases, including if you want to
set action data for an action that is set before a SOAP or dotNET connector runs, use the
CAAddActionData activity.
CACompensate
The CACompensate activity causes all the compensating actions stored on the
pyCompensatingActionContainer clipboard page to run in reverse order. It takes no
parameters.
To use this activity, insert a Utility shape in the flow at the point when compensating
actions should run. Then select the Work-.Compensate activity. Typically, the utility runs
in response to a decision made in an assignment. For example, in the
ApplyForCreditCompensate flow in the SOAP connector sample, when the work object
is canceled, it is routed through a Utility shape called Compensate. This shape calls the
Work-.Compensate activity, which calls the compensate function.




Using Compensating Actions 7


CACompensateClear
The CACompensateClear activity clears all compensating actions from the
pyCompensatingActionContainer page. In the sample flow for the SOAP connector
sample, CACompensateClear is used after the application for credit is approved.
To use this function, call it from a Utility flow shape.

8 Using Compensating Actions


Summary of Steps
Complete the following steps when configuring a flow to set a compensating action.
1. Write the compensatory activity, that is, the activity that completes the
compensation task.
2. Set the activity as a compensating action:
" If you are using a SOAP or dotNET connector and want to add the action after
the connector receives a response, use the Compensating Action fields on the
Response tab of the connector rule. For example, Figure 2 shows the
Compensating Action fields of the CreateCreditReport SOAP connector from
the SOAP connector sample.

Figure 2. Compensating Action Settings in Sample SOAP Connector Rule
" To add the action from an activity, use the Call activity method to call the Work-
.CAAddAction activity.
" To add the action from a Utility flow shape, drag and drop the shape into the
appropriate position in the flow, and then select the Work-.CAAddAction
activity in the Activity field.
3. Add action data for the compensating action immediately after setting the action.
" If you are using a SOAP or dotNET connector and used the Compensating
Action fields on the Reponse tab of the connector rule to specify the action, use
the Compensating Action Data fields to specify the data to store. See Figure 2
for an example.
" If you set the action by calling the Work-.CAAddAction activity from another
activity, create a call to the Work-.CAAddActionData activity in the next
activity step. If you need to set more than one activity parameter, create more
than one step that calls the Work-.CAAddActionData activity.
" If you set the action with a Utility flow shape, insert another Utility shape
directly after it and specify the CAAddActionData activity.
Using Compensating Actions 9


4. Insert a utility flow shape where the flow evaluates conditions that determine
whether the compensating actions should run and the decision is made that the
compensating actions should occur. Perhaps you insert it after a decision rule or in
the path the work object takes in response to a specific flow action. Then select the
Work-.CACompensate activity.
5. At the point that the work object does not need its compensating actions run, insert
a Utility flow shape and select the Work-.CACompensateClear activity.
6. Create a work object to test the compensating actions. Use the Clipboard Viewer to
track the values written to or cleared from the pyCompensatingActionContainer
page property.
The SOAP connector sample posted on the Integration Services pages of the Pega
Developers Network includes a flow that illustrates how to use compensating actions.
Figure 3 shows the Visio diagram of ApplyForCreditCompensate, the SOAP connector
flow with a compensating action.
10 Using Compensating Actions



Figure 3. ApplyForCreditCompensate Flow Diagram
For more information, see the document Building SOAP Connectors and the sample, both
of which are posted at the following Web site:
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp