Managing Work Parties in Pega

What is a Work Party?

In Pega work parties represent the people, organizations and operators which are involved in progressing a case towards resolution or have an interest in that particular case instance. These people can be your employees, external parties or the customers themselves. Employees usually have an operator account which grants access to the system directly.

How do these parties relate to one another and what does Pega offer out of the box in their data model? Let´s revisit Pega´s definition of a work party and then provide a simple UML class diagram for the Data-Party classes with their most widely used properties and take it from there.

A work party represents a person, business, or organization that is involved in a case. A work party receives correspondence, such as email, and can be an active or passive participant based on its role.

These so-called work parties are shown in the browser interface as Participants panel on the lower right-side of the screen.

Party Class Structure

PRPC provides several work party classes out-of-the-box as shown in this diagram. While Pega differentiates among four non-operator categories for Companies, Governments, Organizations and Persons, all standard properties are modeled as part of the generalized Data-Party class for reuse; except for .pyPosition which extends Data-Party-Operator with the position some Operator holds within the organization.

The data model of Data-Party contains several more standard properties than depicted in the above diagram. For example this class defines a pyAddresses page group for categorized email and phone details and also has many properties for other types of Home and Work [Office] related contact information. While it´s wise to reuse those existing fields given all of the default sections, there are certainly scenarios where you might want to override and extend the Data-Address class or even write your own.

Note the distinction between operators (which do actually log onto the system) versus the other party classes. Also important is the relation of those operators to the access control model...

TIP: Do not add properties for the sake of translating those fields, but rather use the platforms localization tool instead. This way you won´t break Pega´s standard activities and other logic.

Default Roles

In Pega, each case type holds a list of valid party classes with some associated role. These party roles represent the type of stakeholders, such as Owner or Customer, participating in managing the case. The role is mostly a hint of how the party is supposed to interact with the case at hand; although case Owner has special meaning. Just make sure you always configure the rule Process > Work Parties > pyCaseManagementDefault similar to the following example. You can specify a role to be Required and Visible On Entry (VOE) which means it will be available at run-time for new case instances. You can also make any of the roles repeatable so multiple parties of the specified role can co-exist within the pyWorkParty page list. Do mind the pxSubscript naming convention and logic of Pega.

Managing Participants on a Case

As mentioned before party related rules include many Sections and Activities. Leverage those rather than rebuilding from scratch. A simple Trace will tell you what to look for... The important activities for programmatically adding or removing parties are:

• addWorkObjectParty
• removeWorkObjectParty (although not exposed by Public API)

For adding a party to the current case you either construct a pass a partyPage to the function or alternatively set the role class and model input parameters. The function will then return the actual PartyIDUsed. The removal function uses just PartyRole as input parameter, so take special action when the role is repeatable.

Tracing a Party upon New Case

Upon starting a new case instance the following activities get executed based on the settings in the rule named pyCaseManagementDefaults:

1. For each “valid party” defined as required or has VOE enabled (.pyPartyRoleVisibleOnEntry) a call to Work- PartyNewSetup is made with step page pyROWork.pyWorkPartyDef(#) where # corresponds to the line number in this list.
2. This activity creates up the new party page including role, class and prompt as well as label and then applies its "Data transform” i.e. CurrentOperator, NewParty of custom class model.
3. Next, due to the changing party page properties the WorkPartyRetrieve kicks in and will fill the Data-Admin-Operator-ID properties when the page has an associated user account given .pyUserIdentifier. It does so by branching on GetOperatorIDFromClipboard. Copied account properties include: user name and identifier, full name, work phone, position, email address as default and role. Note: Originator and Owner are reserved subscripts for which Organisation, Division, Unit and UserID are copied to the party page as well.
4. Finally the Data-Party gets validates and saved.

Tracing a Party upon Managing Participant

For existing cases clicking the “Manage” link for Participant will execute the following:

1. Work- pyUpdateWorkPartiesBefore
   
   When you select a role you would typically see:


2. pyGetWorkPartyOptions to populate the dropdown with parties (label/role/subscript?)
3. Work- AddWorkParty will effectively append a row to the list by calling PartyCreate. This activity just creates a new party given a party role.
4. Work- addWorkObjectParty will actually add the party to the current case.

Submitting the modal form will call Work- pyUpdateWorkPartiesAfter to effectuate the changes.

In conclusion, for non-Operators it is important to set the expected party properties yourself. Many sections such as “pyMiniPartyDetails” and “pyNewWorkPartyDetailRepeat” depend on having values for either .pyLabel and .pyPartyLabel or .pyFullName and .pyPartyRole. This holds for .pyFirstName and .pyLastName as well.

For example, you can define change event handlers on the appropriate controls to update the full name given first and last name by having it apply a data transform. Or one could hide the full name altogether and set a declare expression instead.

TIP: For adding existing operators you can leverage .pyWorkPartyUri=Param.OperatorID and .pxPartyRole=Param.PartyRole as Data transform which are special parameter that are in scope.

[Edgar] (7/9/2017 2:15:21 PM)