Designing Applications That Ensure Data Integrity Full Guide

Designing Applications that Ensure Data Integrity PegaRULES Process Commander Versions v5.1 and 5.
Copyright 2007 Pegasystems Inc., Cambridge, MA

All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. 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 described. 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 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 Phone: (617) 374-9600 Fax: (617) 374-9620 www.pega.com PegaRULES Process Commander Document: Designing Applications that Ensure Data Integrity Software Version 5.1 and 5.2 Updated: January 2007
Contents
Chapter 1: About This Document.................................................................................................. 5 Who Should Read This Document......................................................................................... 6 Definition of Terms.................................................................................................................. 7 Chapter Overview ...................................................................................................................10 The Pega Developer Network (PDN) .....................................................................................11 Chapter 2: Introduction .................................................................................................................12 Overview of Object Locking ..................................................................................................13 Process Commander and Database Operations .................................................................14 When Commits Occur Programmatically......................................................................14 Activity Methods that Cause Database Operations .....................................................15 Managing Commits and Rollbacks in Custom Activities.............................................16 Process Commander Commits and Distributed Transactions...........................................20 Chapter 3: Object Locking ............................................................................................................22 About Object Locking ............................................................................................................23 Lock Keys and Lock Strings ..........................................................................................23 Lock Lifespan ..................................................................................................................24 How Locking is Enabled .................................................................................................25 How Locking is Implemented.........................................................................................25 Locking and Permissions...............................................................................................26 Database Isolation Levels ..............................................................................................26 Enabling Object Locking Manually .......................................................................................27 Before You Begin ............................................................................................................27 Configure Locking for Class Groups and Classes.......................................................29 Customize Object Locking for Cover Objects .....................................................................31 Chapter 4: Application Processing that Obtains Locks.............................................................32 Obtaining Locks for Work Objects .......................................................................................33 Assign-.acquireWorkObject Activity .............................................................................33 Work-.acquireWorkObject Activity ................................................................................35 Example: MergePage Parameter and Service Rules....................................................36 Obtaining Locks for Objects that are not Work Objects.....................................................37 Using the Obj-Open Method...........................................................................................37 Using the Obj-Open-by-Handle Method ........................................................................38 Using the Obj-Refresh-and-Lock Method......................................................................39
Designing Applications that Ensure Data Integrity
Managing When Object Locks are Released .......................................................................41 Reporting Locking Messages to Users ................................................................................42 About LockInfo Pages ....................................................................................................42 Using the LockInfo Harness...........................................................................................43 Capturing Lock Information and Setting it in a Page Message...................................44 Lock Status Messages....................................................................................................46 Troubleshooting and Testing ................................................................................................48 DeferredOps HTML rule ..................................................................................................48 Tracer ...............................................................................................................................48 System Locks Report......................................................................................................48
Chapter 1 About this Document

During PegaRULES Process Commander processing, data is read from and saved to the PegaRULES database. When more than one person is using a Process Commander application, two people may try to save the same work or other object to the database at the same time. If they are both allowed to succeed, one persons changes overwrite the others, possibly resulting in inaccurate data. Process Commander provides several features that ensure the data integrity of the work and other objects managed by your Process Commander applications. This document describes those features and uses examples from standard Process Commander RuleSets to illustrate key points.
Who Should Read This Document

If you are a Process Commander system architect (developer) who is responsible for application design and architecture, database operations, or security design and implementation, you should read this document. It is assumed that you understand Process Commander terminology, forms, functions, and the SmartBuild design and development process. You should have at least some experience in defining Process Commander classes, properties, and models, and in configuring activities and flows rules. For access to the troubleshooting tools and to the integration features described in this document, you need administrator rights in Process Commander. That is, you should have the SysAdmin role and the Developer portal assigned to your operator ID record.
Definition of Terms
Figure 1-1 defines the terms used in this document.
Term Database locking
Definition Mechanisms provided by your database management system that control how/whether operations access data at the same time. Database locking provides functionality such as preventing two write operations from committing changes to the same row at the same time. This kind of locking does not prevent one user from overwriting another users edits if your application allows two users to open and edit the same item at the same time.
Object locking
Ensures that while one user has a work or other object open, no other user can access that object. With object locking, the application grants the user a lock on that item when the user opens a work or other object. If a second user attempts to open and edit the same object, he or she is denied access because the object is already locked. A Java object that holds information about a user and that users session. In Process Commander, users are represented as requestors and object locks are associated with a users requestor. A parameter for the Obj-Open, Obj-Open-by-Handle, and ObjRefresh-and-Lock activity methods. When selected, this parameter instructs Process Commander to obtain an object lock on the item being opened. A parameter for the Obj-Open, Obj-Open-by-Handle, and ObjRefresh-and-Lock activity methods. When selected, this parameter instructs Process Commander to release the object lock on the item being opened when changes for the object are committed to the database. A text string that identifies an object lock. Typically, when the activity methods that save or delete objects are used, they dont cause the object to be saved or deleted immediately. Instead, these methods set up deferred write or deferred delete operations that are stored on a list of deferred operations. When a commit method is invoked, Process Commander completes all the tasks on the deferred operations list.
Requestor
Lock parameter
ReleaseOnCommit
Lock string Deferred operations list
Term Server interaction
Definition One request/response interaction between the Process Commander application and a server one HTTP communication, SOAP message and response, or Java invocation, for example. When an external system makes a service request to Process Commander, the request to the service rule and the service rules response occur within one server interaction. When an end user interacts with Process Commander from a Web browser, a server interaction is one HTTP request/response.
Transaction
A set of related operations that need to be treated as one operation for the purposes of data integrity. All of the related operations must succeed, or none of them will. A transaction ends in either a commit or a rollback. A transaction occurs within the scope of one server interaction.
Business transaction
Some subset of operations that are grouped together conceptually according to the design of the application doing the work. In the context of Process Commander, a business transaction typically means the work done with/to an object during the scope of an object lock. For example, an assignment is a business transaction. The scope of a business transaction is based on human intent. The start and end points do not mark transactional boundaries they mark the scope of an object lock. Depending on how a flow is designed, there can be several server interactions during one assignment (business transaction) because a separate server interaction occurs each time a form is refreshed. That is, a business transaction can span several server interactions.
Distributed transaction
A set of operations that include more than one resource manager and that must be treated as one operation. For example, updates to more than one database in the same transaction, or, a database transaction and the sending or receiving of a JMS message in the same transaction. To use distributed transactions, Process Commander must be deployed as an enterprise application and must be using a JDBC driver with XA support. Distributed transactions can be either bean-managed or containermanaged.
Bean-managed transaction
When running in this mode, Process Commander is in charge of the (distributed) transaction. Process Commander issues the
Term
Definition begin statement and the final commit or rollback. When deployed as an enterprise application, Process Commander is configured to run in this mode by default. That is, by default, transactions are bean-managed by Process Commander.
Container-managed transaction
When running in this mode, an external J2EE container starts and ends distributed transactions that Process Commander joins as one of the participating resources. When Process Commander finishes its work, it submits a list of operations to the resource manager(s) or it marks the transaction for rollback. If none of the resources participating in the transaction (including Process Commander) mark the transaction for rollback, the Process Commander operations are committed with the other operations within the boundaries of the transaction. If Process Commander or any of the other resources participating in the transaction marks the transaction for rollback, all the operations are rolled back. Note that only the processing managed by certain Process Commander service rule types (EJB, Java, and JMS ) can participate in container-managed transactions. For more information, see Distributed Transactions and PegaRULES Process Commander.
Transaction attribute
A setting for enterprise beans that determine how the bean or an individual business method in the bean is enlisted in containermanaged transactions. For example, whether it needs a new transaction to be started, whether it must join an existing transaction, and so on.
Figure 1-1. Definitions of Terms
10
Chapter Overview
The following is a list of the remaining chapters in this document: Chapter 2, Introduction, introduces the object locking feature, describes the Process Commander deferred operations list and the activity methods that cause database operations, describes when commit operations occur as part of normal flow processing, presents information about how to write custom activities that manage commits and rollbacks, and discusses the difference between a Process Commander commit and a distributed transaction. Chapter 3, Object Locking, describes the object locking feature in detail and presents steps for enabling object locking. Chapter 4, Application Processing that Obtains Locks, describes the standard activities and activity methods to use when developing application processing that opens objects, explains how to configure applications that report locking errors to end users, and provides some troubleshooting tips.
11
The Pega Developer Network (PDN)

As a member of the Process Commander developer community, your primary technical resource is the Pega Developer Network (PDN). The PDN contains a broad range of technical articles including troubleshooting and how-to information as well as a comprehensive and searchable knowledgebase to help developers speed their application development. Before you can use the PDN, you must register to obtain an account at the following URL: http://pdn.pega.com After you have an account you can access the site directly from the Process Commander application. From the Process Commander menu, select Help > Pega Developer Network.
12
Chapter 2 Introduction
In addition to the locking mechanisms provided by your database software, Process Commander provides object locking. While database locking ensures an object is locked during the span of a database operation (update, delete), object locking ensures that the object is locked during the entire span of time a user is working with that object. This document describes how Process Commander locks objects, how it manages commit operations, and how it manages and/or participates in transactions. It provides the information you need to design applications that take advantage of Process Commanders default object locking behavior and to configure custom processing for your applications that follows best practices: obtaining object locks as appropriate, gracefully managing errors when an object lock already exists or when commit operations fail, and so on.
13
Overview of Object Locking

Process Commander objects are subject to two kinds of locks: database locks and object locks. Database locks are tightly focused in scope and have short durations. That is, database locks affect specific database rows and are meant to be held for the brief period of time (typically milliseconds) that it takes to save, update, or delete an object. Database locking ensures that while a database operation for a specific object is underway, no other database operation is allowed on that same object. Object locking is an application-level lock that Process Commander holds on objects for a much longer duration than that of a database lock. Object locking for work objects is enabled by default.
Object locks are associated with users requestors. Requestors obtain a lock on a work or other object when the user opens an object for modification. While the requestor holds the object lock, no other requestor can make changes to that object. After the processing of the application causes the changes to be written to the database, the lock is released and the object is available to another requestor. Why isnt database locking enough? Consider the case in which two users open the same assignment, which opens the same work object. Without object locking, both users can make changes to the work object but which set of changes persist will depend on timing. The first user to finish making changes clicks the Save button. The database obtains a database lock and saves the object. Then the slower user clicks the Save button. The database obtains another database lock, saves the object, but what happens to the data entered by the first user? Very likely it is overwritten. Object locking prevents that from happening by locking the work object when the first user opened the assignment. As mentioned, object locking is enabled on work objects by default; the standard activities that provide flow processing for your applications acquire and release object locks as appropriate. However, whenever your application design needs require you to write your own custom activities that interact with work or other objects, you must configure the activities to acquire and release object locks appropriately. Chapter 3: Object Locking describes how to enable object locking for objects that are not work objects. Chapter 4: Application Processing that Obtains Object Locks describes the standard helper activities and activity methods to use when writing custom activities that open objects.
14
Process Commander and Database Operations

In addition to the object locking feature, Process Commander ensures data integrity by creating a deferred operations list during a business transaction rather than writing each change to the database individually. For example, consider an assignment during which a user adds an attachment, changes the value of a property, and adds another work party to a work object. With standard flow processing, each of those operations is written to a deferred operations list. When the user finishes the assignment, Process Commander commits the changes by completing all the operations on the deferred list and releases the object lock appropriately. If any of the operations fail, Process Commander rolls all of them back, thereby ensuring data integrity.
When Commits Occur Programmatically

When a user is working with a work object that is, is in the process of a business transaction updates to the work object are deferred until the end of the business transaction. When the flow processing completes for a business transaction, the work object is committed and, usually, the object lock is released. For example, utility or routing activities can call other activities, that can call declarative rules or start new work objects, and so on. When all the processing and subprocessing is done and control is returned to the user an assignment is transferred, for example the work object is automatically committed. During a commit operation, Process Commander does the following: 1. Completes all the operations for all the objects on the deferred operations list. The RDBMS obtains a database lock for each item to be committed and releases the locks when the operations are completed. 2. Releases the object locks that are specified as ReleaseOnCommit. During normal flow processing, commit operations occur automatically at the following times: When a new work object is created. When a work object is updated, resolved, reopened, and so on. After the processing invoked for a flow action is completed. For example, a Submit button is clicked. When an assignment is completed and the work object moves to the next assignment; for example, whenever the Get Next Work processing transfers an assignment from a work basket to a worklist.
15
Note: If an activity calls the Flow-New method, Process Commander does a

deferred save of the current work object rather than a commit before that activity step. For the following reasons, you should never use the Commit activity method in an activity that is executed within a flow: If the object lock for the work object is ReleaseOnCommit, the work object loses its object lock and then any subsequent processing for that object fails because it doesnt have a lock on the object. After a commit to an object whose lock is not released, a condition exists in which a partial business transaction failure can occur. That is, if an error occurs after the commit, only those operations that were written to the deferred operations list since the commit can be rolled back.
It is a best practice to create applications that take advantage of the automatic commits provided with normal flow processing. Only when your application is designed to save objects that are not work objects should you use the activity methods that cause database operations (described in the next section) in your custom activities. If your application design requires that the commit of a work object occurs during custom processing, use the standard activity Work-.CommitWithErrorHandling rather than Commit or Obj-Save activity methods.
Activity Methods that Cause Database Operations

Process Commander provides four activity methods that cause data operations to occur (Figure 2-1). It is best practice for you to use these methods only when you are configuring custom processing for objects that are not work objects.
Activity Method Obj-Save
Description Specifies that an object should be saved. By default, Obj-Save sets up a deferred write operation that does not occur until the next commit operation executes. In the very rare case that your application design requires it, you can select the WriteNow option, which forces an immediate commit of the current object. The WriteNow option does not affect any other objects with operations pending on the list of deferred operations and does not release the object lock.
Obj-Delete
Specifies that the object should be deleted. By default, this method sets up a deferred delete operation and the object is not deleted until the next
16
Activity Method
Description commit operation executes. If your application design requires it, you can select the Immediate option, which forces an immediate deletion of the object.
Commit
Specifies that all operations currently on Process Commanders deferred operations list be written to the database. If any of the operations fail, the commit will end in a rollback: all the operations will be rolled back. Note that if your application design requires you to manage the commit operation for a work object perhaps you create a button or other custom widget that commits a work object use the standard activity Work-.commitWithErrorHandling rather than the Commit method.
Rollback
Specifies that all operations currently on Process Commanders deferred operations list should be removed, or rolled back. Any objects with locks specified as ReleaseOnCommit are released with a rollback operation.
Figure 2-1. Database Operation Activity Methods The activity methods in Figure 2-1 can also be used by your applications to interact with tables in external databases. To use these methods with an external table, the appropriate class and property rules and data objects must exist. Use the Create External Data Table Rules Wizard to generate these items. For more information, see the Application Developer Help system. Process Commander also provides activity methods that invoke SQL connector rules, which interact with external databases: RDB-Save and RDB-Delete. You use SQL connector rules for stored procedures and for SQL queries that include joins or are more complex than simple read/write interactions. For more information, see the Application Developer Help system.
Managing Commits and Rollbacks in Custom Activities

While commits occur automatically for work objects during normal flow processing, you must write activities that manage commits and rollbacks for items that are not work objects. Additionally, sometimes the design of your application may require you to configure the commit operation for a work object for example, perhaps you need to create a button or a custom widget that creates (saves) a work object. In activities that commit objects that are not work objects, use the activity methods described in Figure 2-1. In activities that commit work objects, call the standard activity Work.commitWithErrorHandling rather than the Commit and Rollback methods.
17
Generally speaking, activities that commit objects use the following pattern: 1. Commit the deferred operations list. 2. Evaluate the results of the commit step. 3. If the commit failed: Report errors to the clipboard page and to the Pega log. Roll back the operations.
Steps 3 through 6 of the standard activity Work-.commitWithErrorHandling, shown in Figure 2-2, illustrate the items on the preceding list.
Figure 2-2. Example of Commit and Rollback Steps
Evaluating the Results of the Commit Method

After activity methods run, they set the value of a property named pxMethodStatus with a status message that indicates whether the method succeeded. The pxMethodStatus property is located on the pxThread page in the clipboard. Whenever you create an activity that performs a database operation (save, delete, commit, rollback), configure the activity to use a transition in that step or a precondition in the following step to determine whether the database operation succeeded before continuing to the next step. A standard when rule (Rule-Obj-When) named StepStatusFail checks the value of the pxMethodStatus property. If the property has a value that begins with the word Fail, the When rule returns a value of true. Use the StepStatusFail rule to evaluate the results of database operations and then configure activities to respond in a meaningful way if an operation failed: roll back the deferred
18
operations list, display an error message, route a failed work object to a special work basket, and so on.
Note: A similarly named When rule, StepStatusGood, checks the value of the
pxMethodStatus property and returns a value of true if the value of the property begins with the word Good. That is, StepStatusGood returns a false value if the value of pxMethodStatus contains either a warning or a failure message. Use the StepStatusGood rule for evaluating whether an operation failed only if your application defines both warnings and failures as failures. If you do not consider warnings to be failures, use the StepStatusFail rule to determine whether an operation failed. The Commit step in the Work-.commitWithErrorHandling activity (Figure 2-2) evaluates two transitions before moving to the next step. The first transition uses the StepStatusFail rule to determine whether the step successfully committed the operations. If the Commit step succeeded, the activity continues to the second transition.
Reporting Errors
The Work-.commitWithErrorHandling activity also illustrates how to report errors when a commit operation fails. Step 4 uses the Page-Set-Messages activity method to write a message to the primary page of the activity. Following is the statement in the Message parameter: "Validate-SaveFailed-CommitError\t" + @getWorstMessage(tools) getWorstMessage is a utility function that extracts the value of the pxMethodStatus property. Step 5 uses a Java step to write the error message to the Pega log file. Following in the Java code in that step: oLog.fatal(myStepPage.getMessagesAll());
Note: For information about the log files, see PegaRULES Process
Commander Administration and Security, which is available on the PDN.
19
Managing a Rollback
If the Commit step in the commitWithErrorHandling activity fails that is, the StepStatusFail rule evaluates to true the activity continues. It writes a page message in step 4 and a message to the Pega log file in step 5. Then, in step 6, the commitWithErrorHandling activity invokes the Rollback method to roll back the operations that were attempted by the Commit method.
20
Process Commander Commits and Distributed Transactions

A transaction is a set of related operations that appear to execute as one operation for the purpose of ensuring data integrity. All the related operations must succeed, or none of them should. For example, when you transfer money from your savings account to your checking account, it is likely that there are two operations involved: 1) a withdrawal from savings and 2) a deposit to checking. If the deposit operation fails, the withdrawal operation must also fail or you would lose money. During flow and other processing, database operations are usually deferred and do not actually take place until the commit operation executes. At that point, all the deferred save operations must succeed for the commit to succeed. If any of the deferred save operations fail, the commit operation will end in a rollback and none of the operations succeed, which ensures data integrity. However, what if the database operations manipulate data in different databases? Perhaps on commit, new customer information is saved in one database and the work object is saved in a different database. What happens at this point depends on how Process Commander is deployed. Starting in version 5.1 SP1, when Process Commander is deployed as an enterprise application and your system is configured to use a JDBC driver with XA support, your Process Commander applications can participate in distributed transactions. In this case, when the Process Commander commit is issued, two write operations occur within the same transaction. If one fails, both are rolled back. If your Process Commander system is deployed as a web application or as an enterprise application that uses non-XA JDBC drivers, it does not participate in distributed transactions. That is, commits are not transactions, they are database operations. In this case, when the Process Commander commit is issued, two separate JDBC connections are opened for two separate database transactions. It is possible for one write operation to succeed and the other to fail. This means that if your applications need to participate in distributed transactions, Process Commander must be deployed as an enterprise application and must use a JDBC driver with XA support. When deployed as an enterprise application, transactions can be managed either by Process Commander (bean-managed) or by a J2EE application server (container-managed). By default, Process Commanders transactional mode is
21
set to bean-managed. However, when an external application sends a request to one of Process Commanders transaction-aware service rule types (EJB, Java, or JMS), Process Commander can participate in container-managed distributed transactions. Note the following: If your application objects are contained in the PegaRULES database only that is, all the operations on a deferred operations list are written to the same database your application does not require the ability to participate in distributed transactions and there is no need for your Process Commander system to use database drivers with XA support. If your application does need to participate in a distributed transaction a two-phased commit, for example the transaction should be bean-managed by Process Commander, which is the default state of your Process Commander system.
For more information about bean-managed and container managed transactions, see Distributed Transactions and PegaRULES Process Commander, which is available on the PDN.
22
Chapter 3 Object Locking

If you used the Application Accelerator to start building your Process Commander application, object locking is enabled by default on your generated work object types and covers. However, if you create your class groups and work objects manually, you must manually configure the Lock option for the class group. Additionally, if you determine that there are other, non-work objects that must be saved to the database, you manually configure the Lock option for those class rules (even if they were generated by the Application Accelerator). This chapter describes how object locking works in more detail how lock strings are created, the lifespan of a lock, and so on and how you enable locking for work object types that were not generated by the Application Accelerator and for non-work objects that are saved by your applications.
23
About Object Locking

Object locking marks data as in use. When a user attempts to open an item for editing, Process Commander checks to see if there is already a lock on that item. If a lock exists, the user sees a message stating that the item is locked by another user. If a lock does not already exist, Process Commander creates an object lock and grants access to the item. The item is now locked until either a) the user finishes his or her work and saves the item, which (typically) releases the lock, or b) the lock expires.
Lock Keys and Lock Strings

When Process Commander creates an object lock, it generates a lock string that provides a key to the object. Process Commander then writes the string plus other information (including the requestor ID and the operator ID of the user) to a new row in the pr_sys_locks table. When a requestor attempts to open and lock an object, Process Commander first examines the lock strings in the table to determine whether the object is available. If the object is already locked, the requestors attempt to open it fails. When an object lock is released, the row holding the lock string is cleared from the database and the object becomes available for locking by another requestor.
Lock Keys
The lock string of an object is determined by its lock keys. Typically, the objects lock keys are the same as the objects keys which is the value of the objects pzInsKey property. However, the design of your application might call for locking more than one class instance with a single key. As long as the classes have a common property, you could define that property as the lock key for each class (or classgroup). For example, you might design a flow in which work objects belong to a folder and only one work object from a folder can be worked on at a time. In this case, you could create a property named something like FolderKey, design the application such that the ID of the folder they belong to is stored in the FolderKey property of the work objects, and then specify the FolderKey property as the property to use as the lock key in the class groups of all the work objects that could belong to the folder.
24
Lock Strings
Lock strings are determined as follows: If lock keys are specified, the lock string includes the values of the properties identified by the lock keys in the order in which they are listed on the Locking tab of the class or class group. When lock keys are not specified, Process Commander uses the object keys as the lock keys.
The object keys are different, depending on whether the class belongs to a classgroup or not: For an object that is within the scope of a class group, the lock string is the name of the class group concatenated with the values of the properties specified as object keys on the Keys tab of the Class Group form. For example, the object key specified for the PegaSample class group in the PegaProCom RuleSet is pyID. Therefore, the lock string of a work object that belongs to the PegaSample class group would be something like PegaSample W-113. For objects that belong to classes not associated with a class group (objects that are not work objects), the lock string is the name of the class concatenated with the values of the properties specified as object keys on the Basics tab of the Class form. For example, for a class named Employee-Data with an object key of a property that holds a numeric employee ID, the lock string of an EmployeeData object would be something like Employee-Data 123456.
Lock Lifespan
Object locks have a timeout interval that is set to 120 minutes by default. When an object lock reaches the timeout threshold, the lock is not automatically released. Instead, the row in the pr_sys_locks table is updated to indicate that the current lock is expired. If a new users requestor attempts to obtain a new lock on an object with an expired lock, the new requestor takes the object lock from the old requestor. If the original user returns to the object and attempts to save it, the save fails because the users requestor no longer has an object lock on the instance. Note that an expired lock also called a soft lock. You can change the value of the lock timeout by editing the system definition data object. From the Rules by Type explorer, select SysAdmin > System. Open your system definition and specify a new value in the Lock Timeout field.
25
How Locking is Enabled

For work objects, object locking is configured on the Locks tab of the classgroup the work object belongs to; for other objects data that must be saved separately from a work object, for example the object locking is configured on the Locks tab on the class rule that defines the object. If you used the Application Accelerator to start building your Process Commander application, object locking is enabled by default on the generated class groups and cover objects. As mentioned, if you create your class groups and work objects manually, you must manually configure the Lock option for the class group. Additionally, if you determine that there are other, non-work objects that must be saved to the database, you must manually configure the Lock option for those class rules (even if they were generated by the Application Accelerator).
External Classes
You can enable object locking on classes that were generated by the External Data Table Wizard classes that represent tables in an external database. However, obtaining an object lock on an object that is stored in an external class prevents only those updates made by other requestors in the Process Commander system. It does not prevent changes being made to that object by other systems.
How Locking is Implemented

In simple flows that use standard rules to interact with one work object and do not spin off work or make changes to an object other than the main work object, object locking is automatically managed and you do not have to configure additional processing. However, if a flow updates a value in another work object or opens another work object, for example, you must configure your activities to manage object locking appropriately. When your custom activity needs to open another work object, use one of the standard activities Work-.AcquireWorkObject and Assign.AcquireWorkObject to open it. When your custom activity needs to open a non-work objects, use the activity methods Obj-Open or Obj-Open-by-Handle and select the Lock parameter, or use the method Obj-Refresh-and-Lock to open the object.
For information about these activities and methods, see Chapter 4: Application Processing that Obtains Object Locks, which starts on page 32.
26
Locking and Permissions

As described in the security chapter in the PegaRULES Process Commander Administration and Security guide, users need access rights in order to work with Process Commander applications. Users cannot obtain lock on objects unless their access roles grant them modification privileges to objects from that class. If a user has read privileges but does not have modify privileges on the class of an object that he or she attempts to open and lock, the lock attempt fails and the object is opened in read-only mode.
Database Isolation Levels

Verify with your database administrators that they have configured the database isolation levels for the Process Commander database to enforce repeatable reads. When a record is saved, but not yet committed, it should not be able to be read. Objects should not exist as reportable entities until they have been committed.
27
Enabling Object Locking Manually

This section describes how to enable object locking on work object types that you created manually (that is, without using the Application Accelerator) and on nonwork objects that your applications save. Additionally, if you need to customize the lock keys for your objects, you should follow the instructions in this section. If you do not need to manually enable locking or to modify lock strings, skip the rest of this section and continue with Customize Object Locking for Cover Objects on page 31.
Before You Begin

Before you begin manually enabling locking or modifying lock strings for generated work objects, you must design your locking strategy.
Determine Object Scope

When you use the Application Accelerator, object locking is automatically enabled for work and cover objects. However, many objects are not completely defined by a single class rule. During the design phase of your applications, determine the scope of your work objects. Are there data objects that need to be saved separately? Determine whether additional classes need object locking enabled. For an example, consider the sample application provided for the SOAP connector sample, Manage Credit Applications. It is available from the Integration Services section of the Pega Developer Network (PDN), located here: http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp The work object for this application has an embedded page property that holds a credit report, which is an object obtained from a sample Web service with the sample SOAP connector. Object locking is enabled on the sample work objects class group and a credit report that is saved as part of the work object is locked when the work object it belongs to is locked. However, if you also wanted to save the credit report as a separate object, you would also need to enable locking on the top-level class that represents the credit report ConnectSamples-DataSOAP-CreditReportType Determine whether your applications create or obtain non-work objects that are saved separately from work objects, and decide whether these classes should also be locked.
28
Determine Locking Groups

A locking group is a set of objects that should be locked together when one of the objects in the group is locked. If you determine that you need to set up locking groups, note the following: Each class group or class can be in one locking group only. That is, you cannot include the same class or class group in more than locking group even if you use different lock keys to identify the group. When configuring a lock key based on a property common to multiple classes, each class that could be locked by that property must have locking enabled.
Determine Lock Keys

As mentioned, a lock string is generated and stored in the database when an object is locked. Typically, an objects key(s) are used as the lock key part of the lock string. In the typical case, you leave the Lock Name field blank, and Process Commander uses the object keys specified on the Keys tab of the class group or the Basic tab of the class as the lock key. (That is, the value of the objects pzInsKey property.) If you determine that you need to use a different set of keys for the lock key than are used as the object key, use the Lock Name field to provide the keys for the lock string. For example, perhaps you want to set up a locking strategy in which one lock would lock several items, as in the work object and folder example described in the Lock Keys and Lock Strings section on page 23. In such a case, you determine a common property that creates the relationship between the classes (the locking property) and specify it as the Lock Name on the Locks tab of the class group and/or the individual classes. Note the following: If you use a custom property as a lock key, be sure to use a property whose value never changes. If you use a property whose value can be changed by activity processing or user input, when the value is changed, the lock is invalid. If you determine that you need to specify more than one lock key property, be sure to specify all of them and in the same order in all the classes or class groups that are part of the locking group.
29
Configure Locking for Class Groups and Classes

Locking is configured differently for work objects than it is for other objects: For work objects, you enable locking on the class group not the class groups class, but the Data-Admin-ClassGroup instance. For objects that do not belong to a class group items that are not work objects you enable locking on the class (the Rule-Obj-Class instance).
Class Groups (Work Objects)

If you created your work object classes manually, or, you want to use something other than the object keys as the lock keys, configure locking in the classgroup. 1. From the Rules by Type explorer, select SysAdmin > Class Group. 2. Select the class group from the list. 3. In the Class Group form, select the Locks tab. Figure 3-1 shows the Locks tab of the class group from the sample application for the SOAP connector sample.
Figure 3-1. Locks Tab of ConnectSamples-SampleWork Class Group 4. Select the Allow Locking? field. 5. Optional. If you want the lock key for the work objects that belong to this class group to be something other than the key(s) to the class group, specify the property or properties to use in the Lock Name column. Always leave the Lock Caption value blank.
Other (non-work) Objects

For non-work object classes, configure locking for the class rule. 1. Use the Class Explorer to open the class of the object. 2. In the Class form, select the Locks tab. 3. Select the Allow Locking? field.
30
4. Optional. If you want the lock string for the objects that belong to this class to use properties other than the key(s) to the object, specify the properties to use as the lock keys in the Lock Name column. Always leave the Lock Caption value blank.
31
Customize Object Locking for Cover Objects

Cover objects typically contain more than one work object. When a work object that belongs to a cover is open, the cover is also open. By default, Process Commander always locks the cover when a work object is opened, which means that by default only one user can work on a cover at a time. If your application design needs are such that it must be possible for more than one user to be able to work on the items in the same cover, override the default locking behavior for covers and then use the Obj-Refresh-and-Lock activity method when an activity needs to lock the cover. (See Using the Obj-Refreshand-Lock Method on page 39 for information.) To override the default locking behavior, complete the following steps: 1. Locate the activity named Work-.DetermineLockString. 2. Copy the activity (using Save As) as follows: Select the appropriate RuleSet the one that contains the cover object class whose object locking you want to change. Set the Applies To class of the activity to that of the class group the work objects in the cover belong to.
3. Edit the Property-Set step so that it does not include the cover in value of the pxLockHandle property. That is, change the default value (.pxCoverInsKey == "" ? .pzInsKey : .pxCoverInsKey) to just pzInsKey as shown in Figure 3-2.
Figure 3-2. Setting pxLockHandle in the DetermineLockString Activity After you complete these steps, the lock on a work object does not also lock its cover.
32
Chapter 4 Application Processing that Obtains Object Locks

In simple flows that use standard rules to interact with one work object and do not spin off work or make changes to an object other than the main work object, object locking is automatically managed and you do not have to configure additional processing. When a work object is first created, the lock is obtained. The lock is released when the work object is routed to the next assignment. When a user opens the next assignment, flow processing automatically obtains the lock when it opens the work object. However, if a flow updates a value in another work object or opens another work object, for example, you must manage the object locking appropriately in the activities that provide the processing. This chapter describes how to configure your custom processing to obtain and release object locks as appropriate, gracefully manage errors when an object lock already exists or when commit operations fail, and so on.
33
Obtaining Locks for Work Objects

When your activities need to open work objects other than the one that is being operated on by the current flow, or, you are creating service activities that begin processing in response to a message from an external source, use the standard activities Work-.acquireWorkObject and Assign-.acquireWorkObject The acquireWorkObject activities obtain object locks, handle work pages, assignment pages, cover pages, output pages, and so on, and provide error reporting and other kinds of processing. Which of the acquireWorkObject activities you use depends on the information that is available at the point when the application needs to open the work object (Figure 4-1).
If the activity you are creating Has access to the pzInsKey of the work object Does not have access to the pzInsKey of the work object but does have access to the assignment
Then use Work-.AcquireWorkObject Assign-.AcquireWorkObject
Figure 4-1. When to use each acquireWorkObject activity
Assign-.acquireWorkObject Activity
The Assign-.acquireWorkObject activity (Figure 4-2) checks for an existing output page and clears it if it finds one, opens the assignment page, locates the work object handle (pzInsKey), then calls and passes the handle to an internal activity that opens the work object and acquires an object lock. It also writes any errors to a page called pyOutput.
34
Figure 4-2. Assign-.acquireWorkObject For an example of how to use the Assign-.acquireWorkObject activity, locate and open the standard activity Assign-.ProcessAssignment. Figure 4-3 shows the first two steps in the ProcessAssignment activity.
Figure 4-3. Calling Assign-.AcquireWorkObject from Assign-.ProcessAssignment Step 1 uses Property-Set to set values for the activity parameters that it needs to use when it calls the Assign-.acquireWorkObject activity in step 2.
35
Work-.acquireWorkObject Activity
The Work-.acquireWorkObject activity (Figure 4-4) opens the specified work object on the specified work page, obtains a work object lock on it, writes any provided property values to the work page, and then removes the primary page. It also writes any errors to a page called pyOutput.
Figure 4-4. Work-.acquireWorkObject For an example of how to use the Work-.acquireWorkObject activity, locate and open the Work-.resumeWorkProcess activity. Figure 4-5 shows the first step in the resumeWorkProcess activity.
Figure 4-5 Calling Work-.AcquireWorkObject from Work-resumeWorkProcess.
36
The resumeWorkProcess activity is typically used as the service activity of services that deliver information for a work object from an external system. The external system passes in the pzInsKey of the work object, the flow to resume, and so on. The service passes that information to the resumeWorkProcess activity, which uses the Work-.acquireWorkObject activity to locate the work object and obtain a work object lock for it. You would also use this activity when a flow includes logic that updates information in a work object other than the current work object. For example, perhaps a customer order work object spins off an inventory tracking work object and the status of the inventory tracking work object should be changed when the customer order work object reaches a certain point in the flow. To open the related work object the inventory tracking object you would use the Work.acquireWorkObject activity.
Example: MergePage Parameter and Service Rules

A key feature of the Work-.acquireWorkObject activity is the MergePage parameter. When a service rule invokes the resumeWorkProcess activity, it is in response to a request from an external application. Presumably, the external application provides information that should be used to update an existing work object, but you dont want the service to map the data directly to the work page of that work object you want it to acquire an object lock first. In such a case you use the MergePage parameter to provide a place for the service to store the incoming data while it acquires the object lock. To configure a service that uses the MergePage parameter of the Work.acquireWorkObject activity rather than mapping data directly to the work page, configure the service as follows: 1. On the Service tab of the service rule: Specify a page other than pyWorkPage in the Page Name field; by convention this page is named ServicePage. Do not specify a model. Specify the resumeWorkProcess activity as the service activity.
2. On the tab that holds the Map To data mappings (typically the Request tab, but for some rules it is the Parameters tab), map the incoming data to the ServicePage page. When the resumeWorkProcess activity calls the Work-.acquireWorkObject activity, the function used to provide the value of the MergePage parameter references the ServicePage page. When the acquireWorkObject page reaches step 9, it merges the values from the ServicePage into the pyWorkPage page.
37
Obtaining Locks for Objects that are not Work Objects

When the object you need to open is not a work object, use the Obj-Open, ObjOpen-by-Handle, and Obj-Refresh-and-Lock methods in your activities. Remember that when you use these methods you are responsible for configuring the same kind of object locking and error reporting functionality that the acquireWorkObject activities provide.
Using the Obj-Open Method

Using the class and property-value pair provided by the activity, the Obj-Open method locates and opens the specified object. It is best practice to select both the Lock and the ReleaseOnCommit parameters when you use this method. That way, an object lock is obtained when the object is opened and the then lock is released when the changes made to the object are committed. This method also takes a parameter named LockInfoPage. You can name a page of class System-Locks that will hold the results of the attempt to lock the object. For information about using the information from a LockInfo page, see Reporting Locking Messages to Users on page 41. It is common to use the Obj-Open method in routing activities because routing activities open organizations, organization units, and divisions to determine the correct user for an assignment. For an example, locate and open the standard routing activity Work.ToOrgUnitManager. Figure 4-6 shows the first step in this activity, which routes work to the manager of the current user.
Figure 4-6. Using the Obj-Open Activity Method
38
Note: When using Obj-Open (or Obj-Open-by-Handle) to open a Process

Commander data object like an organization, do not select the Lock parameter. Locking is not enabled on those classes. Additionally, object locking is not enabled on Process Commander rule types. Locking for rules is provided through the Rule Maintenance feature. When the activity in Figure 4-6 runs, organization information for the current requestor/user is located on the pxRequestor page. In this step, the activity is able to use the values of pxRequestor.pxOrgUnit, pxRequestor.pxOrgDivision, and pxRequestor.pxOrganization to locate and open the organization unit of the current user.
Using the Obj-Open-by-Handle Method

Using the value specified in the InstanceHandle parameter, the Obj-Open-byHandle method locates and opens the specified object. The handle of an object is a unique key, in an internal format, assembled by Process Commander and stored in either the pzInsKey or the pxInsHandle property. Reports and lists (like work lists, for example) are generated by list rules (Rule-Obj-List). When a list rule runs, it displays a list of the objects that match the criteria specified in the rule it does not actually open these objects. Each object listed then has an embedded page of the class CodePega-List in the clipboard and on that page is the pxInsHandle property for that object. When an object is opened (rather than merely listed), its clipboard page contains the pxInsKey property for that object.
If the object you want to open has been opened or listed previously and a page with that objects pzInsKey or pxInsHandle value is still in the clipboard, your activity can use the Obj-Open-by-Handle method. To obtain the object handle of an item, you can use the function @getPrimaryPageInstanceHandle(). It is best practice to select both the Lock and the ReleaseOnCommit parameters when you use this method. It also takes a parameter named LockInfoPage that you can use to name a page of class System-Locks to hold information about object locks. For an example, open and examine the Assign-.acquireWorkObject activity. This activity uses a Java step to obtain the handle to the assignment from the primary page (the assignment page). The Java step copies the object handle to an activity parameter named assignmentHandle. Step 3 sets values for two more activity parameters, one of which is a page name for the assignment page. Figure 4-7 shows steps 4 and 5 of Assign-acquireWorkObject.
39
Figure 4-7. Using the Obj-Open-By-Handle Activity Method Step 4 checks to verify that step 2 did, in fact, put the handle to the assignment in the assignmentHandle parameter. Then Step 5 uses the Obj-Open-By-Handle activity method to open the assignment.
Using the Obj-Refresh-and-Lock Method

There may be times when your application opens an object without locking it because at that point in the processing, there is no intent to change the object. If at any point after the object is opened, the intent of the processing changes and modifications will be made to the unlocked object, use the Obj-Refresh-and-Lock method to obtain the lock before updating the object. The Obj-Refresh-and-Lock method updates the object on the specified step page, ensuring that its contents are up-to-date, and then locks it. It is best practice to select the ReleaseOnCommit parameter so the lock is released when the object is committed. It is common to use the Obj-Refresh-and-Lock method with cover objects because when a covered work object is opened, its cover is automatically opened, too. If the design of your application requires that more than one user be allowed to work on the work objects in the same cover, you have configured your application so that the object lock on a work object does not also lock the cover object (see Customize Object Locking for Cover Objects on page 31). At the point where the application needs to update the cover object, use the ObjRefresh-and-Lock method to obtain a lock before updating it. For example, when a work object is resolved, the cover must be updated because it keeps track of the number of open work objects. Therefore, in the step before the activity updates the cover of a work object, use the Obj-Refresh-andLock activity method to obtain an object lock for the cover. For an example, locate and open the activity Work-.Resolve. Figure 4-8 shows steps 5 through 8 of Work-.Resolve.
40
Figure 4-8. Using the Obj-Refresh-And-Lock Activity Method Step 5 obtains a lock on the cover page and uses the LockInfoPage parameter to store any locking information that might be returned. Steps 6 and 7 manage errors. Step 8 updates the cover page, decreasing the number of open work objects by one.
41
Managing When Object Locks are Released

In most cases, object locks should be released when the object is committed. However, when configuring the processing for services, you may find that the service needs to hold the object lock until some later, specified time. Perhaps two services in the same service package write information to a work object in a specific sequence so you want the service requestor to hold the lock until the second service completes its write operation. When you need to manage when an object lock is released, use the following parameters and activity method: The ReleaseLockManually parameter for the acquireWorkObject activities; when selected, the object lock is retained after the object is committed The ReleaseOn Commit parameter for the Obj-Open, Obj-Open-by-Handle, and Obj-Refresh-and-Lock activity methods; when selected, the lock is released after the object is committed. If it is cleared, the lock is retained. The Page-Unlock activity method releases an object lock.
42
Reporting Locking Messages to Users

When users attempt to open an assignment from a workbasket or a shared work list, what message should they see if another user has already locked the work object or if it cannot be locked for some reason? Your activities can capture and report locking errors by using the following items: LockInfo pages named pages of the class System-Locks, which represents the information from the pr_sys_locks table. The LockInfo harness a standard harness that reports locking errors to the end user. Lock status messages the acquireWorkObject activities return a special set of lock status messages when they cannot obtain a lock on a work object or cover object.
When your activities detect locking errors, how you configure the activity to report the error depends on whether the processing is at a point where it can display the HTML from a harness rule. When the processing is at a point where it can display a harness, use the LockInfo page and the LockInfo harness to report the information to the user, as described in Using the LockInfo Harness on page 43. When the processing is at a point at which a harness rule cannot be displayed during the processing of a flow action, for example configure the activity to acquire the returned error message and set it on the objects page, as described in Capturing Lock Information and Setting it in a Page Message on page 44.
This section describes the LockInfo page, how to use the LockInfo harness, and how to manage locking errors when you cannot use the LockInfo harness, and provides a list of the lock status messages that can be returned from the acquireWorkObject activities.
About LockInfo Pages

When Process Commander attempts to obtain a lock on an object that already has a lock, it reports an error that identifies the requestor holding the lock. Typically, you want the application to report more information than that to the user requesting access to the locked item the name of the user rather than the requestor ID, for example. To do so, use a LockInfo page. The Obj-Open, Obj-Open-by-Handle, and Obj-Refresh-and-Lock activity methods all have a parameter named LockInfoPage. When specified, the activity creates a
43
named page of the class System-Locks, which represents the information from the pr_sys_locks table. You can see a LockInfo page with the Clipboard and the Tracer. It contains the following information: pxOwnerID the requestor ID of the requestor that holds the lock pxExpireDateTime the date and time the lock will expire pxUpdateOperator the operator ID of the user associated with the requestor that holds the lock pxLockHandle the lock string of the object
By convention, the LockInfo page is named LockInfo in all the standard Process Commander activities. It is best practice to name this page LockInfo in your activities, too.
Using the LockInfo Harness

The Work-.LockInfo harness is a standard harness that streams the values held on a LockInfo page back to the user who attempted to open an item that is already locked. If the user reported as the owner of the lock is the same as the user requesting the lock, a Release Lock button appears on the form. Note that in order to successfully display the LockInfo harness, a LockInfo page must exist on the clipboard when the harness is invoked. To use the Work-.LockInfo harness, configure your activity as follows: 1. In the activity step that attempts to acquire the work object, use one of the acquireWorkObject activities. If the design of your application requires the use of one of the Obj-Open activity methods instead, specify a value for the LockInfoPage parameter. By convention, name this page LockInfo. 2. In the step following the one that attempts to obtain the lock, evaluate the value of the pxMethodStatus property with the StepStatusFail rule. If StepStatusFail resolves to true, have the activity call the LockInfo harness and pass it the parameter page (which holds the name of the LockInfo page). 3. Alternately, you can override the standard LockInfo harness with one of your own. It must be named LockInfo and should incorporate the standard section rule System-Locks.LockInfo. For an example of how to use the LockInfo harness, locate and open the Assign.ProcessAssignment activity. Figure 4-9 shows steps 1-3 of this activity.
44
Figure 4-9. Call the LockInfo Harness The activity calls the Assign-.acquireWorkObject activity in step 2 to open and lock the work object. Step 3 uses preconditions to determine if the object lock was successful. If the work object was already locked, step 3 runs, branching off to the DisplayLockInfo activity, which then calls the LockInfo harness (Figure 4-10).
Figure 4-10. The Work-.LockInfo Harness The LockInfo harness displays the lock string, who the object is locked by, and when the lock will expire. If the person who has the lock is the same as the person requesting the lock now, he or she can use the Release Lock button to release the old lock and continue with the current processing.
Capturing Lock Information and Setting it in a Page Message

As mentioned, when the processing of your application is at a point at which a harness rule cannot be used to display locking errors during the processing of a flow action, for example configure the activity to acquire the returned error message and set it on the objects page. For an example, locate and open the activity Work-.ActionAddToCover. Figure 4-11 shows steps 3 and 4 from the Work-.ActionAddToCover activity.
45
Figure 4-11.Managing Lock Errors Step 3 uses the Obj-Refresh-And-Lock activity method to obtain an object lock on a cover. (It sets the value the LockInfoPage parameter to LockInfo.) Step 4 uses a precondition to check the value of the pxMethodStatus property with the When rule named StepStatusFail. If StepStatusFail resolves to true, the activity continues to the next condition, one that uses the function getWorstMessageName(tools) to determine whether the error message specifies that the object is already locked. Following is the statement from the second condition: @getWorstMessageName(tools) == "Database-LockFailure-LockHeldByAnother" If this condition resolves to true at runtime, the step uses the Page-SetMessages activity method to set the following message specified in the Message parameter: "Flow_CoverLockFail\t" + pyWorkCover.pyID + "\t" + LockInfo.pxUpdateOpName If this message is triggered at runtime, the message states that the cover lock failed, provides the ID of the cover, and provides the name of the operator who currently has the lock. This information is available because the Obj-RefreshAnd-Lock method set LockInfo as the name of the LockInfo page. Then, as specified by the transition at the end of Step 4, the activity exits, returning control to the calling process.
46
Lock Status Messages

The acquireWorkObject activities call other, internal Process Commander activities that return status information in two properties: SuccessIndicator, which holds a number, and FailureInfo, which holds the description of the error. In a step after the object lock is attempted, the acquireWorkObject activities check the value of the SucessIndicator parameter. If the value of SuccessIndicator is less than 0, it means there was a problem. The acquireWorkObject activity then saves the message in a page message on the primary page. Therefore, in an activity that calls one of the acquireWorkObject activities, you can configure the activity to display any lock messages that are returned. Figure 4-12 lists the possible error messages and describes them.
Success Indicator 0 -1 -2 -3
FailureInfo No errors Work object not found. Work object open access denied Work objects lock held by another Work object modify access denied (lock fail)
Description The object was successfully locked. The work object doesnt exist it couldnt be found. The operator does not have the access rights needed to open the work object. The work object is already locked.
-4
The operator does not have the access rights needed to modify the work object, so a lock was not granted. The object is opened in a read-only state. The cover doesnt exist it couldnt be located. The operator does not have the access rights needed to open the cover. The cover is already locked. The operator does not have the access rights needed to modify the cover so a lock was not granted. The cover object is opened in a read-only state. The object is not a cover or a work object
-5 -6 -7 -8
Cover object not found Cover object open access denied Cover objects lock held by another. Cover object modify access denied (lock fail)
-9
Lockstring fail
47
Success Indicator -10 -21
FailureInfo
Description and it is already locked.
Miscellaneous database failure Corresponding flow on work object is at different task
The object lock cant be obtained because something is wrong with the database. At this point during runtime, the assignment identified on the assignment page does not match that identified on the work objects flow page. This error indicates there is a problem in the flow rule configuration. At this point during runtime, the flow that the assignment page refers to no longer exists for the work object. This error also indicates a configuration problem with the flow. At this point during runtime, the work page has an outdated assignment handle. This can happen when developers create an activity that transfer an assignment from a work list to a workbasket, but the activity does not then update the work objects flow page. Someone deleted the flow rule while this work object was still in process. Someone deleted an assignment shape from the flow rule while this work object was still in process.
-22
Corresponding flow on work object no longer exists
-23
Work object points to a different assignment
-24 -25
Rule-Obj-Flow no longer exists Rule-Obj-Flow exists, but the assignment shape has been deleted
Figure 4-12. Object Lock Error Messages
48
Troubleshooting and Testing

Use the following troubleshooting tools to uncover issues with locking or commits when you are testing your applications.
DeferredOps HTML rule

When you do not understand the results of a save or a commit operation, start by examining the list of operations that are waiting to be written. To see the current list of deferred operations, insert a step before the point at which the commit will happen either through a Commit method or when flow processing idles and call the HTML rule @baseclass.DeferredOps. This rule displays the list of operations that will be written when the commit occurs.
Tracer
You can select object locking as an event to show in the Tracer. When you select the Locking option, event types of Acquired Lock and Release Lock appear in the event list. Examine these messages to determine whether a lock was needed but wasnt acquired or, perhaps, that a lock is being released before it should.
System Locks Report

The System Locks report displays a list of all the object locks that are currently held. From the menu, select View > System > Locks. The report shows the lock string of the object (called the object handle), the requestor that has the lock, and the time of the lock. To determine the identity of the user associated with a requestor, use the System Management Application.

Designing Applications That Ensure Data Integrity Full Guide

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Designing Applications That Ensure Data Integrity Full Guide

Diunggah oleh

Hak Cipta:

Format Tersedia

Designing Applications that Ensure Data Integrity PegaRULES Process Commander Versions v5.1 and 5.

Copyright 2007 Pegasystems Inc., Cambridge, MA

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Chapter 1 About this Document

Designing Applications that Ensure Data Integrity

Who Should Read This Document

Designing Applications that Ensure Data Integrity

Term Database locking

Lock string Deferred operations list

Designing Applications that Ensure Data Integrity

Term Server interaction

Designing Applications that Ensure Data Integrity

Figure 1-1. Definitions of Terms

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

The Pega Developer Network (PDN)

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Overview of Object Locking

Designing Applications that Ensure Data Integrity

Process Commander and Database Operations

When Commits Occur Programmatically

Designing Applications that Ensure Data Integrity

Note: If an activity calls the Flow-New method, Process Commander does a

Activity Methods that Cause Database Operations

Activity Method Obj-Save

Designing Applications that Ensure Data Integrity

Managing Commits and Rollbacks in Custom Activities

Designing Applications that Ensure Data Integrity

Figure 2-2. Example of Commit and Rollback Steps

Evaluating the Results of the Commit Method

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Process Commander Commits and Distributed Transactions

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Chapter 3 Object Locking

Designing Applications that Ensure Data Integrity

About Object Locking

Lock Keys and Lock Strings

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

How Locking is Enabled

How Locking is Implemented

Designing Applications that Ensure Data Integrity

Locking and Permissions

Database Isolation Levels

Designing Applications that Ensure Data Integrity

Enabling Object Locking Manually

Before You Begin

Determine Object Scope

Designing Applications that Ensure Data Integrity

Determine Locking Groups

Determine Lock Keys

Designing Applications that Ensure Data Integrity

Configure Locking for Class Groups and Classes

Class Groups (Work Objects)

Other (non-work) Objects

Designing Applications that Ensure Data Integrity

Designing Applications that Ensure Data Integrity

Customize Object Locking for Cover Objects