K2 blackpearl Roles and Advanced Destination Rules

K2 blackpearl Roles and Advanced Destination Rules

USING BLACKPEARL TO PLAN ACTIVITIES AND DYNAMICALLY RESOLVE USERS

Originally published January 7th, 2008

Updated April 4th, October 22

nd, 2008, January 26

th, 2009 and May 4

th, 2010

Updated September 17th 2010

Learn about dynamic roles and advanced destination planning with K2 blackpearl, including specific examples of

activity planning based on common business scenarios.

WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES

PAGE 2

INTRODUCTION

In K2 blackpearl, giving a user the ability to take action in a workflow is relatively simple. It is accomplished by

adding that user as a Destination for the activity. As a destination, the user is typically sent a notification and

the task is added to their worklist. Clicking on the task loads an action form, either an InfoPath form or an

ASP.NET form, containing the available actions. This simple scenario, however, does not reflect the real world

or the power of K2 blackpearl. With the introduction of advanced destination planning and roles, blackpearl

provides the flexibility needed for complex workflow processes to be built for dynamic business environments.

Note: For the most up-to-date information regarding the technologies and software supported by

K2, please see the Compatibility Matrix available at http://help.k2.com/en/blackpearlmatrix.aspx.

CONTENTS

INTRODUCTION ................................................................................................................................................. 2

CONTENTS ......................................................................................................................................................... 2

ROLES IN K2 BLACKPEARL .............................................................................................................................. 4

What makes up a Role? ................................................................................................................................ 4

Using a SmartObject Method in a Role ......................................................................................................... 5

Using XML as a Destination Set ................................................................................................................... 5

Synchronized vs. Cached Roles ................................................................................................................... 5

Dynamic Resolution of Role Membership ..................................................................................................... 5

Using Roles in a Process .............................................................................................................................. 6

TASK ALLOCATION, RIGHTS AND SECURITY ................................................................................................ 7

The Context Grid ........................................................................................................................................... 7

The Difference Between Delegation and Redirection of Tasks .................................................................... 8

ADVANCED DESTINATION RULES .................................................................................................................. 8

Plan per destination - All at once (Parallel planning) .................................................................................... 9

Plan per destination - One at a time (Serial planning) .................................................................................. 9

Plan per slot (no destinations) .................................................................................................................... 10

SCENARIO EXAMPLES ................................................................................................................................... 12

Plan just once Activities .............................................................................................................................. 12

Plan Per Destination - All at Once (Parallel) Activities ................................................................................ 14

Plan Per Destination - One at a time (Serial) Activities .............................................................................. 16

CONCLUSION ................................................................................................................................................... 17

APPENDIX ......................................................................................................................................................... 18

http://help.k2.com/en/blackpearlmatrix.aspx


PAGE 3

DEFINITIONS .................................................................................................................................................... 18

Activity ......................................................................................................................................................... 18

Event ........................................................................................................................................................... 18

Destination .................................................................................................................................................. 19

Line Instance ............................................................................................................................................... 19

Activity Instance .......................................................................................................................................... 19

Activity instance Destination ....................................................................................................................... 19

User Task .................................................................................................................................................... 19

Worklist Header ........................................................................................................................................... 19

Slot .............................................................................................................................................................. 20

Action .......................................................................................................................................................... 21

Event Instance and Event Succeeding Rule ............................................................................................... 21

Redirect ....................................................................................................................................................... 21

Delegate ...................................................................................................................................................... 21

SCENARIOS ...................................................................................................................................................... 22

Plan Options ................................................................................................................................................ 22

Destination Rule Options ............................................................................................................................ 26

Redirect Scenario ........................................................................................................................... 27

Delegate Scenario .......................................................................................................................... 27

Worklist Sharing .......................................................................................................................................... 28

Managed Users ........................................................................................................................................... 29

QUESTIONS ...................................................................................................................................................... 29


PAGE 4

ROLES IN K2 BLACKPEARL

To understand advanced destination planning, it is necessary to first understand how roles are built and used

in blackpearl. Much like groups or roles in other systems, such as Active Directory, roles in blackpearl are

groups of users.

WHAT MAKES UP A ROLE?

K2 roles are created in the Management Console of K2 Workspace. A new role is given a name and one or

more role items. These items can be based on the following entities:

Users or Groups from Active Directory or SQL

Result from SmartObject Methods

Users or Groups from custom user providers

In addition to specifying one the above items for each role item, each role item can be either included in or

excluded from the role. As illustrated in Figure 1, all users are included in the Role1 role except Mike.

SmartObject methods can also be included or excluded from the role.

[FIGURE 1: INCLUDING AND EXCLUDING USERS AND GROUPS.]

In addition to being able to specify users from Active Directory or SQL, K2 user providers written for other

systems can be used as the basis of a role item.

Notes:

Though beyond the scope of this article, the user providers currently written for K2 blackpearl

include Active Directory and SQL User Manager, but role providers for other systems may be

developed by third parties or released as enhancements to K2 blackpearl.

If familiar with destination queues in K2.net 2003, roles are very similar in concept and in

execution; however a role can include users from multiple sources.

Each individual role item is limited to one of the sources above, but a role may contain role items that are

based on any valid user entity. This means that a role can include or exclude users and groups from Active

Directory, SQL, a SmartObject query and another K2 role. The ability to span user providers and define roles


PAGE 5

with a SmartObject method, in addition to the ability to include or exclude role items from a role, makes K2

roles very powerful. It is recommended, however, that the establishment of roles for use in business

processes be carefully planned and executed, as a role's resultant membership may be difficult to determine if

many role items are present.

USING A SMARTOBJECT METHOD IN A ROLE

When a SmartObject contains properties that directly maps to users in one or more of the user providers

configured for the K2 server, a role can be configured for a method on that SmartObject. The method is

typically the GetList method which returns multiple records from the SmartObject. Each record should include

a username that corresponds to a username in the default user provider. The results of the SmartObject

method are stored like other role membership information and the refresh interval can be configured on a per-

process basis once the process using that role is deployed to the server.

USING XML AS A DESTINATION SET

User information contained in an XML structure, either as a process field or XML document outside of the

process, can be used as a basis of a destination set. It is important to remember, however, that users will only

be resolved by the K2 server if they are present in the default label, such as "K2." It is not possible to use an

XML structure as the basis for a role.

SYNCHRONIZED VS. CACHED ROLES

Default behavior: When an instance of an activity gets created and tasks are assigned, a single task will be

assigned to the role and any member of the role can action the task. Additionally, the role membership will be

resolved and cached at a configurable 10 minute interval. The default destination setting is Create a slot for

each role, which is available on one of the pages of the Destination Rules wizard in advanced mode.

Advanced behavior: The advanced Destination Rule options (see Advanced Destination Rules section in this

document) can be adjusted to assign a single tasks item to every individual member of a role (Resolve all

role to users), this happens only once and changes to roles will not be reflected. Optionally the role members

and their individual tasks can be kept in sync (Keep roles synchronized) and tasks will be removed or added

to each user’s task list based on their membership. Membership is resolved and cached at a configurable

interval, the default of which is 10 minutes.

Execution modes: How the role resolution behaves will be affected when using Plan just once or Plan per

destination - All at once or One at a time. Please see the Advanced Destination Rules section for more

details.

DYNAMIC RESOLUTION OF ROLE MEMBERSHIP

Depending on the solution requirement, it is sometimes necessary to use on-demand resolution of roles

instead of using an interval-based role resolution. Dynamic roles are on-demand and are refreshed when

dynamic roles are defined and every time worklists are opened which contain items that use the role. For

example, if a solution requires tasks to be assigned to users signing on at a certain location, a role can be

created to on-demand and dynamically resolve a user’s location and make the tasks visible to them. By


PAGE 6

default when multiple users open worklists containing items that use the role, the dynamic roles are only

resolved within a configurable three second window. When creating the role there is a Dynamic checkbox as

shown in Figure 1. Checking this box makes every call to the role a dynamic call, regardless of the process it

is used in. If the role is not dynamic, checking the Dynamic checkbox next to the Interval (minutes) text box

on the Role page of the process tree in the Management Console will force the role to resolve dynamically

instead of at the set interval, but only for the process in which is it used.

Notes:

A Dynamic Role can only be used with the Create a slot for each role option and the Plan

just once or Plan Per Destination - All at Once execution modes. Choosing the option for

resolving all roles to users will override a dynamic role as the users are resolved the first time

the activity is planned.

Dynamic roles were first introduced with K2 blackpearl Service Pack 1.

USING ROLES IN A PROCESS

As stated before, roles are created and managed in the Management Console of K2 Workspace. Once

created, roles are displayed in the Context Browser and the K2 Object Browser in the K2 Designer for Visual

Studio and the K2 Designer for Visio. Roles cannot be used in the K2 Web Designer. On the User Browser

tab, under Roles, each role available on the K2 server is listed, as shown in Figure 2.

[FIGURE 2: USING ROLES IN A PROCESS.]

When a role is added to a destination, the role is assigned rights to the slot that is created for the activity.

Each member of the role therefore has the same rights to the activity and the task associated with the event is

displayed on each member's worklist. Tasks will automatically appear or disappear from a user's worklist

based on their role membership. This is the default behavior of blackpearl when using roles and also applies if

using multiple individual destination users instead of a role. This is what happens for all default activities. The

plan for default activities is Plan just once, or simply Plan once. Other planning options will be covered in the

Advanced Destination Rules section. In a plan once process, when a member of the role actions the task, it is


PAGE 7

removed from everyone's worklist depending on the number of slots. If there is one slot configured and one

person actions the task, it is removed from everyone's worklist.

When a process that uses one or more roles is deployed, each role is displayed in the Management Console

under the process tree, as shown in Figure 3.

[FIGURE 3: THE ROLES PAGE IN THE PROCESS TREE IN THE MANAGEMENT CONSOLE.]

Alternatives for planning the activity, controlling the number of slots, and creating destination sets are

discussed in the next section.

TASK ALLOCATION, RIGHTS AND SECURITY

At runtime the K2 Server creates a single task item for every activity instance containing a client event, and

assigns default access rights to users or roles for that single task item. This allows the server to be able to

add or remove tasks to/from users and roles dynamically at runtime. The concept of slots are used to

determine when a task item (client event) is completed and can move on to the next activity based on the

outcome of a succeeding rule

The default actions and rights are defined at design time within the process definition. As a destination user,

all actions configured for the process are available by default. Once process instances are created, these

rights can be tailored in the Management Console. In addition, when a task is delegated, rights for each action

must be configured by the person delegating the task. This is useful, for example, when one of the possible

actions for an activity should not be completed by a delegated user. Actions that are not specifically granted

are not present when the delegated user opens the form.

THE CONTEXT GRID

To determine what rights a user has at runtime, K2 blackpearl uses a matrix of users, roles, processes and

activities, collectively called the Context Grid. This is an internal representation of what users can do at any

given time in a process. The Context Grid is not a graphical representation in any blackpearl user interface

(UI), but rather a concept that is used by blackpearl for rights and security. Many aspects of the Context Grid

are exposed through the Management Console in the K2 Workspace, such as assigning a user the right to

start a particular process.


PAGE 8

By using the Context Grid concept, user rights and the delegation, releasing and reassignment of tasks is

always up to date and dynamically controlled by the server.

THE DIFFERENCE BETWEEN DELEGATION AND REDIRECTION OF TASKS

When a task is delegated or redirected (reassigned), the user or role to which the delegation or redirected

occurs will receive the same rights as the person delegating or redirecting. The difference between delegation

and redirection is that the task will display on both user's worklist if it is delegated, while redirection will

remove the task from the user's worklist who performs the redirection. If the user is not available, the K2

administrator can redirect tasks using the Worklists page in Management Console.

ADVANCED DESTINATION RULES

The Plan once method of planning a destination rule was described as the default method of planning a

blackpearl activity. Figure 4 illustrates the first page of the advanced mode Destination Rule wizard,

containing the default and extra options for planning an activity.

[FIGURE 4: ADVANCED DESTINATION RULE PLANNING.]

When using the default plan once option, only one activity instance is created. Events are executed once.

Only one task item is created and rights assigned to the single task item. The activity instance will complete

when all slots are completed or when the succeeding rule is true. The activity instance will expire when the

succeeding rule is false. When using roles instead of individual users as the destination, task items are


PAGE 9

assigned to the role name rather than the individuals in the roles. This option and the number of slots can be

configured on the second page of the advanced Destination Rules wizard as shown in Figure 5 below.

PLAN PER DESTINATION - ALL AT ONCE (PARALLEL PLANNING)

This option works in the same manner as it did in K2.net 2003. The server creates one activity instance per

destination, and creates one task item per destination with the rights assigned to each destination for each

task item.

The options on the following page, as illustrated in Figure 5 below, are as follows:

Slot for each destination: Required slots auto adjust depending on the number of destinations resolved

when activity instance is executed at runtime

Specify number of slots: A fixed amount of slots are created. This overrides the activity setting.

Resolve roles: The role is resolved to its members during activity execution and an instance for each

member of the role is created. All events execute once for each member of the role.

Create slot for each role: Roles are not resolved and a single activity instance is created. The role

receives rights and all members of the role can access the task.

Keep roles synchronized: This option has no effect for parallel or serial plans and is discussed in the

section Synchronized vs. Cached Roles.

[FIGURE 5: PLANNING THE SLOTS AND ROLE RESOLUTION.]

PLAN PER DESTINATION - ONE AT A TIME (SERIAL PLANNING)

For the One at a time planning method, the server creates one activity instance per destination, but does so

in a serial fashion, one instance at a time, and in the order the destination sets were designed. When a role is


PAGE 10

used as a destination, instances are created in the order in which the role membership is returned from the

server query and there is no way to specify an order. If an order is required, do not use roles but rather

individual users instead, and specify the users in the desired order.

The server creates one task item per destination at a time, and assigns rights to each task item. The next

instance will be created only after the previous event is completed by the previous destination user. The

server will not evaluate a succeeding rule on the activity until all activity instances are completed.

Important: For both parallel and serial planning methods, if more slots than destinations are

specified, the activity cannot be completed without a custom succeeding rule, which requires code

in the rule. To avoid this, ensure that there are always at least as many destinations as there are

slots.

PLAN PER SLOT (NO DESTINATIONS)

The Plan per slot (no destination) method is reserved for server events based activities. As an example, this

could be used for a parent process to start a variable number of child processes using IPC events. In this

case, all configured destinations are ignored and the server creates one activity instance per slot. Activity data

can be initialized and used for each slot. This allows each slot to have its own instance of the activity data

fields.

In this method, the number of slots can be configured using activity or list data, which means that the number

of slots is equal to the number of nodes in the XML field that is mapped to this field. When the runtime activity

starts, the server decides how many instances of the IPC process, for example, need to be started.

Initialization data may contain any unique data that the IPC needs per child call. If a SmartObject GetList

method or repeating XML node is specified for the initialization data, the server retrieves the next value for

each slot, but only until it has reached the number of specified slots. Using the list field, the server creates a

slot for each item returned while at the same time using the property specified as the initialization data for the

new child process.

IPC Example Using XML Data

Using a repeating XML node or SmartObject GetList method, data is mapped to the target process in a

Process data field. The following example illustrates this.

Step 1. Create a repeating XML doc that looks something like the following.

<OrderXML>

<Order>Order1312</Order>





</OrderXML>


PAGE 11

Step 2. Create a process-level XML data field with the above schema (called IPCXML in this example).

[FIGURE 6: CREATING THE XML DATA FIELD.]

Step 3. Add a Default Activity to the design canvas and go to the Advanced Destination Rules.

[FIGURE 7: SPECIFYING ADVANCED MODE FOR THE DESTINATION RULE.]

Step 4. Select “Plan per slot (No Destinations)”

[FIGURE 8: SELECTING THE ACTIVITY PLAN FOR IPC PROCESSES.]

Step 5. Use the “Select a list field to determine how many slots should be created” option and point it to the

repeating node in your XML schema, and then finish the wizard. This option will repeat through the XML

schema and start a new IPC for each node entry. This data can be used as initialization data for the child

process

[FIGURE 9: SPECIFYING THE REPEATING XML NODE FOR ACTIVITY SLOT AND, IN TURN, NUMBER OF IPC PROCESSES TO CALL.]


PAGE 12

Step 6. Drop an IPC Event on the activity. On the Field Mapping page map a data field in your child process

to the ActivityInstanceDestInstanceData. K2 Server takes the repeating XML node’s value (at runtime it is

stored in the InstanceData) and copies it into the data field in the child process (in the example called "IData).

[FIGURE 10: MAPPING DATA FROM PARENT TO CHILD PROCESS.]

The parent process starts a new IPC process for every repeating node entry and passes the XML node value

to the data field in the child process. In this example it starts 5 child processes via IPC and each instance has

a process data field containing a unique order number.

SCENARIO EXAMPLES

In the following section, ten different plans and options are used to illustrate the outcomes that can be

achieved with K2 blackpearl plans and task assignments.

The following users and roles are used in the examples below:

Role1: Based on an Active Directory group called Team1, which contains three people.

Role2: Based on the Active Directory group called Team2, which contains three people.

PLAN JUST ONCE ACTIVITIES

The following three examples illustrate various combinations of single activities. Keep in mind that dynamic

roles can only be used with Plan just once activities or Plan Per Destination activities that do not resolve

roles to users. If membership in a role changes frequently, the role should be marked Dynamic and the Keep

roles synchronized option in the advanced Destination Rule wizard should be checked.

Example #1:

DESTINATION SET ROLE1, BOB

Create a slot for each destination FALSE


PAGE 13

DESTINATION SET ROLE1, BOB

Specified number of slots 2

Resolve all roles to users FALSE

Create a slot for each role TRUE

Slot(s) assigned to SingleUser and Role1

Total number of slots 2

Outcome This activity is actioned once by a single user and once by a

member of Role1

Example #2:

DESTINATION SET ROLE1, ROLE2

Create a slot for each destination TRUE

Specified number of slots N/A



Slot(s) assigned to Roles


Outcome

Worklist items remain for members of a role when someone in that

role has already actioned the task. If this is not desired, plan a

parallel (All at once) activity with the "Create a slot for each

destination" and "Create a slot for each role" options enabled.

Example #3:




Resolve all roles to users TRUE


PAGE 14

Create a slot for each role FALSE

Slot(s) assigned to Users


Outcome There will be as many slots created as there are users in the

roles.

PLAN PER DESTINATION - ALL AT ONCE (PARALLEL) ACTIVITIES

Parallel planning enables all users to get notifications at the same time and, when the number of slots is filled,

the availability of the task will disappear from the user's worklists who have not yet opened the task.

Example #4

DESTINATION SET ROLE1







Outcome This works the same as Plan just once with the option

Resolve all roles to users.

Example #5








PAGE 15


Outcome Once a person actions the task, all worklist items are

removed.

Example #6








Outcome The combination of Create a slot for each destination and

Resolve all roles to users creates a slot for each user.

Example #7








Outcome

This will create a slot for each role. Once a user from a role

actions the task, the worklist item for the other role members

is removed.


PAGE 16

PLAN PER DESTINATION - ONE AT A TIME (SERIAL) ACTIVITIES

Serial activities are useful when multiple destination users need to review or make comments to an item in a

sequential manner.

Example #8








Outcome

Each user is assigned a task after the previous user

completes it. Worklist items appear for one user at a time.

Changes to the role will not remove assigned tasks from a

users worklist.

Example #9








Outcome

Worklist items appear for each user in the first role. Once

one of those users actions the task, the users from the

second role see worklist items. When one person actions

the task from the second role, the activity is completed.

Example #10


PAGE 17

DESTINATION SET TEAM1, TEAM2 (ACTIVE DIRECTORY GROUPS)







Outcome

All users are assigned tasks. As soon as two tasks are

actioned, the others disappear (does not matter which

member of which team actioned it).

CONCLUSION

K2 blackpearl offers many powerful features to assign tasks to users and manage activities, including dynamic

role resolution based on Active Directory, SQL, SmartObjects and custom user providers. By using these

features of blackpearl, a wide range of scenarios for business process planning can be achieved.


PAGE 18

APPENDIX

There are a few key concepts that you need to understand when planning your activities. They are as follows:

Know what plan you need: Plan Just Once or Plan Per Destination. Server events will only execute

one time for Plan Just Once, but will usually execute more than once in Plan Per Destination.

Keep Roles and Groups in mind: When using K2 roles and AD groups, make sure you know when

you want tasks assigned to the role or group, and when you want tasks assigned to individual users.

This can become tricky when you need to limit slots and need to mix roles or groups with individual

users.

There are also some key rules to keep in mind when planning your activities.

1. The default plan is a Plan Just Once

2. At runtime, a Plan Per Destination activity has only one slot per destination.

3. The slots configuration at the activity level is the same as the slot configuration of an advanced

destination rule – changing one changes the other.

4. Worklist headers are not used for Plan Per Slot activities

5. A Plan Per Slot activity should not contain a client event

6. Slots are filled when a user opens a worklist item.

7. Resolving groups and roles to users is the same as assigning tasks to individual users, and only to

members of the group or role at the time the activity is planned. However, if you select the Create a

slot for each destination and Keep roles synchronized options, resolving roles and groups to

users can still be dynamic.

8. When you do NOT resolve groups and roles to users, the group or role is treated as a single user

and, depending on the activity plan, counts for one slot. If you have a mix of roles or groups and

individual users, you should calculate your necessary slots based on the number of entities. For

example, one role, one group, and three users equals five total slots. If you only need three people to

approve, those three approvals could be filled by the three individual users, one person each from the

role and the group plus one individual user, or one person from the role or group and two individuals.

DEFINITIONS

Understanding the terminology is necessary in order to understand how different planning options affect the

activity.

ACTIVITY

An Activity is a K2 construct that includes one or more events. There are many items configured at the

activity level, such as the name and description of the activity as well as several rules, including the Start

Rule, the Preceding Rule, the Destination Rule, the Succeeding Rule, and the Escalation Rule.

EVENT

An Event is contained within an activity and performs some type of action, such as copying a document,

calling a web service, manipulating XML data, for example. There are three types of events – Server, Client,

and IPC (inter-process communication). Server events execute synchronously without any interaction from a

user. Client events are planned and then the server waits for some user interaction. IPC events are used to

call other workflows, and can be executed synchronously or asynchronously.

Multiple events in the same activity execute in the order in which they appear in the activity, from top to

bottom.


PAGE 19

DESTINATION

A Destination is the target of a task (worklist item recipient) and is only used in client events. Destination is

an abstract definition for a User, Role or an AD Group.

LINE INSTANCE

A Line Instance is an instance of a Line Definition. There can be more than one instance for a line

definition. Each instance contains unique data or configuration based on the definition of the line.

ACTIVITY INSTANCE

An Activity Instance is an instance based on an Activity Definition. Many instances can exist for an activity.

Each instance contains unique data and configuration. An activity instance is created when a certain path is

followed in the process. The instance is created by a line instance and only when the line rule for that instance

has evaluated to true. The activity instance is responsible for the preceding rule, which determines if the

activity instance should start (true/false), the start rule, which determines when the activity instance starts

(date/time), and the destination rule. The destination rule has many options and settings, such as plan option,

slot configuration, synchronization settings, resolving configuration, and the actual destinations used. The

destination rule acts as the definition for an Activity Instance Destination. The activity instances holds a

collection of all the activity instance destinations created. Note, however, that this collection is only available

at the activity level.

The destination rule is the configuration behind how many activity instance destinations are created, which, in

turn, determines how many times the events inside the activity are executed. However, if a client event is

contained within the activity and the destination rule limits the slot count to less than the number of activity

instance destinations, server events that occur after the client event execute the same number of times as the

slot count.

ACTIVITY INSTANCE DESTINATION

An Activity Instance Destination is a container that holds each instance of the events within the activity.

Each activity instance destination has a unique serial number. This serial number is used for server, client,

and IPC events. The number of activity instance destinations created will depend on settings configured in the

destination rule (more on this later). Each activity instance destination contains a list of destinations it is

responsible for, the amount of slots available (which for Plan Per Destination activities is always 1), and a

copy of the data and XML fields that is unique for the activity instance destination. The activity instance

destination is responsible for executing the succeeding rule, which means the succeeding rule is executed

after every activity instance destination completes. Once the succeeding rule is true, all remaining (active)

activity instance destinations are expired.

It is important to understand that all events in each activity instance destination are executed only once. Each

activity instance destination will only create one event instance for every event as defined in the

process.

USER TASK

A User Task or simply Task is a business user concept and is represented on the technical level as a

Worklist Header. A Serial Number consists of the Process Instance ID and the Activity Instance

Destination ID (for example, 8_10). Each task has a unique serial number. A serial number is owned by an

activity instance destination. In case of a client event, a worklist header is created that identifies the serial

number as a user task.

WORKLIST HEADER

A Worklist Header is responsible for identifying a serial number as a user task created in a client event. It

stores the platform, serial number, slots available, total slots, and the data for the serial number. This is what

you see on your worklist and you can think of the worklist header as the serial number. If you have a Plan


PAGE 20

Just Once (PJO) activity, there are multiple slots per serial number, but if you have a Plan Per Destination

(PPD) activity, you will have a single slot per serial number.

Worklist headers do not exist for Plan Per Slot (PPS) activities, and these activities should not contain any

client events. A PPS activity is meant to process server events and control how IPC calls are processed by

the parent process.

SLOT

A Slot is a placeholder that captures the response from the user for a specific task. A slot contains data and

XML fields for a specific user’s response. Only a user can own a slot -- a group or a role cannot respond to a

task. Many slots can exist for a serial number (worklist header). When a worklist item is opened, that user gets

allocated a slot by the server. This slot allows the user to respond to the task and captures the data when the

user executes an action. Users can also release a slot and complete a slot.

The worklist header for PJO activities has one or more slots, but for PPD activities it has only one slot. With

PPD activities, the activity succeeding rule evaluates the slots, and if all slots are filled, expires any additional

activity instance destinations and the activity is complete.

Also keep in mind that the slot count that you see at the Activity General Properties page is the same slot

count that you can specify in the advanced Destination Rule Options page, as shown below. Changing the

slot count on either page will change it on the other page.


PAGE 21

ACTION

An Action is a business user concept that represent a list of instructions for the workflow server. This entails

setting data and XML fields and performing one of the server tasks, like Update, Finish, Redirect, Release, or

Goto activity. Security rights are configured between actions, worklist headers, and destinations, which is how

users can specify that a user to which they delegate a task can only perform a subset of the actions available

on that task.

EVENT INSTANCE AND EVENT SUCCEEDING RULE

An Event Instance is an instance created from an Event Definition. The event instance is contained by the

activity instance destination. The event instance is responsible for the Event Succeeding Rule. The event

succeeding rule determines if the event should complete, which is only evaluated in client events. The event

succeeding rule is executed every time a slot is completed for this event instance.

REDIRECT

Redirect is a server action that will move a worklist item from one user to another. The worklist item status is

left unchanged. If the item is ppen, it will remain open on the destination user’s worklist. This is a slot

ownership transfer. The data will also be intact as they are stored as part of the slot. This means, for example,

that user 3 can see the changes to the data and XML fields made by user 1. If the item is available, it will

remain available on user 3’s worklist. There is no slot allocated, so the rules stay the same if the item is

available or allocated, based on the available slots. All rights assigned to the original user are transferred to

the redirected user.

DELEGATE

The Delegate action is the sharing of a worklist item. No ownership transfer takes place. The item still belongs

to the original user. Delegation is simply based on rights to the worklist item. The delegated user can only


PAGE 22

perform the actions that have been delegated by the original user, and only actions that are available to the

original user can be delegated. The original user can still complete the task, which will take away the rights of

the delegated user as well, and vice-versa. If there is only one slot, the item is opened by the original user.

The item will show as allocated on the delegated user as he doesn’t own a slot, and all slots have been used

up. The item will also show the actual user the item belongs to. Any action performed by the delegated user is

recorded as on behalf of the original user.

SCENARIOS

What do each of the plan options mean in the context of the definitions above? Using scenarios to illustrate

the options and what happens based on the plan may help.

PLAN OPTIONS

There are three plan options – Plan Just Once (PJO), Plan Per Destination (PPD), and Plan Per Slot (PPS).

PPD activities can be executed in parallel (All at Once) or in serial (One at a Time). These options don’t

change the rules on how worklist items are handled by the server.

1. Plan Just Once

This option will only create one activity instance destination. The number of slots is set on the activity

instance destination, and all the destinations defined in the destination rule are copied to the

destinations collection of the activity instance destination. Because only one activity instance

destination exists, the client event executes once. This is why there is only one worklist header and

one serial number. All destinations have access to the same serial number and each response from a

user will update the activity instance destination’s data and XML fields. A slot is created for that user

and the data and XML fields are copied to the slot. Depending on the action performed, the slot is

completed or it remains open to all users.


PAGE 23

Plan Just Once means plan all events just once and create only one activity instance destination.

Worklist items are created for all destinations with a shared serial number. The event succeeding rule

is executed (not the activity succeeding rule) when a task is completed, and if false (allocated slots

are less than configured slots), the server events that follow the client event do not get executed.

Once all slots are allocated, the event succeeding rule is marked as true, and the subsequent server

events are executed. Once the server events execute, the activity succeeding rule is evaluated.

Plan Just Once represents shared data and XML fields, but the server tracks individual slots actions.

A copy of the data and XML fields are represented in the slots when the worklist item is opened, but it

does not get copied back to the activity instance destination unless the item is completed. The last

person to take action on the activity wins with regard to the data and XML fields.

The following illustration includes a start activity leading to the first activity in the process, Activity1,

which is a Plan Just Once activity:

2. Plan Per Destination (PPD) – All at Once or One at a Time

This option will create an activity instance destination for every destination. The events are executed

once for every activity instance destination. Each destination will have its own serial number, and

because a client event is executed, each destination will have its own worklist header. The slot

property for the activity instance destination is always set to one. Be careful not to confuse this slot

property with the one configured in the destination rule, which is the total number of slots for the

activity instance. The destinations collection for the activity instance destination will contain only one

destination. When a user actions the worklist item, the activity instance destination data and XML

fields are updated, a slot is created for the user, and the data and XML fields are copied to the slot for

that user. Depending on the action performed and how the process was designed, the slot is


PAGE 24

completed or it remains open to the user. When the slot is completed and because the activity

instance destination slot property is equal to one, the event succeeding rule is executed and

evaluates to true (all slots = completed). The activity instance destination executes the remaining

events in the activity and finally the activity succeeding rule executes. This repeats until all activity

instance destinations are completed or until the activity succeeding rule evaluates to true.

Plan Per Destination can be translated as plan all events in the activity for each destination. Each

plan is equal to one activity instance destination and one serial number. This represents separate

data and XML field collections as defined in the activity, and the activity data and XML fields are not

shared.

Once any two users open their tasks, the two available slots become allocated, and the user who has

not opened that particular worklist item will no longer see it on their worklist unless one of the other

users (User1 or User3) releases their worklist item before completing it. If both users complete their

worklist items, the remaining activity instance destination is cancelled. This means that the Server


PAGE 25

Event 2 for that activity instance destination (#2) is also cancelled. Server Event 2 for the other two

activity instance destinations (#1 & #3) are executed just after the users action their tasks. The activity

succeeding rule is then evaluated, to true in this case, and the activity instance destination (#2) is

expired.

Note that if there are more destinations than slots, the planned activity instance destinations are

automatically expired when the activity succeeding rule evaluates to true, which means the configured

number of slots are complete.

3. Plan Per Slot (PPS)

This option works exactly the same as plan per destination, except that there are no destinations

configured for this option. The activity instance destination rule still executes as normal, but the

destinations are ignored. The slot count is used to determine how many activity instance destinations

are created. This option is typically used in conjunction with server events or IPC events that require

no user action. Because there are no destinations and no client events, no worklist headers exist. So

there is no need to fill slots when the serial number is completed. Take an IPC call as an example:

The IPC execute synchronously, and once the IPC is returned from the child process, the event is

completed, and the data and XML fields are updated. Then the event succeeding rule is evaluated to


PAGE 26

true. The activity instance destination continues to execute the remaining events, and the succeeding

rule is evaluated.

DESTINATION RULE OPTIONS

So what happens when a user task is delegated? Before we get to that, there are a couple options available

on the Destination Rule wizard that need to be highlighted.

1. Create a Slot for each destination

This is a setting that determines the total number of slots to be created. If this option is checked, the

count is adjusted to reflect the amount of destinations added in the destination rule. This count can be

influenced by the previous setting (Resolve all roles and groups to users). If a user and a group are

added, and the previous setting is true, the slot count is equal to the number of users in the group

plus one. If this is a PPD activity, there are that many activity instance destinations created.

2. Resolve all roles and groups to users

This setting determines if the Roles and Groups should be resolved to individual users, and that each

user should be added as a destination instead of the role or group being used as the destination itself.

When the Create a slot for each destination and Keep roles synchronized options are true, and a

user is added to a role while the activity is active, the user is added to the destinations collection when

any user currently in the collection refreshes or opens their worklist. For a specified number of slots,

the user is added when the role refresh interval is reached.

3. Create a slot for each role or group

This setting determines if the Roles and Groups should be used as destinations in and of themselves.

This can be useful when role or group membership changes often, or the membership is very large.

4. Keep roles synchronized

Keep roles synchronized enables the activity instance to monitor any changes that may occur in the

roles or groups that are currently assigned to the activity instance. When a user is added or removed,


PAGE 27

the activity instance adjusts the slots if Create a slot for each destination is checked. For PPD

activities it creates or expire activity instance destinations if Resolve all roles and groups to users is

not checked. For PJO activities, only slots are adjusted to keep the succeeding rule updated.

Now that we understand the basics, let’s look at some scenarios:

REDIRECT SCENARIO

With plan per destination, if two users redirect to the same third user, that user can action the task

twice. If it's a plan just once activity with two slots, they will see two items on their worklist. If it's a plan

just once activity with one slot, the second task will disappear as soon as the second user redirects it.

Plan Option: Plan Just Once with two slots and two users (User 1 and User 2).

User 1 redirects the item to User 3. User 3 is added to the destinations collection of the

activity instance destination corresponding to the serial number. User 3 receives the

same rights as User 1. User 1 gets removed from the destinations collection. User 3 has

an item on his worklist and it disappears from User 1’s worklist.

User 2 redirects the worklist item to User 3. User 3 is already in the destinations

collection, and already has rights to the item. User 2 gets removed from the destinations

collection. Now there is only one destination left and two slots have been configured.

User 3 will only have one worklist item on his list that he can complete. The succeeding

rule will never be true as there are more slots than users.

Plan Option: Plan Per Destination with two slots and two users (User 1 and User 2).

User 1 redirects his item to User 3. User 3 is added to the destinations collection of the


same rights as User 1. User 1 is removed from the destinations collection. User 3 has an

item on his worklist and it disappears from User 1’s worklist.

User 2 redirects the item to User 3. User 3 is added in the destinations collection of the


same rights as User2. User 2 is removed from the destinations collection.

There are two activity instance destinations and User 3 is in both. User 3 will have two

worklist items on his worklist. The succeeding rule can be true in this case as there are an

equal number of slots to activity instance destinations.

When User 3 completes activity instance destination1 and activity instance destination2,

the activity completes.

DELEGATE SCENARIO

Delegate works in a similar way except that the original user keeps ownership of the worklist item.


PAGE 28

With plan per destination, if two users delegate to the same third user, that user can action the task

twice. If it's a plan just once activity with two slots, they will see two items on their worklist. If it's a plan

just once activity with one slot, both items will show as well.

Plan Option: Plan Just Once with two slots and two users (User 1 and User 2)

User 1 delegates his item to User 3. User 3 is not added to the destinations collection of

the activity instance destination. Instead he receives the same rights to the serial number

as User 1 as well as an indication of who the original user is (it shows User 1 as the

destination user.

User 2 delegates her item to User 3. User 3 gets the same rights as User 2.

There is one activity instance destination and User 3 has two sets of rights from each

original user. User 3 has two worklist items on his worklist that he can complete, however

each item shows the original user as the owner of that item. The succeeding rule is true

as there are equal slots to users. User 3 can complete both items. The slots still belong to

User 1 and User 2 and audit entries are logged to show that User 3 completed the items

on behalf of User 1 or 2.

Plan Option: Plan Per Destination with two slots and two users (User 1 and User 2)

User 1 delegates his item to User 3. User 3 is not added to the destinations collection of

the activity instance destination. Instead he receives the same rights to the serial number

as User 1 as well as an indication of who the original user is (it shows User 1 as the

destination user.

User 2 delegates the item to User 3. User 3 gets the same rights as User 2. Now there

are two activity instance destinations and User 3 has rights to both.

User 3 has two worklist items on his list that he can complete, but each item will show to

whom the item belongs to. The succeeding rule can be true as there are equal slots to

activity instance destinations

User 3 can complete activity instance destination1 and activity instance destination2. The

slots still belong to User 1 and User 2 and Audit entries are logged to show that User 3

completed the items on behalf of User 1 and 2.

When a delegated item is opened by the delegated user, it displays as Open on the original user’s worklist as

well as on the delegated user’s worklist. The slot belongs to User 1.

WORKLIST SHARING

Worklist sharing works the same as delegation. Worklist sharing is a view of another user’s worklist based on

criteria. Worklist sharing takes place at the worklist level, whereas delegation is on an individual item. Out of

Office is an implementation of worklist sharing, but is a different type of sharing. Worklist sharing is based on


PAGE 29

worklist criteria and users that it applies to. With worklist sharing, the items are displayed as part of the

destination users’ items with an extra column indicating the original user of the item.

MANAGED USERS

Managed users are determined by the default K2 User Manager, which is typically based on AD users. When

enabled, it allows a manager to see the list of the people he is managing in his worklsit. It is also a view of

each user’s worklist. Note that the manager can only see the items directly assigned to the destination user

and not the items shared or delegated to him.

QUESTIONS

Q: How do slots relate to Activity instanceDestinations?

A: Slots are determined at the activity level. Slots can be filled with Plan Once or Plan Per Destination

activities. If you have a Plan Once planned activity with slots per destination, the K2 server creates

multiple worklist items for a shared Activity instanceDestination, and evaluates the succeeding rule of

the event (not the activity). If all slots are not completed, the subsequent event after the client event

does not execute. This behavior can be changed through rules, however, where you can set an

outcome rule to say “At Least 2” are complete.

Q: What happens when there are more slots than destinations?

A: The Activity will never complete because the succeeding rule will never be true. You must alter the

succeeding rule so that the slots are less than the destinations.

Q: When you have Plan Per Destination, is the total slot count across all worklist headers?

A: Yes, and if you limit the slot count the activity succeeding rule is modified to check for the total slots

completed after each user actions his or her task.

K2 blackpearl Roles and Advanced Destination Rules

Documents

Transcript of K2 blackpearl Roles and Advanced Destination Rules