Upload
lamquynh
View
223
Download
0
Embed Size (px)
Citation preview
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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>
<Order>Order2412</Order>
<Order>Order3412</Order>
<Order>Order4531</Order>
<Order>Order5751</Order>
</OrderXML>
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.]
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
Resolve all roles to users FALSE
Create a slot for each role TRUE
Slot(s) assigned to Roles
Total number of slots 2
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:
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination TRUE
Specified number of slots N/A
Resolve all roles to users TRUE
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
PAGE 14
Create a slot for each role FALSE
Slot(s) assigned to Users
Total number of slots 6
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
Create a slot for each destination FALSE
Specified number of slots 1
Resolve all roles to users TRUE
Create a slot for each role FALSE
Slot(s) assigned to Users
Total number of slots 1
Outcome This works the same as Plan just once with the option
Resolve all roles to users.
Example #5
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination FALSE
Specified number of slots 1
Resolve all roles to users FALSE
Create a slot for each role TRUE
Slot(s) assigned to Users
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
PAGE 15
Total number of slots 1
Outcome Once a person actions the task, all worklist items are
removed.
Example #6
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination TRUE
Specified number of slots N/A
Resolve all roles to users TRUE
Create a slot for each role FALSE
Slot(s) assigned to Users
Total number of slots 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
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination TRUE
Specified number of slots N/A
Resolve all roles to users FALSE
Create a slot for each role TRUE
Slot(s) assigned to Roles
Total number of slots 2
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination TRUE
Specified number of slots N/A
Resolve all roles to users TRUE
Create a slot for each role FALSE
Slot(s) assigned to Users
Total number of slots 6
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
DESTINATION SET ROLE1, ROLE2
Create a slot for each destination TRUE
Specified number of slots N/A
Resolve all roles to users FALSE
Create a slot for each role TRUE
Slot(s) assigned to Roles
Total number of slots 2
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
PAGE 17
DESTINATION SET TEAM1, TEAM2 (ACTIVE DIRECTORY GROUPS)
Create a slot for each destination FALSE
Specified number of slots 2
Resolve all roles to users FALSE
Create a slot for each role TRUE
Slot(s) assigned to Users
Total number of slots 2
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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,
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
activity instance destination corresponding to the serial number. User 3 receives 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
activity instance destination corresponding to the serial number. User 3 receives 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.
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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
WHITEPAPER: K2 BLACKPEARL ROLES AND ADVANCED DESTINATION RULES
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.