Authorization and staff resolution in Business Process Choreographer: Part 2: Understanding the programming model for staff resolution

This article describes the Business Process Choreographer programming model of the instance-based authorization and staff resolution for business processes and human tasks. It explains how staff resolution is used to create work items, which are the core artifacts of instance-based authorization, how to model authorization rules using staff verbs, how these verbs are transformed at deployment, and how they are used for staff resolution at run time. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Kurt Lind (klind@de.ibm.com), Advisory Software Engineer, EMC

Kurt Lind has studied Communications Engineering at the University of Applied Sciences in Mannheim, Germany. As member of the WebSphere Process Server team, he is responsible for Human Task Manager and Business Process Choreographer security architecture.


developerWorks Contributing author
        level

07 November 2007

Introduction

Human Task Manager is an IBM® WebSphere® Process Server component that enables human beings to interact with Web services and business processes. Together with Business Flow Manager, which orchestrates business processes, Human Task Manager provides powerful support for the execution of business processes that involve humans. Both components together make up the Business Process Choreographer. One of the major features of Business Process Choreographer is its ability to provide instance-based authorization for business processes and human tasks by considering the business context. This enables you to model sophisticated authorization rules like the four-eyes principle in review or approval processes, a major enhancement of the standard J2EE™ authorization approach that only supports defining static authorization based on methods, without considering the business context. This instance-based authorization relies on staff resolution being performed so that people are assigned to various roles for later authorization checks.

Although authorization rules are modeled for a task template, these rules can behave differently for each human task or business process instance based on that template, since they are able to consider business context data when assigning people to an authorization role.

This article describes the programming model for Human Task Manager staff resolution, which provides access control lists for instance-based authorization. The programming model is introduced first, followed by a discussion on how you can model authorization rules for human tasks, what defaults apply, and how authorization is inherited. Finally, the article explains how to configure the staff resolution plug-ins and the staff query result refresh daemon.

The article assumes that you are already familiar with Business Process Choreographer concepts, architecture, and programming model as described in WebSphere Process Server V6 Business Process Choreographer: Concepts and Architecture and WebSphere Process Server V6.0 Business Process Choreographer Programming Model. Also, you are strongly encouraged to read Part 1 of this series before you continue with this article.


Programming model

Staff resolution (also known as people resolution) determines which users are assigned to a specific authorization role of a human task or business process, and to which e-mail addresses escalation notifications will be sent. Staff resolution is performed by the staff support service (also known as people assignment service) and the staff resolution plug-ins (also known as people directory plug-ins), which together provide an abstraction layer for the resolution of people information. The staff repository is an external people directory, such as LDAP (Lightweight Directory Adapter Protocol), or a repository configured for IBM WebSphere Application Server security.

The encapsulation of references to organizational information is an important consideration when you design human tasks and business processes with human interaction. Although human tasks and processes are usually relatively stable, the associated organizational information changes on an ongoing basis. For example, employees are assigned to new projects or are promoted, new hires are added to existing teams, or employees are temporarily out of office and require substitutes.

There are two approaches to separate business process logic from the associated organizational model:

  • Define staff queries based on groups or search queries. The queried organizational structures are stored in an external staff repository like LDAP.
  • Define staff queries based on variables from the human task or business process context. A typical example is to assign the starter of a business process to a human task in the process.

Because these two approaches are orthogonal, Human Task Manager staff resolution supports both. For example, you can assign the manager of an employee to a "Travel approval" task based on which employee has performed the previous "Request travel approval" task in the business process.

The authorization rules for human tasks and, indirectly, business processes are defined using so called staff verbs (also known as people assignment criteria), which are authorization rule templates. Staff query verbs are abstract authorization rules for a human task authorization role that can be parameterized and bound to a specific staff repository during business process and human task modeling.

Modeling

Figure 1 shows a diagram that describes how to model human tasks and business processes that use staff resolution.

Figure 1. Modeling human tasks and business processes with staff queries
Modeling human tasks and business processes with staff queries

As task or process modeler, you create human tasks using the task editor in IBM WebSphere Integration Developer. When you define human tasks, you select an authorization role, like "potential owner," and associate it with a staff verb from the verb set offered by the task editor. To support modeling query details, the staff verb comes with a set of parameters that must be populated with data. Parameter data can reference context variables like %wf:process.starter%. When you finished populating the parameter values, your authorization rule is ready for deployment. The resulting parameterized staff verb is stored as part of the human task model.

For each task, you also specify a staff resolution plug-in configuration JNDI (Java Naming and Directory Interface) name, which refers to a staff plug-in configuration (also known as people directory configuration) to be used for staff verb deployment and later execution of the deployed staff queries at run time. By default, the UserRegistry staff resolution plug-in configuration is used. The resulting task or process model is exported as a J2EE enterprise archive (EAR) file that can be deployed to a WebSphere Process Server installation.

Process Choreographer provides a default set of staff verbs that can be used for standard staff queries. You can extend the set of verbs and define verbs that more closely match your needs. The administrator is responsible for defining and customizing staff query verbs and their associated mapping XSLT files, and so is expected to have indepth knowledge of the target staff repository.

When you have finished modeling your human tasks and business processes, you can assemble them, and prepare them for deployment to the runtime server as an EAR file.

Deployment

Figure 2 shows a diagram describing the deployment steps and involved roles.

Figure 2. Deployment of human tasks and business processes with staff verbs
Deployment of human tasks and business processes with staff verbs

When the WebSphere Application Server administrator deploys the human task or business process model EAR file, the staff support service transforms the parameterized staff query verbs into plug-in specific staff queries. This step involves an XSLT (Extensible Stylesheet Language for Transformations) verb mapping file. The XSLT file is associated with a staff plug-in configuration that is bound to the human task using the corresponding JNDI name that you specified in the task model.

After the XSL transformation has mapped the parameterized staff verb to the staff repository schema and plug-in specific query language, deployment continues by validating and deploying these queries in the staff resolution plug-in. Human Task Manager accesses staff resolution plug-ins via their staff plug-in configurations, the same configuration artifact used to access the XSLT file:

  • A staff repository specific staff resolution plug-in is represented by a staff plug-in provider (also known as people directory provider) in the administration console.
  • Each staff plug-in provider must have at least one staff plug-in configuration.
  • Each configuration has
    • Its own JNDI name that is used to locate it and is specified when modeling human tasks.
    • A reference to an XSLT verb mapping file, which translates the parameterized verbs into the plug-in specific staff query language.
    • A set of configuration properties for the LDAP plug-in configurations that contains, for example, a provider URL pointing to the staff repository LDAP server.

The WebSphere Application Server administrator has to ensure the availability of the staff plug-in configurations used in human task or business process models before deploying them. WebSphere Process Server comes with three staff repository specific staff resolution plug-ins. WebSphere Portal provides a fourth one for WebSphere Member Manager. A default staff plug-in configuration is available for each plug-in. If the defaults do not match your system parameters, you might want to create your own plug-in configuration for the LDAP or WebSphere Member Manager plug-in provider. If you want to use your own customized XSLT verb mapping file, create a new staff plug-in configuration that refers to your XSLT file.

The default XSLT mapping files might be updated together with the product, which would replace your changes if you do not work with an own copy of the mapping file.

When the staff support service has finished transforming the parameterized staff verb into a plug-in specific query, and the staff resolution plug-in has deployed the resulting staff query, the deployment artifacts are stored in the Business Process Choreographer database and available for staff resolution at run time.

Staff resolution

Figure 3 shows a diagram describing staff resolution at run time.

Figure 3. Resolving staff queries
Resolving staff queries

The actual staff resolution happens at run time, for example, to retrieve the list of potential owners of a human task when the task is started. The authorization management retrieves the stored staff query specification from the database, resolves the set of context variables referenced by this query, and invokes the staff support service to resolve it. The staff support service selects the appropriate staff resolution plug-in and delegates staff resolution to it.

The staff resolution plug-in replaces context variable references of the query with concrete values, and then invokes API methods of the staff repository to retrieve lists of user IDs or a group ID. The staff query result is returned to the authorization management.

When a staff query result post-processor plug-in (also known as people assignment post-processor plug-in) has been registered, it is invoked with this staff query result and a set of context data, providing it with the possibility to alter the result. This plug-in can perform, for example, workload management for the involved people (by removing user IDs of people with a high workload), or adding user IDs of additional people to enhance the overall business process performance. This plug-in can even change the type of the staff query result, for example, from a list of user IDs to a group ID or vice versa. The modified staff query result is then returned to the authorization management.

Authorization management transforms the staff query result into so-called work items that are stored in the Business Process Choreographer database. Work items build a cache for staff resolution results that is available for Business Process Choreographer authorization. This way, the staff repository containing the organizational model is not queried for every authorization request, but only when an authorization rule is resolved for the first time, or when the staff query result that is cached in the work item expires and is refreshed.

The content of the work item cache is used for instance-based authorization in two cases:

  • When an API method is invoked, where instance-based authorization applies. For example the method claim().
  • For implicit or explicit filtering of the result set of the query() method. The caller only receives the rows of the potential result set, for which she has an appropriate work item.

When an API method like claim() is invoked, an authorization check is performed to verify whether this user is allowed to perform the action. The authorization check compares either the user ID or the group membership list of the logged-on user with the content of the work item cache. (Be aware that this check is case sensitive.)

For user work items, the user ID (caller principal name) of the calling user is compared with the user ID of all user work items associated with the primary business object (for example, a human task) for which the API method is invoked. If a work item is found that is associated with this user, the selected business object, and a predefined authorization role that allows this API method to be invoked, then authorization is granted.

For group work items, the group membership list of the calling user is compared with the group ID of all group work items associated with the primary business object (for example, a human task) for which the API method is invoked. If a work item is found for a group where this user is member, and the group is associated with the selected business object and a predefined authorization role that allows this API method to be invoked, then authorization is granted.

Members of the J2EE roles BPESystemAdministrator and TaskSystemAdministrator always have administrator rights, and are treated as if they have an administrator work item for every business object. Members of the J2EE roles BPESystemMonitor and TaskSystemMonitor always have reader rights, and they are treated as if they have a reader work item for every business object.

If you use the query() API method, authorization is performed by implicitly adding a check for appropriate work items to the database query. This authorization check filters the result set and ensures that the caller can only see these result set rows for which she has an appropriate work item. Since every authorization role grants reader rights, it is sufficient when the caller has a matching work item for any assignment reason (authorization role). A matching work item is either a user work item corresponding to the caller principal name, or a group work item corresponding to one of the groups of which the caller is a member. (This check is also case sensitive.) Members of the J2EE roles BPESystemAdministrator, BPESystemMonitor, TaskSystemAdministrator, or TaskSystemMonitor can always see every result set row. (See Resources for more information about the query() API method.)

Transferring work items

Sometimes you will want to modify the people assignments created during staff resolution for various reasons, such as dynamically managing your people's workloads, absence of business critical team members, and so on.

For these cases, Business Process Choreographer offers you a set of run time API methods that enable you to alter the work items created during staff resolution on instance objects like human tasks, escalations, process instances, and their activities. These API methods support:

  • Transferring a work item from one person to another person.
  • Transferring a group work item from one group to another group.
  • Creating a work item on an instance object for an additional person.
  • Deleting a work item for a person.

Be aware that these restrictions apply:

  • You are not allowed to delete the last administrator work item, since the corresponding instance object must remain manageable.
  • Creating, transferring, or deleting "Everybody" work items is not supported.
  • Work item creation, transfer, and deletion must occur on the original object. Work items assigned due to role inheritance cannot be transferred on the object that inherited the work item, but only on the original object, where staff resolution occurred. For example, a process administrator work item can only be transferred based on the process instance ID or the process administrative task ID, but not based on an inline human task ID or a process activity ID, since on these objects, the work item exists only to reflect role inheritance.
  • For security reasons, not every person is allowed to transfer every work item. These rules apply:
    • Administrators can create, transfer, or delete work items of every authorization role to anybody.
    • Originators can create, transfer, or delete work items of these authorization roles to anybody: potential owner, potential starter, originator, reader, editor, and escalation receiver.
    • Task owners can transfer their owner work item to another potential owner, or to an administrator.
    • Task starters can transfer their starter work item to another potential starter, or to an administrator.
    • Transferring work items can also be forbidden due to an incompatible state of the owning business object. For example, you are not allowed to transfer a task owner work item when the task is already finished.
    • The target user ID for a work item transfer or creation is validated by default. The target group ID for a group work item transfer is not validated.
  • When adding or transferring a work item to a new escalation receiver, no e-mail will be sent to this person, even when the escalation action is e-mail.

When a staff resolution result is refreshed, its transfer history is re-applied. Thus, staff resolution refresh does not reset a work item creation, transfer, or deletion.


Modeling authorization rules with the task editor

With the Human Task Editor (Figure 4), WebSphere Integration Developer provides you with a powerful editor to model authorization rules for business processes and human tasks. You define authorization rules using staff verbs for the set of predefined authorization roles.

Figure 4. Human Task Editor
Human Task Editor

You can define authorization rules selecting the authorization role of your choice on the editor canvas, under Staff settings. Then the Verb (or people group) tab will appear in the properties pane for the human task.

You can add a role to the human task by clicking on the associated icon on the task pane, next to the Receiver settings. These roles are available for human tasks:

  • Potential instance creator specifies who can create a task instance from this model. It is resolved to check authorization before task instance creation (as a first role during task creation).
  • Potential owner specifies who can work on the task by claiming and completing it. It is resolved as a second role during task start.
  • Potential starter specifies who can start the service associated with the task. It is resolved as a second role during task creation.
  • Administrator specifies who can administer the task and perform every permitted action on the task. It is resolved as a first role during task start.
  • Editor specifies who can work on a claimed task, but cannot influence the task lifecycle. It is resolved as a third role during task start.
  • Reader specifies who can see all task properties and associated objects, but cannot change them. It is resolved as a fourth role during task start.

Not every role is available for every kind of task. Table 1 shows which authorization role is supported by which kind of task.

Table 1. Authorization roles and their support by human tasks
Authorization roleParticipating taskOriginating taskPurely human taskAdministrative task
Potential instance creatorXXX--
Potential ownerX--X--
Potential starter--X----
AdministratorXXXX
EditorX--X--
ReaderXX-XX

For inline originating tasks, the potential instance creator role is identical with the potential starter role. Inline tasks are tightly coupled with the business process they are part of. Their lifecycle is usually determined by the process instance and they have access to the process context data. Only inline originating tasks that are started using the Human Task Manager API manage their own lifecycle. Standalone tasks are available as service components, are independent from the eventually surrounding business process, and thus manage their own lifecycle and have no access to the process context.

When modeling escalations for the human task, you can define the people who will see the escalation and receive the associated notifications using the escalation receiver role.

Business process roles are defined using human tasks associated with the process or some of its activities:

  • To define business process readers and administrators, select the process administrative task in the BPEL editor Human Task property tab when no specific process activity is selected, and define the authorization rule for these two roles there.
  • To define potential starters for a Receive or Receive Choice activity, or an "on event" Event Handler, select the activity in the process model, and in the Human Task property tab click on the Human task link and define the authorization rule for potential starters there.
  • To define administrators for invoke activities, select the activity in the process model, and in the Human Task property tab, click on the Human task link, and define the authorization rule for administrators there.
  • To define default administrators for process activities, select the default administrative task for activities in the BPEL editor Human Task property tab when no specific process activity is selected, and define the authorization rule for this role there.

A business process always navigates with the authority of the process starter. This means that services represented by invoke activities are always invoked with this user's security context. Thus, when you model standalone participating human tasks as invoke activities in a business process, you need to ensure that all people who are able to instantiate the business process are assigned as potential instance creators to this task. Otherwise, the process engine might not be able to invoke this task at run time.

When you selected the role in the human task editor, the Verb tab will appear in the Properties pane for the human task. Figure 5 shows the details of this tab, where you can model an authorization rule.

Figure 5. Staff verb definition
Staff verb definition

You can select the staff verb of your choice from the drop down box. The description field beneath gives a short overview of the capabilities and staff plug-in provider support of the selected verb.

The table at the bottom lists parameters supported by the selected verb. Mandatory parameters are marked with an asterisk in the first table column. Enter the parameter values of your choice in the Value field. Some verb parameters have a set of hints associated with it to help you enter appropriate values. When you click in the Value field of a parameter that supports hints, a button appears at the right of the field. Click on this button to see the set of hints (Figure 6).

Figure 6. Verb parameter hints
Verb parameter hints

For each human task, you can select or enter the staff plug-in configuration JNDI name of your choice, which will resolve the authorization rules you defined, at run time. Click on the human task pane in the human task editor to see the human task properties tabs. Click on the Details tab to see the editable drop down box for the plug-in configuration JNDI name. You can either select a default entry from the drop down list, or enter the JNDI name of your self-defined staff plug-in configuration.

The parameterized staff verbs representing your authorization rules are stored as part of the human task model and will be deployed together with your human task or business process model EAR file. When you finished modeling a process or task, you can assemble it, and deploy it to the WebSphere Process Server runtime, which provides you with a set of pre-configured staff resolution plug-ins that can be used to perform the staff queries for these authorization rules.

Staff query verbs

The Human Task Editor in WebSphere Integration Developer comes with a predefined set of staff query verbs, offering support for basic authorization rules. You can extend and adapt the set of verbs in order to better fit your project's needs.

Some staff verbs are not supported by all staff plug-in providers. The Manager of Employee verb, for example, is only available for the LDAP staff plug-in provider. For further details on staff verbs and their parameters, see the WebSphere Process Server Information Center in Resources.

Here is a summary of the predefined staff verbs delivered with the Human Task Editor:

  • Department Members enables you to query for members of a department.
  • Everybody assigns every authenticated user.
  • Group assigns a whole group, without resolving its members (late binding). This verb creates a single group work item for the whole group instead of a user work item for each of the group members, and thus efficiently supports large groups. (You have to enable group work items in the administrative console for this verb, since they are disabled by default.) For small groups, or when your users are members of many groups, you might prefer the Group Members verb, since when group work items are enabled, authorization checks are more complex and come with a cost that increases with the number of groups a person is member of.
  • Group Members queries for members of a group. The group members are resolved (early binding) with the staff query. For large groups, it is better to use the Group verb.
  • Group Members without Filtered Users queries for members of a group, but removes a set of users from the result set. The set of users to be removed is defined by a search filter.
  • Group Members without Named Users queries for members of a group, but removes a set of users from the result set. The set of users to be removed is entered as a verb parameter, preferably using context variables. This verb supports the four-eyes principle.
  • Group Search enables you to search for a group, based on an attribute match. This verb resolves the members of the groups it finds.
  • Manager of Employee retrieves the manager of a person, given the person's name.
  • Manager of Employee by user ID retrieves the manager of a person, given the person's user ID. This verb is useful in combination with context variables.
  • Native Query enables you to define a native query based on staff plug-in provider specific parameters. This verb can be used to define simple custom queries. For more sophisticated custom staff queries, you should define a new verb.
  • Nobody does not assign normal users. Only inheritance applies to this authorization role. For roles with mandatory staff assignment, the default for an empty result set additionally applies.
  • Person Search searches for people based on an attribute match.
  • Role Members queries for members of a role in the staff repository.
  • Users assigns a user who is known by name. (From a human task and business process perspective, it is not recommended to hardcode user names in task models, but rather to use more dynamic user assignment approaches that do not fail when the assigned person changes the organization.)
  • Users by user ID assigns a user who is known by its user ID. This verb is useful in combination with context queries, when it assigns the user IDs from a context variable, for example: Users by user ID [UserID='%wf:process.starter%']
  • Users by user ID without Named Users assigns one or more users known by user ID, but removes a set of users from the result set. The set of users to be removed is entered as verb parameter, preferably using context variables. This verb supports the four eyes principle; for example, it assigns the set of potential owners from the previous process activity, but removes the owner of the previous activity (both using context variables).

Some of these verbs can return potentially large sets of user IDs to be assigned to an authorization role. Since such large staff assignments usually do not make much sense in a business process, and yet impact the overall performance, Human Task Manager supports a threshold parameter that limits the number of returned user IDs. The threshold parameter is set by default to 20 users. If you want to use larger result sets, you can customize this parameter in the XSLT file associated with your staff plug-in configuration.

Staff query verbs for e-mail addresses

When modeling escalations with escalation action e-mail, some additional staff query verbs are used to resolve the e-mail address of the escalation receivers. You will not see these verbs when using the Task Editor in WebSphere Integration Developer, but when creating new verbs, or when creating ad hoc tasks, it is important to understand what rules apply.

To select the right verb for the resolution of escalation receiver e-mail addresses, the task editor searches for a verb that has the same name as the escalation receiver verb, prefixed by "Email Address for " and the same set of parameters.

  • If this verb exists, it will be used and it will receive the same parameters as the escalation receivers verb.
  • If such a verb is not available, the task editor will use the Email Address for Users by user ID verb, and pass it the variable %htm:escalation.receivers% as an input parameter. This verb receives the user IDs of each escalation receiver, searches for the corresponding user record, and retrieves the e-mail address from this user record. This verb is always working, but due to the large number of searches, it may be slower than a native e-mail verb implementation.

This algorithm is implemented under the covers in the task editor, and you won't normally see it, but when creating ad hoc tasks or new staff query verbs, you should be aware of it. When creating an ad hoc task, you should select the staff verb for the eMailReceiver following the algorithm described above. When creating new staff query verbs, consider the creation of a corresponding e-mail verb. If it can be implemented to be faster than a search for each user by its user ID, then it might be worth the effort.

The LDAP staff resolution plug-in natively supports the following staff query verbs to resolve e-mail addresses:

  • Email Address for Department Members
  • Email Address for Group Members
  • Email Address for Group Members without Filtered Users
  • Email Address for Group Search
  • Email Address for Role Members
  • Email Address for Users
  • Email Address for Users by user ID (the default e-mail staff query verb).

Modeling context-based authorization rules

When defining more sophisticated authorization rules like the four-eyes principle, you need access to the process context in order to exclude the owner of the previous task and to enforce this principle. Human Task Manager provides you access to the surrounding context using context variables that can be included in staff verb parameters as shown above in Figure 6.

Context here means data from previous staff resolutions, values from task input or output messages, custom properties, and so on. For inline tasks, additional context from the surrounding business process is available. Context variables are referred to using percent ( % ) signs and have the following notation:

%context variable%

For example: %htm:task.originator%. Using percent signs within variable names is not permitted. If a percent sign is required to be used within a string where context variables can be used, then use double percent signs ( %% ). Context variables can also contain XPath expressions. If an XPath expression contains a percent sign itself, it must be escaped, as specified by XML (using %).

Not all the values of context variables are always available during the task or escalation lifecycle. For example, the task owner is only available after the task has been claimed. If a variable is used before it has been defined, then the variable is not replaced. For example, when the following string is to be processed for variable replacements:

The task owner is %htm:task.owner% and needs to review the document until %htm:property.reviewCompletionTime%.

and the task owner is already available, but the custom property reviewCompletionTime has not yet been set, the result after replacement will be the following:

The task owner is John and needs to review the document until %htm:property.reviewCompletionTime%.

Context variables might resolve to single values or to multiple values. Single value context variables evaluate to a string that is replaced in the parameter context, for example, cn=%htm:task.originator% evaluates to "sarah". Multi-value context variables like %htm:task.administrators% evaluate to a string array. (The use of multi-value context variables is limited to one per staff query element.)

Examples for context variables:

%htm:task.owner% resolves to the user ID of the person who has claimed the task instance, and is thus its owner.

%htm:task.potentialOwners% resolves to this task instance's set of the potential owners assigned by a previous staff query.

%htm:task.property.customPropertyName% provides access to custom properties of the human task. The leading htm:task.property. is a constant delimiter, followed by the name of the custom property.

%htm:input.[messagePartName][\XPathExpression]% resolves to the task input message, or to parts of it. The leading htm:input. is a constant delimiter, followed by the optional name of the message part to be accessed. Optionally, there can follow an XPath expression to access only a specific element of the message (part). Note that the XPath expression must resolve to a string, a string array, a Java object with a useful toString() method, or an array of Java objects with a useful toString() method. For example, %htm:input.\admins% resolves to the string array element with name admins of the input message. The part name was not specified, since this is a single-part message.

Inline human tasks have access to the process context and thus they can also access process context variables.

They have access to simple process context variables like %wf:process.administrators%, or %wf:activity(activityName).owner%, where "activityName" represents the name of the activity to which the owner will be resolved.

They have access to process custom properties using the expression %wf:property.customPropertyName%, where wf:property. is a constant part.

They can also access process variables or the process input message, using this expression: %wf:variable.[variableName]\messagePartName[\XPathExpression]% where wf:variable. is a constant part. The message part name is mandatory for interface typed variables, and defaults to "<operationName>Parameters" for doclit/wrapped style interfaces. Check your message WSDL for the exact part name. For data typed interfaces (Business Objects), the part name is optional. Know that a variable name must not be specified when evaluating context variables for the process administrative task, since this is taken directly from the process input message. Also know that specifying staff resolution results from the process input message might lead to a security hole.

This example shows how you can access a process variable: The expression %wf:variable.ReadersVar\\readers% accesses the string array attribute "readers" of the process variable named "ReadersVar."

This example shows how you can access the process input message: The expression %wf:variable.\operation1Parameters\reader% accesses the string typed element "reader" of the input message part. "operation1Parameters"

To find the right part name for your XPath expression in WebSphere Integration Developer:

  1. Select the WSDL file describing your variable or input message type. It will usually have the name of your process model with the extension .wsdl. Otherwise, check your variable definition for the right WSDL file, which you can find by clicking on the variable, and in the Properties panel's Details tab, push the Browse button in order to see which WSDL file defines the variable.
  2. Open the WSDL file with the WSDL Editor in the source view, and check for the operation associated with your process input message or variable. You can find the input message operation by clicking on the initiating receive activity, and in the Properties panel's Details tab you can see the selected operation. Alternatively, you can find the operation associated with your variable by clicking on the variable, and in the Properties panel's Details tab you can see the selected operation. Here you can also see whether the input or output message type is used by the variable.
  3. The operation defines the message name. Check for the message definition, which declares the part.
  4. The part name is the string you have to enter when defining your XPath expression.

In this example, you find the operation (operation1), which defines the input message (operation1Request). The message (operation1Request) defines a single part with the name "operation1Parameters."

...
<message name="operation1Request">
  <part element="tns:operation1" name="operation1Parameters"/>
</message>
<message name="operation1Response">
  <part element="tns:operation1Response" name="operation1Result"/>
</message>
<portType name="ApprovalProc">
  <operation name="operation1">
    <input message="tns:operation1Request" name="operation1Request"/>
    <output message="tns:operation1Response" name="operation1Response"/>
  </operation>
</portType>
...

Modeling authorization rules for ad-hoc tasks and task templates

When modeling ad hoc human tasks using the run time API, you will use the Eclipse Modeling Framework (EMF) API to create the task model as a tree of EMF objects and properties. The authorization rules for human tasks are modeled using the TStaffSettings class, which aggregates all authorization roles of a task, and where you can attach an authorization rule for each supported authorization role. The staff settings are aggregated by the main TTask object. The authorization rules for escalations are aggregated directly by the TEscalation class.

The authorization rule assigned to an authorization role is modeled using the corresponding child class of the TStaffRole class. These authorization role classes are available to model authorization rules for human tasks:

  • TAdministrator
  • TEditor
  • TPotentialInstanceCreator
  • TPotentialOwne
  • TPotentialStarter
  • TReader.

These authorization role classes are available to model authorization rules for escalations:

  • TEMailReceiver
  • TEscalationReceiver.

When human tasks are modeled in the task editor, the editor will create the e-mail receiver verb automatically under the covers for you, based on your selection for the escalation receiver authorization role. When you create a task model ad hoc and use escalations with escalation action ">e-mail," you have to model the e-mail receiver staff verb manually. See staff query verbs for e-mail addresses for details.

Each TStaffRole (child) class aggregates a verb object that represents the authorization rule. You will create the authorization rules based on the same set of staff verbs that you would use in the WebSphere Integration Developer task editor. The content of the verb you have to model corresponds to the parameterized staff verb created (based on your input) by the task editor. The verb is an object of the class TVerb and has a name property, and a list of parameter objects. The verb name must be supported by the selected staff plug-in configuration (XSLT file).

The parameters are objects of the class ParameterType. They have two properties: ID and value. The parameter ID is the parameter name as displayed in the task editor and supported by the XSLT template corresponding to the selected verb. The parameter value is exactly the value you would enter in the task editor, including context variables.

You select the staff plug-in configuration for an ad hoc task by entering its JNDI name as the JndiNameStaffPluginProvider property of the main TTask object.


Staff resolution defaults and authorization inheritance

Default staff assignments

Some of the authorization roles mandate that people are assigned to them. For example, a human task might become unusable if it has no administrator assigned. Also, if a participating or purely human task has no potential owners assigned, nobody will perform the assigned work.

Consequently, Human Task Manager defines defaults for missing or failed authorization rules that are specific to every authorization role. An empty staff resolution result is treated the same way as a failed one. Tables 2, 3 and 4 show which defaults apply for which human task or business process authorization role.

Table 2. Staff resolution defaults for business process roles
Business process rolesRole not defined in process modelStaff resolution fails or returns empty result
Process administratorProcess starter becomes process administratorEngineAdministratorCannotBeResolvedException is thrown and the process is not started.
Process readerNo readerNo reader
Table 3. Staff resolution defaults for inline human tasks and escalation roles
Inline human task or escalation roleRole not defined in task modelStaff resolution fails or returns empty result
Task administratorOnly inheritance appliesAdministratorCannotBeResolvedException is thrown and the task is not started
Task editorNo editorNo editor
Task potential instance creatorEverybody becomes potential instance creatorEverybody becomes potential instance creator
Task potential ownerEverybody becomes potential ownerAdministrators become potential owners
Task potential starterEverybody becomes potential starterEverybody becomes potential starter
Task readerOnly inheritance appliesOnly inheritance applies
Escalation receiverAdministrators become escalation receiversAdministrators become escalation receivers
Table 4. Staff resolution defaults for standalone human tasks and escalation roles
Standalone human task or escalation roleRole not defined in task modelStaff resolution fails or returns empty result
Task administratorOriginator becomes administratorAdministratorCannotBeResolvedException is thrown and the task is not started
Task editorNo editorNo editor
Task potential instance creatorEverybody becomes potential instance creatorEverybody becomes potential instance creator
Task potential ownerEverybody becomes potential ownerAdministrators become potential owners
Task potential starterOriginator becomes potential starterCannotCreateWorkItemException is thrown and the task is not started
Task readerOnly inheritance appliesOnly inheritance applies
Escalation receiverAdministrators become escalation receiversAdministrators become escalation receivers

Authorization role inheritance

A person who is the administrator of a business process expects to be authorized to execute every action in this process to be able to fix problems that occur during process operation. There are additional roles that you might expect authorization to be inherited from a high level business entity (like a process) to a lower level entity (like a process activity). Human Task Manager provides intuitive authorization inheritance using these rules:

  • A process administrator is administrator for every activity, inline task (including its sub- and follow-on tasks), or task escalation of the process.
  • A process reader is reader for every activity, inline task (including its sub- and follow-on tasks), or task escalation of the process.
  • Members of an inline participating task authorization role have the same role on the corresponding human task activity.
  • A potential starter of an inline originating task is a potential starter of the associated Receive or Receive Choice activity, or an "on event" Event Handler also.
  • A task administrator is administrator for every sub- and follow-on task of this task, including escalations of one of these tasks.
  • Members of each task role are readers for every sub- and follow-on task of this task, including escalations of one of these tasks.
  • Escalation receivers are readers for the escalated task, and for every sub- and follow-on task of this task, including escalations of one of these tasks.

You will not be able to transfer inherited work items on the low level business entity; instead, you will have to transfer the work item on the business entity that assigns the person to the role directly. For example, you can transfer a process administrator using the administrator work item on the business process, but you cannot transfer the administrator work item for the same user on an activity or inline human task of this process instance, since it is inherited. The rationale for this rule is that you cannot distinguish an inherited work item from a direct one at first sight. You would think that you could transfer the task administrator, but what you would actually transfer is the process administrator, which was not your intention. If a person has two administrator work items on a task, one is inherited from the process, and the other one is directly assigned; the directly assigned one can, of course, be transferred.

Also be aware that members of the human task container and process container J2EE roles "inherit" rights for every business entity (process, activity, task, escalation) that is visible to other users: when a method is invoked via the Business Flow Manager API, members of the J2EE role BPESystemAdministrator have administrator authorization, and members of the J2EE role BPESystemMonitor have reader authorization. When a method is invoked via the Human Task Manager API, members of the J2EE role TaskSystemAdministrator have administrator authorization, and members of the J2EE role TaskSystemMonitor have reader authorization. As a consequence -- and especially for use cases that access both APIs -- it is recommended (but not required) to assign the same set of people and groups to the two sets of roles.


Staff plug-in configurations

The sections above described how you can model authorization rules, by defining what staff verb applies, and which input parameters it will receive to execute that rule at run time. You also need to specify the staff repository to be queried in order to execute the authorization rule. You can specify the staff repository and its access parameters in your task model indirectly by entering the JNDI name of a staff plug-in configuration, available as a run time server resource. Human Task Manager supports multiple staff plug-in configurations in parallel; you can specify one per human task model.

Staff plug-in configurations determine how staff resolution is performed at run time. Each has a unique JNDI name used to register it as an application server resource, and specifies:

  • What repository type is to be used (for example LDAP or User Registry).
  • What XSLT file is used to map the staff verb and its parameters to a concrete staff query that is executable at run time. The XSL transformation:
    • Maps the staff verb and its parameters into an XML language corresponding to the staff repository type (staff plug-in provider).
    • Adapts the resulting query to the schema of your staff repository, if needed. This is required, for example, for LDAP servers where each customer uses a different LDAP schema of his choice.
  • Additional custom properties, if required by the selected staff plug-in provider. For example:
    • Hostname and port of the directory server to access.
    • Security settings for the directory server connection.

Staff plug-in configurations are available in the WebSphere administrative console under Resources => Staff plug-in provider. On this panel, you can click on the staff plug-in provider of your choice and in the screen that opens, select Staff plug-in configuration to get the list of staff plug-in configurations available for the plug-in provider you selected. From here, you can add, delete, or modify staff plug-in configurations. Figure 7 shows the staff plug-in configuration screen that opens when you select add or modify.

Figure 7. Staff plug-in configuration
Staff plug-in configuration

You can enter a name, description, and JNDI name for the plug-in configuration. The location of the XSLT file can be set when creating the configuration. The JNDI name is the link to the task model that references the configuration and must be unique. The plug-in configuration must be available before deploying a task model that uses it.

If the plug-in provider supports custom properties, you can access them using the Custom properties link. Another panel opens, where you can set values for the properties the staff plug-in provider supports. For example, the LDAP staff plug-in supports a set of custom properties, like the LDAP provider URL (hostname and port). (Do use the Custom properties link that is exposed by the staff plug-in provider screens; instead, use the link on the staff plug-in configuration screens.)


Staff query result refresh daemon

Since every organization is subject to continuous changes, staff resolution results can become outdated and need to be refreshed in the work item cache. The staff query result refresh daemon (also known as people assignment refresh daemon) is responsible to refresh staff query results that have expired.

The refresh daemon runs on a regular basis and refreshes all staff query results that are expired at that moment. The refresh happens according to the staff verb associated with the corresponding work item. Staff resolution is invoked again and the new results are stored with the existing work item. Thus, in case of an organizational change, the refresh daemon keeps the work item cache up to date. If the work item has been transferred before, the transfer history is applied again, thus a previous transfer is not overridden by this refresh.

The refresh daemon behavior is controlled by two parameters:

  • timeout for staff query result determines how long after the last update a staff query result remains valid. When this time period has passed, this query result is available for update.
  • staff query refresh schedule controls the time when the refresh daemon runs to refresh expired query results.

You can access these two parameters in the WebSphere administrative console in the panel Application Servers => <server name> => Human task container. In this panel's edit field group Staff Resolution, you will find the fields Staff query refresh schedule and Timeout for staff query result. Enter the refresh interval as a string value with WebSphere CRON calendar syntax (see Resources). Enter the timeout value as an integer in seconds, specifying the duration after a new staff query result will expire.

These rules apply for staff query refreshes:

  • When refreshing the work item cache, changes of context variables will not be considered; the refresh will occur based on the context data available when staff resolution for this staff query was performed for the first time.
  • If the initial staff resolution did not return any results or failed, and thus staff resolution defaults have been applied, the refresh will be applied on the staff resolution default, not on the original staff query.
  • You can also enforce staff query result refreshes manually, using the WebSphere Application Server administration console or the JACL script refreshStaffQuery.jacl. (See Resources for more details.) When refreshing this way, all specified staff query results are refreshed, not only the expired ones.
  • Refreshes performed by the refresh daemon, the administrative console, or the JACL script do not apply to the user-to-group membership as considered by group work items. A user's group membership list is refreshed when the user logs on again.

The refresh daemon is only available in WebSphere Process Server V6.0.2 and later.


Conclusion

Human Task Manager provides powerful instance- and business context-based authorization for people involved in business processes and Service Oriented Architectures. It performs staff resolution queries based on flexible authorization rules, and caches the query results for better authorization performance.

This article described the WebSphere Process Server Business Process Choreographer rule and instance-based authorization and staff resolution programming model. It described the authorization roles with their inheritance rules and defaults, how you can define authorization rules, and how they are resolved in order to perform instance-based authorization.


Acknowledgements

The author thanks his colleagues Eric Van Norman, Gerhard Pfau, and Hans Schoen for their help in preparing this article.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=267278
ArticleTitle=Authorization and staff resolution in Business Process Choreographer: Part 2: Understanding the programming model for staff resolution
publish-date=11072007