Authorization and staff resolution in Business Process Choreographer: Part 4: Staff resolution specifications and reference guide

Information for customizing staff resolution

This article describes the details and specifications of Business Process Choreographer staff resolution, including staff resolution plug-in query syntax and configuration parameters, and information necessary for customization. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

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

Author photoKurt 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

23 January 2008

Introduction

Human Task Manager is an IBM® WebSphere® Process Server component that enables human beings to interact with Web services and business processes. Working with Business Flow Manager, it 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 instance-based authorization for business processes and human tasks that enables you to model sophisticated authorization rules, like the four-eyes principle, in review or approval processes. The instance-based authorization is based on data provided by staff resolution for later authorization checks.

This article provides a detailed description of the programming model specifications for the Human Task Manager staff resolution, first describing the default staff verb set, the structure of a verb set XML document, and the structure of a parameterized verb. The article then provides a detailed description of the staff query XML syntax for the three staff resolution plug-ins that are part of Business Process Choreographer. This is followed by a description of the staff resolution plug-in configuration parameters, and further details about the post-processor plug-in.

Before continuing with this article, you should read the first two articles in this series, which provide an introduction to Business Process Choreographer staff resolution and authorization. The third article in this series, on customization options for staff resolution, is not prerequisite for this article, but provides the motivation for the technical details described here.

Staff query verb reference

When you model human tasks in the IBM WebSphere Integration Developer task editor, you can select from a set of predefined staff query verbs, also known as people assignment criteria. These verbs are abstract staff query templates that can be used to model sophisticated authorization rules. Defining the query parameters for a verb it results in a parameterized verb embedded in the task model of your human task or business process module. This parameterized verb becomes the input for the XSLT verb mapping step that is executed during module deployment and generates the actual staff query (also known as people query) that is executed at runtime by a staff resolution plug-in against a staff repository, like an LDAP directory. For a deeper understanding of the staff resolution programming model, see Part 2.

This section points to the detailed description of the default Human Task Manager staff verbs, then describes the verb set definition XML file syntax and the parameterized verb syntax, which is the input for the XSLT mapping step. The verb set syntax is important if you want to customize or extend the predefined verb set, whereas the parameterized verb syntax is important if you want to customize XSLT mapping files.

This section includes:

  1. Predefined staff verbs
  2. Staff verb set syntax
  3. Parameterized verb syntax

A. Predefined staff verbs

The set of default staff verbs available in the task editor can be used directly, without further customization. Depending on the staff plug-in configuration (also known as people directory configuration) you choose, not all of these verbs will be supported. The "Manager of Employee" verb, for example, is not available when using the User Registry or the System plug-in.

The set of default verbs is best described in the WebSphere Process Server Information Center. Of particular interest are the bpe/staff/systemconfiguration, bpe/staff/userregistryconfiguration, or bpe/staff/sampleldapconfiguration staff plug-in configurations.

You might notice that the staff verbs to retrieve e-mail addresses are not described there. These are available only for the LDAP staff resolution plug-in, and have the same parameters as their counterparts used to resolve the user IDs. For a deeper understanding of the e-mail verb usage, see Part 2. Table 1 shows the mapping of e-mail verbs to user ID verbs.

Table 1. E-mail verbs and their standard user ID verb counterparts
E-mail verbUser ID verb
Email Address for Department MembersDepartment Members
Email Address for Group MembersGroup Members
Email Address for Group Members without Filtered UsersGroup Members without Filtered Users
Email Address for Group SearchGroup Search
Email Address for Role MembersRole Members
Email Address for UsersUsers
Email Address for Users by user IDUsers by user ID

B. Staff verb set syntax

If the set of default staff verbs does not satisfy your needs when modeling authorization rules, you can modify existing verbs or add new ones to the verb set. This section explains the structure and syntax of the verb set XML file.

The structure of the verb set XML file is fairly simple. It contains the usual XML prologue, the namespace declaration, the verb set description, and the actual verb definitions:

<?xml version="1.0" encoding="UTF-8"?>
<vs:VerbSet xmlns:vs=
  "http://www.ibm.com/schemas/workflow/wswf/plugins/staff/verbset">
  <vs:Description>verb set description</vs:Description>
  verb definition 1+
</vs:VerbSet>

A verb definition has this syntax:

<vs:DefineVerb name="verb name">
  <vs:Description>verb description</vs:Description>
  <vs:Mandatory>
    parameter definition *
  </vs:Mandatory>
  <vs:Optional>
    parameter definition *
  </vs:Optional>
</vs:DefineVerb>

The root element has an attribute, "name," which identifies the verb. This is followed by the verb description and the set of mandatory parameters. The mandatory parameter set is followed by the set of optional parameters. There can be zero to many parameters in both the mandatory and optional parameter sets. The parameter declaration has this syntax:

<vs:Parameter>
  <vs:Name>parameter name</vs:Name>
  <vs:Type>parameter type</vs:Type>
  <vs:Hint>hint text</vs:Hint> *
</vs:Parameter>

The parameter declaration is identical for optional and mandatory parameters. It contains the parameter name, data type, and a number of optional hints. The parameter type and value space corresponds to the XML schema data types; it can be of type boolean or string.

For a formal specification of the verb set XML syntax, see the XML schema.

Here is a simple example of a verb set file:

<?xml version="1.0" encoding="UTF-8"?>
<vs:VerbSet xmlns:vs=
  "http://www.ibm.com/schemas/workflow/wswf/plugins/staff/verbset">
  <vs:Description>Default Verbset</vs:Description>

  <vs:DefineVerb name='Everybody'>
    <vs:Description>Assigns all authenticated users.
Supported by sample XSLT files for:
 - LDAP
 - User Registry
 - System
    </vs:Description>
    <vs:Mandatory></vs:Mandatory>
    <vs:Optional></vs:Optional>
  </vs:DefineVerb>

  <vs:DefineVerb name='Users by user ID'>
    <vs:Description>Assigns users, given their user ID.
Supported by sample XSLT files for:
 - LDAP
 - User Registry
 - System
    </vs:Description>
    <vs:Mandatory>
      <vs:Parameter>
        <vs:Name>UserID</vs:Name>
        <vs:Type>xsd:string</vs:Type>
        <vs:Hint>%wf:process.starter%</vs:Hint>
        <vs:Hint>%wf:process.administrators%</vs:Hint>
        <vs:Hint>
          %wf:activity(-enter activity name-).readers%
        </vs:Hint>
      </vs:Parameter>
    </vs:Mandatory>
    <vs:Optional>
      <vs:Parameter>
        <vs:Name>AlternativeID1</vs:Name>
        <vs:Type>xsd:string</vs:Type>
      </vs:Parameter>
      <vs:Parameter>
        <vs:Name>AlternativeID2</vs:Name>
        <vs:Type>xsd:string</vs:Type>
      </vs:Parameter>
    </vs:Optional>
  </vs:DefineVerb>
</vs:VerbSet>

C. Parameterized verb syntax

When you finish modeling an authorization rule by selecting a staff verb and entering its parameter values in the task editor, the result is stored as part of the task model in the task or process module EAR file. This section describes the syntax of the XML snippet which is the input for the XSLT mapping step that transforms the pretty abstract parameterized verb into a set of plug-in specific staff queries. (This syntax is not identical to the corresponding XML snippet in the task model TEL file; at least the namespaces differ.) This section explains the parameterized verb syntax.

The structure of the parameterized verb XML document is very simple. It contains the usual XML prologue, the namespace declaration, the mandatory verb name and the optional list of parameters:

<?xml version="1.0" encoding="UTF-8"?>
<staff:verb xmlns:staff=
  "http://www.ibm.com/schemas/workflow/wswf/plugins/staff">
  <staff:name>verb name</staff:name>	
  <staff:parameter id="parameter ID">
    parameter value
  </staff:parameter> *
</staff:verb>

A parameter is identified by its attribute "id." The element text content is the parameter value.

For a formal specification of the parameterized verb XML syntax, see the XML schema.

Here is an example showing a parameterized verb document:

<?xml version="1.0" encoding="UTF-8"?>
<staff:verb xmlns:staff=
  "http://www.ibm.com/schemas/workflow/wswf/plugins/staff">
  <staff:name>Users by user ID</staff:name>	
  <staff:parameter id="UserID">%wf:process.starter%</staff:parameter>
  <staff:parameter id="AlternativeID1">John</staff:parameter>	
</staff:verb>

Staff query reference

The parameterized verb is the input for the XSL transformation, which maps the abstract verb into a set of staff queries that can be executed by a staff resolution plug-in. For the LDAP staff resolution plug-in, the XSL transformation additionally adapts the queries to the schema of the LDAP server to query.

During deployment of a business process or human task module, the staff plug-in configuration JNDI name of the human task points to the XSLT file that will perform the mapping. The XSL transformation generates the staff queries that are executed by the associated staff resolution plug-in at runtime. For a deeper understanding of the staff resolution programming model, see Part 2.

This section describes the syntax of the staff query XML language that is generated by the XSL transformation. You need a good understanding of this language when you customize or create new verb mapping XSLT files.

This section includes:

  1. Common syntax elements
  2. System staff resolution plug-in
  3. User registry staff resolution plug-in
  4. LDAP staff resolution plug-in

A. Common syntax elements

All staff resolution plug-ins support a common set of syntax elements. These elements differ only in the XML namespace to which they belong, since each plug-in has its own XML namespace. This section describes the common part of the plug-in syntax.

For a formal specification of the staff query XML syntax, see the corresponding XML schemas.

Staff queries structure

The enclosing query element for staff queries is the same for all staff resolution plug-ins:

<staff:staffQueries threshold="positive nonzero integer number">
  staff query element *
</staff:staffQueries>

The <staffQueries> specification can contain one or more staff query elements, with the exception of <everybody/>, <groupID/>, and <nobody/>, which are standalone queries.

For queries that return a set of user IDs, a union of the results of all queries is created, and builds the result set of user IDs. User IDs are added only once to the result set, if the same user ID is returned by a second query, it will be ignored.

All staff resolution plug-ins support a "threshold" parameter. This parameter enables you to limit the total number of users that are returned by the enclosing staff query. If the number of users that are being retrieved is larger than the threshold value, the query is aborted at this point and only the users resolved before the threshold was reached will be returned. Other users that would have qualified for this query will be ignored. In a business process context, it is normally not required to assign a large number of users to a human task. If a staff query returns a large number of users (for example more than 50), it is likely that a query is not defined in a well-contained manner. Independently of the "threshold" parameter staff repositories can impose their own limitations on the result set size. The "threshold" parameter is optional. Its value must be a positive nonzero integer number. The default value for the threshold is 2,147,483,647.

Context variables

Human Task Manager supports dynamic context in many places, such as task descriptions, task durations, and staff resolution. Context information can be taken from task input and output messages, task custom properties, and so on. Inline human tasks additionally have access to the surrounding business process context information like process variables, process custom properties, and so on. This document focuses on the dynamic context that can be used for staff resolution. Several staff queries support context variables for several of their parameters. Context variables are encapsulated in "%" signs and have this notation: %context variable%, for example: %wf:process.starter%

Single value context variables evaluate to a string that is replaced in the parameter context, for example %wf:process.starter% evaluates to sarah. Multi-value context variables like %wf:process.administrators% evaluate to a string array and the staff query element containing them will be executed many times (corresponding to the array length), each time with a different value from the result array. Be aware that this is the reason for the restricted number of multi-value context variables. Multiple multi-value context variables would result in a matrix multiplication and are not supported. Thus, the number of multi-value context variables is limited to one per staff query.

If the resolved context variable content is null, no replacement occurs and the variable name remains unchanged in the query string (including the "%" signs). Such unreplaced context variables may lead to failing staff queries, and you should check for them if your staff query fails unexpectedly. A possible reason for context variables not being replaced, is that staff resolution happens before the context information has been set. For example, the task administrator is usually resolved during the createAndStart() operation of a human task, but a custom property can only be set later for this task instance.

Human Task Manager supports the following context variables for staff resolution:

  • The task input message can be accessed via XPath expressions:

    htm:input.[messagePartName][\XPathExpression]

    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 prefixed by a backslash, to access only a specific element of the message part. If the XPath expression contains a % sign itself, it must be escaped as specified by XML (using &#37;). The input message is available during task creation (if it has been passed to the create() method), or during task start, if it has been passed only to the task start() method. It is available for all task kinds, excluding administrative tasks. Note: 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 useful toString() methods.

  • The task output message can be accessed via XPath expressions as well:

    htm:output.[messagePartName][\XPathExpression]

    The leading htm:output. is a constant delimiter, followed by the optional name of the message part to be accessed. Optionally, there can follow an XPath expression prefixed by a backslash, to access only a specific element of the message part. If the XPath expression contains a % sign itself, it must be escaped as specified by XML (using &#37;). The output message is available after it has been stored using the methods setOutputMessage() or complete(outputMessage). It is available for participating and purely human tasks. Note: 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 useful toString() methods.

  • %htm:task.administrators% is bound to the staff query result of the task instance administrators staff query. It is available during task start (first role resolved during task start). This variable is available for all task kinds.

  • %htm:task.editors% is bound to the staff query result of the task instance editors staff query. It is available during task start (third role resolved during task start). This variable is available for participating and purely human tasks.

  • %htm:task.originator% is bound to the user ID of the person who is acting as the originator of the task instance. It is available after task creation. This variable is available for all task kinds.

  • %htm:task.owner% is bound to user ID of the person who is acting as the owner of the task instance. It is available when a task is claimed or has reached an end state afterwards. This variable is available for participating and purely human tasks.

  • %htm:task.potentialInstanceCreators% is bound to the staff query result of the task template potentialInstanceCreators staff query. It is available during task creation (first role resolved during task creation). This variable is available for all task kinds.

  • %htm:task.potentialOwners% is bound to the staff query result of the potentialOwners task instance staff query. It is available during task start (second role resolved during task start). This variable is available for participating and purely human tasks.

  • %htm:task.potentialStarters% is bound to the staff query result of the task instance potentialStarters staff query. It is available during task creation (second role resolved during task creation). This variable is available for originating tasks only.

  • Task custom properties provide access to custom properties of the task via this expression:

    htm:task.property.customPropertyName

    The leading htm:task.property. is a constant delimiter, followed by the name of the custom property. Custom properties resolve to strings. Custom properties are available after they have been set for the task instance, or in all task states, when they are set on the task template. Custom properties are available for all task kinds.

  • %htm:task.readers% is bound to the staff query result of the task instance readers staff query. It is available during task start (fourth role resolved during task start). This variable is available for all task kinds.

  • %htm:task.starter% is bound to user ID of the person who is acting as the starter of the task instance. It is available after task start (fourth role resolved during task start). This variable is available for originating tasks only.

  • %htm:escalation(escalationname).receivers% is bound to the escalation receivers of the escalation with the specified name in the scope of the current task instance. It is available after the escalation with this name has reached the ESCALATED state. This variable is available for all task kinds with escalations.

  • Escalation custom properties provide access to custom properties of the escalation via the following expression:

    htm:escalation.property.customPropertyName

    The leading htm:escalation.property. is a constant delimiter, followed by the name of the custom property. Custom properties resolve to strings. Custom properties are available after they have been set for the escalation instance, or in all escalation states, when they are set on the escalation template. Custom properties are available for all task kinds with escalations.

  • %htm:escalation.receivers% is bound to the staff query result of the escalation receivers staff query of the escalation instance. It is only visible within the same escalation. It is available after the escalation has reached the ESCALATED state. This variable is available for all tasks that have escalations.

For inline human tasks that have access to the business process context, additional context variables are available:

  • wf:activity(name).editors is bound to the editors of the activity instance with the supplied name. It is available for human tasks following the activity with this name in the process model. Note: the availability in human tasks parallel to the activity with this name would be unpredictable, since parallel process branches are concurrent. The activity with this name has to be a human task (staff) activity. It is available for inline tasks of all kinds.

  • wf:activity(name).owner is bound to the owner of the activity instance with the supplied name. It is available for human tasks following the activity with this name in the process model. Note: the availability in human tasks parallel to the activity with this name would be unpredictable, since parallel process branches are concurrent. The activity with this name has to be a human task (staff) activity. It is available for inline tasks of all kinds.

  • wf:activity(name).potentialOwners is bound to the potential owners of the activity instance with the supplied name. It is available for human tasks following the activity with this name in the process model. Note: the availability in human tasks parallel to the activity with this name would be unpredictable, since parallel process branches are concurrent. The activity with this name has to be a human task (staff) activity. It is available for inline tasks of all kinds.

  • wf:activity(name).readers is bound to the readers of the activity instance with the supplied name. It is available for human tasks following the activity with this name in the process model. Note: the availability in human tasks parallel to the activity with this name would be unpredictable, since parallel process branches are concurrent. The activity with this name has to be a human task (staff) activity. It is available for inline tasks of all kinds.

  • wf:process.administrators is bound to the administrators of the current process instance. It is available during process instance creation (first role resolved during process instance creation). It is available for inline tasks of all kinds.

  • wf:process.readers is bound to the readers of the current process instance. It is available during process instance creation (second role resolved during process instance creation). It is available for inline tasks of all kinds.

  • wf:process.starter is bound to the starter of the current process instance. It is available after the process instance has been created. It is available for inline tasks of all kinds.

  • The process variables can be accessed via XPath expressions:

    wf:variable.variableName\messagePartName[\XPathExpression]

    The leading wf:variable. is a constant delimiter, followed by the variable name, a backslash, and the message part to be accessed. The message part name is mandatory for interface typed variables, and optional for data typed variables. Be aware that the message part is mandatory for single part but interface typed messages as well, and can be deduced from the variable WSDL description as described in the Programming Model document of this series. Optionally, there can follow an XPath expression prefixed by a backslash to access only a specific element of the message part. If the XPath expression contains a % sign itself, it must be escaped as specified by XML (using &#37;). The process variable is available after it has been set, for example, using an assign activity. When modeling the business process, make sure that the variable initialization happens prior to the human task invocation. It is available for inline tasks of all kinds. Note: 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 useful toString() methods.

  • The process input message can be accessed via XPath expressions:

    wf:variable.\messagePartName[\XPathExpression]

    The leading wf:variable. is a constant delimiter, followed by the name of the message part to be accessed. The message part name is mandatory for interface typed variables, and optional for data typed variables. Be aware that the message part is mandatory for single part but interface typed messages as well, and can be deduced from the variable WSDL description as described in Part 2. Optionally, there can follow an XPath expression prefixed by a backslash, to access only a specific element of the message part. If the XPath expression contains a % sign itself, it must be escaped as specified by XML (using &#37;). The process input message is available for the process administrative tasks only. All other tasks must access process variables. Note: 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 useful toString() methods.

  • Process and activity custom properties provide access to custom properties of the process or activity instance or template via the following expression:

    wf:property.customPropertyName.

    The leading wf:property. is a constant delimiter, followed by the name of the custom property. Custom properties resolve to strings. Custom properties are available after they have been set for the process or activity instance, or in all task states, when they are set on the process or activity template. They are available for inline tasks of all kinds.

Be aware that when a staff resolution result is refreshed, updates to the context variable values are not considered, but the initial values are re-used.

Simple staff queries

A set of simple staff queries is supported by all staff resolution plug-ins shipped with Business Process Choreographer. This is the set of queries that do not require access to a staff repository.

  • Everybody

    Every user that has been authenticated by WebSphere Application Server can access the work item created based on this query.

    <staff:staffQueries>	
      <staff:everybody/>	
    </staff:staffQueries>

    The threshold attribute of the <staffQueries> element is ignored by this query. No further query, such as <userID>, is supported together with the <everybody/> query.

  • Group ID

    This query assigns a whole group by its WebSphere Application Server group ID, without resolving its members. A group work item is created based on the query result.

    <staff:staffQueries>
      <staff:groupID name="group ID"/>
    </staff:staffQueries>

    The name attribute is mandatory, and can contain context variables that resolve to a single value. Expressions containing context variables must evaluate to a valid WebSphere Application Server security group ID. This query also supports WebSphere Application Server security dynamic groups added using custom JAAS login modules.

    The group ID corresponds to the following group properties, depending on the user registry you configure:

    • Local OS registry: group security name
    • LDAP registry: unique group ID
    • Custom registry: group security name

    The domain prefix is not used, independent of the user registry type.

    The threshold attribute of the <staffQueries> element is ignored by this query. No further query, such as <userID>, or even a further <groupID> is supported together with the <groupID/> query.

  • Nobody

    No user is assigned to this work item, only role inheritance applies. You will rarely need this query.

    <staff:staffQueries>	
      <staff:nobody/>	
    </staff:staffQueries>

    The threshold attribute of the <staffQueries> element is ignored by this query. No further query, such as <userID>, is supported together with the <nobody/> query.

  • Remove

    This query removes an entry from the staff query result set. It is useful to enforce the four-eyes principle. It can only be used in combination with queries that return user IDs.

    <staff:staffQueries>
      <staff:remove value="user ID to remove"/>
    </staff:staffQueries>

    The value attribute is mandatory. It can contain context variables like %htm:property.myProperty%. Multi-value context variables are supported. Expressions containing context variables must evaluate to one or more WebSphere Application Server security user IDs.

    Using this query together with a set of other queries that have reached the threshold value for the query, will reduce the number of returned user IDs, and the final number of user IDs might be below the threshold value. This behavior ensures the four-eyes principle when applied together with a dynamic set of user IDs to remove.

  • User ID

    This query represents an explicit assignment to a specific WebSphere Application Server user ID.

    <staff:staffQueries>
      <staff:userID name="valid WebSphere user ID"/>	
    </staff:staffQueries>

    The name attribute is mandatory. It can contain context variables, such as %wf:process.starter%.

    Even though this query allows a staff assignment to users by name (user ID), it is a best practice to avoid hard coding user IDs in the human task model. However, the ability to assign work items to users by ID is useful for assignments that are based on context data, for example, the process starter.

    Example:

    <staff:staffQueries>	
      <staff:userID name="Billy"/>	
      <staff:userID name="%wf:process.starter%"/>	
    </staff:staffQueries>

    The user ID corresponds to the following user properties, depending on the user registry you configure:

    • Local OS registry (Windows®): user security name (without domain prefix)
    • Local OS registry (other operating systems): user security name
    • LDAP registry: display name
    • Custom registry with "Use display name" false: user security name
    • Custom registry with "Use display name" true: display name

B. System staff resolution plug-in

The system staff resolution plug-in only supports the simple queries described above. It is not intended to be used in production, since it is not bound to any staff repository, and does not support real staff queries, but only hard coded staff assignments with context variables. However, it enables you to write simple staff business process test scenarios, without having to configure and use a staff repository.

The formal definition of the supported staff queries is available as XML schema. The XML namespace of this plug-in is defined as:

xmlns:ssys="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/system"

C. User registry staff resolution plug-in

The user registry staff resolution plug-in supports querying for users and groups that are known to the WebSphere Application Server security component, the user registry. The plug-in implementation is based on the corresponding UserRegistry interface and leverages the queries supported by this interface.

In addition to the simple queries described above, this plug-in supports the following queries:

  • <sur:user .../>
  • <sur:usersOfGroup .../>
  • <sur:search .../>

The formal definition of the supported staff queries is available as XML schema. The XML namespace of this plug-in is defined as:

xmlns:sur="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/userregistry"

The deprecated getUsersForGroup() method of the UserRegistry interface must be implemented for custom registries in order to be fully supported by the user registry staff resolution plug-in.

User query

The query to lookup and validate the user ID of a person is:

<sur:user name="user ID"/>

The attribute "name" is mandatory and can contain context variables. The number of multi-value context variables is restricted to one variable per <sur:user .../> element.

Since the returned value is identical to the value of the "name" attribute, the only advantage of this query element is to validate the user ID. The query is mainly supported to be consistent to the other Business Process Choreographer staff resolution plug-ins. For performance reasons, use the <sur:userID .../> query instead.

Users of group query

To query for the members of a group and to return their user IDs, you can use the following syntax:

<sur:usersOfGroup groupName="group name"/>

The attribute "groupName" is mandatory and can contain context variables. The number of multi-value context variables is restricted to one variable per <sur:usersOfGroup .../> element.

Search query

The user registry staff resolution plug-in also leverages the user registry functionality to search for a person or group based on a search pattern string. See the WebSphere Application Server user registry documentation for more information regarding the search pattern format.

The following query supports searching for persons or groups:

<sur:search type="user"|"group" 
            pattern="search pattern"/>

The attributes "type" and "pattern" are mandatory. The value of attribute "pattern" can contain context variables. The number of multi-value context variables is restricted to one variable per <sur:search .../> element. There is no way to specify whether subgroups are evaluated recursively or not. The default behavior depends on the user registry implementation configured for the WebSphere Application Server security component.

Query examples

The following example can be used to assign the members of a group known by the user registry to a human task authorization role:

<sur:staffQueries>
  <sur:usersOfGroup groupName="Administrators"/>
</sur:staffQueries>

A more complex example combines two user registry queries:

<sur:staffQueries threshold="30">
  <sur:usersOfGroup groupName="Administrators"/>
  <sur:search type="user" name="mi*"/>
</sur:staffQueries>

This will resolve the user IDs of all members of the "Administrators" group, and of all users with user IDs that begin with "mi".

D. LDAP staff resolution plug-in

The LDAP staff resolution plug-in enables you to utilize organizational information that is available via LDAP directories. Its queries let you retrieve, for example, all members of an LDAP group, or to retrieve specific attributes of an LDAP object such as the manager attribute of a person object.

In addition to the simple queries described above, this plug-in supports the following queries:

  • <sldap:user .../>
  • <sldap:usersOfGroup .../>
  • <sldap:search .../>
  • <sldap:intermediateResult .../>

The formal definition of the supported staff queries is available as XML schema. The XML namespace of this plug-in is defined as:

xmlns:sur="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/ldap"

Note that LDAP staff queries are not necessarily restricted to directories that are configured for the WebSphere Application Server user registry security component, although this is the recommended setup. However, the users and groups managed in the LDAP directory accessed by the LDAP staff resolution plug-in must have a counterpart in the user registry. The user IDs, group IDs, and the user to group relationships must match for the LDAP directory and the user registry.

User query

To locate people based on their distinguished name, the following query can be used:

<sldap:user dn="distinguished name of the user"
            attribute="attribute to evaluate"
            objectclass="LDAP objectclass of the queried object"/>
  • dn is a mandatory attribute that specifies the distinguished name of the LDAP object to be retrieved. The value of attribute "dn" can contain context variables. The number of multi-value context variables is restricted to one variable per <sldap:user .../> element.
  • attribute is a mandatory attribute that specifies which attribute of the LDAP object contains the value(s) to be returned.
  • objectclass is a mandatory attribute that specifies the LDAP object class of the object associated with the dn. See also "Attribute evaluation specifications" below.

Users of group query

To locate members of a group based on the group's distinguished name, the following query is available:

<sldap:usersOfGroup groupDN="distinguished name of the group"
                    recursive="yes"|"no">
  attribute evaluation specification 1+
</sldap:usersOfGroup>
  • groupDN is a mandatory attribute that specifies the distinguished name of the LDAP object to be retrieved and can contain context variables. The number of multi-value context variables is restricted to one variable per <sldap:usersOfGroup .../> element.
  • recursive is an optional attribute that specifies whether the retrieved LDAP object will be processed recursive or not; for example, whether subgroups of a group will be processed or ignored. Its value defaults to "yes".
  • The attribute evaluation specification is mandatory and enables you to define for example, which person attribute contains the userID to be returned, and which group attribute contains the member dn values. The number of specified attributes is not limited. (See also "Attribute evaluation specifications" below.)

Search query

To search for LDAP objects based on LDAP filters, the following query can be used:

<sldap:search baseDN="search root"
              filter="valid LDAP filter"
              searchScope="subtreeScope" | "onelevelScope" | "objectScope"
              recursive="yes"|"no">
  attribute evaluation specification 1+
</sldap:search>
  • baseDN is an optional attribute that specifies the LDAP sub-tree, on which the search operation is applied. Tree parent nodes or siblings of the baseDN node will not be considered. If omitted, the search is executed using the baseDN specified in the plug-in configuration. The value of attribute "baseDN" can contain context variables. The number of multi-value context variables is restricted to one variable per <sldap:search .../> element.
  • filter is a mandatory attribute that enables you to specify an LDAP search filter that is applied to all objects below the baseDN, in order to restrict the set of LDAP objects returned. The value of the attribute "filter" can contain context variables. The number of multi-value context variables is restricted to one variable per <sldap:search .../> element.
  • searchScope is an optional attribute that enables you to specify how deep to search below the baseDN:
    • objectScope only applies the filter to the object specified by the baseDN.
    • onelevelScope applies the filter to all objects at the first level under the baseDN node.
    • subtreeScope applies the filter to the entire sub-tree of the baseDN node.
    If omitted, the search is executed using the search scope specified in the plug-in configuration.
    The search scope allows you to define how many levels of the LDAP tree beneath the baseDN will be evaluated, which is orthogonal to the recursion over links (dn values). So, both kinds of nesting can be exploited in parallel.
  • recursive is an optional attribute that specifies whether the LDAP objects found will be processed recursively or not, for example whether subgroups as members of a group will be processed or ignored. Its value defaults to "yes."
  • The attribute evaluation specification is mandatory and enables you to define for example, which person attribute contains the userID to be returned, and which group attribute contains the member dn values. The number of specified attributes is not limited. (See also the "Attribute evaluation specifications" below.)

Attribute evaluation specifications

When evaluating a staff query, the user, usersOfGroup, and search queries define which LDAP objects are evaluated, whereas the attribute or result evaluation specification defines how to retrieve the query result from these objects. For each LDAP objectclass that is to be evaluated, an attribute evaluation specification must be defined, which specifies the attribute to be retrieved for objects of this class. The attribute can contain the user ID of the queried person, the dn values of the group members to be evaluated implicitly or some arbitrary string(s) in case of intermediate results.

The attribute name and the LDAP objectclass are always used as a pair with a 1-1 relationship. LDAP objects are evaluated by their objectclass. If a query retrieves an LDAP object and an attribute evaluation specification is found for its objectclass, the specified attribute will be evaluated, and added to the (intermediate) result set. If no attribute evaluation specification is found for its objectclass, then the object will be ignored. Many LDAP objects have more than one objectclass, due to objectclass inheritance. The objectclass of the attribute evaluation specification that is found first will be used. Thus, it is important in which order you declare attribute evaluation specifications.

The plug-in supports only those LDAP attributes that have one or more string values. Attributes that contain, for example, a JPEG image of the user are not supported and an exception will be thrown.

Attribute evaluation specifications are defined using the "attribute" element:

<sldap:attribute name="attribute name"
                 objectclass="LDAP object class"
                 usage="simple"|"recursive"/>
  • name is a mandatory attribute that specifies the name of the attribute to evaluate.
  • objectclass is a mandatory attribute that specifies the LDAP objectclass for this attribute. For each LDAP objectclass that is to be evaluated, an attribute specification must be defined.
  • usage is a mandatory attribute that enables you to specify how the content of this attribute has to be evaluated:
    • simple states that the attribute content will be added to the (intermediate) query result set.
    • recursive states that this attribute contains the dn values of objects that can be evaluated. These dn values will be evaluated implicitly. The plug-in retrieves the corresponding objects, checks their objectclass, and looks again for a corresponding attribute evaluation specification. If available, the attribute evaluation for this object continues recursively.
      If the query is recursive (see usersOfGroup or search queries), the number of subsequent recursions is not limited.
      If the query is non-recursive, only one level of indirection will be processed. If objects with recursive attributes are found after the first indirection, they will be ignored.

It makes sense to define more than one attribute per query if the query could return LDAP objects of more than one object class or if the query has to be evaluated recursively and during recursion, objects of different classes are to be evaluated. For the usersOfGroup query, for example, you will specify at least one attribute for the group objectclass, and another attribute for the person objectclass.

This leads to the following behavior:

  1. Recursive queries:
    1. Users of group queries:
      • If the object's target attribute is simple (person), its content will be added to the (intermediate) result set.
      • If the object's target attribute is recursive (group), its content must be a set of dn values pointing to other LDAP objects that will be resolved and treated like 1.1 (recursion).
    2. Search queries:
      A search query returns a set of objects, each of them will be processed individually, using the algorithm described in 1.1.
  2. Non recursive queries:
    1. Users of group queries:
      • If the object's target attribute is simple (person), its content will be added to the (intermediate) result set.
      • If the object's target attribute is recursive (group), its content must be a set of dn values pointing to other LDAP objects that will be resolved and treated as follows:
        • If the object's target attribute is simple (person), its content will be added to the (intermediate) result set.
        • If the object's target attribute is recursive (group), it will be ignored (no recursion).
    2. Search queries:
      A search query returns a set of objects and each of them will be processed individually using the algorithm described in 2.1.

Thus, recursive queries resolve persons, members of a group and members of subgroups, regardless of how deep they are nested. Non-recursive queries resolve persons, members of a group, but no members of subgroups.

Examples for user, usersOfGroup, and search queries

The following examples show how user, usersOfGroup, and search queries are processed:

Simple user retrieval:
<sldap:staffQueries>
  <sldap:user dn="cn=Mary Smith, ou=mydivision, o=acme, c=us" 
              objectclass="inetOrgPerson"
              attribute="uid"/>
</sldap:staffQueries>

Query evaluation sequence:

  1. Retrieve the LDAP object (Mary Smith) of which the dn value has been specified.
  2. The entry in the "uid" attribute is read and added to the result set. It is assumed that the "uid" value is identical to the WebSphere Application Server authenticated user ID.
Simple users of group retrieval:
<sldap:staffQueries>
  <sldap:usersOfGroup groupDN="cn=mygroup, o=acme, c=us" 
                      recursive="no">
    <sldap:attribute name="uid" 
                     objectclass="inetOrgPerson" 
                     usage="simple"/>
    <sldap:attribute name="member" 
                     objectclass="groupOfNames" 
                     usage="recursive"/>
  </sldap:usersOfGroup>
</sldap:staffQueries>
</wf:staff>

Query evaluation sequence:

  1. Retrieve the object (mygroup) of which the dn value has been specified.
  2. The entries in the "member" attribute are read and resolved.
  3. The resolved member objects are evaluated:
    • Objects of class "inetOrgPerson" are resolved and the content of their non-recursive attribute "uid" is added to the result set. It is assumed that the "uid" value is identical to the WebSphere Application Server authenticated user ID.
    • Objects of class "groupOfNames" (subgroups) are ignored, since the query is non-recursive.
Recursive users of group retrieval:
<sldap:staffQueries>
  <sldap:usersOfGroup groupDN="cn=mygroup, o=acme, c=us" 
                      recursive="yes">
    <sldap:attribute name="uid" 
                     objectclass="inetOrgPerson" 
                     usage="simple"/>
    <sldap:attribute name="member" 
                     objectclass="groupOfNames" 
                     usage="recursive"/>
  </sldap:usersOfGroup>
</sldap:staffQueries>

Query evaluation sequence:

  1. Retrieve the object (mygroup) whose dn value has been specified.
  2. The entries in the "member" attribute are read and resolved.
  3. The resolved member objects are evaluated:
    • Objects of class "inetOrgPerson" are resolved and the content of their non-recursive attribute "uid" is added to the result set. It is assumed that the "uid" value is identical to the WebSphere Application Server authenticated user ID.
    • Objects of class "groupOfNames" (subgroups) are also resolved, since the query is recursive. The subgroup members are treated as in step 2. This algorithm repeats recursively until all newly resolved subgroups contain no further subgroups.
Simple search:
<sldap:staffQueries>
  <sldap:search baseDN="ou=mydivision, o=acme, c=us" 
                filter="cn=*"
                searchScope="onelevelScope"
                recursive="no">
    <sldap:attribute name="uid" 
                     objectclass="inetOrgPerson" 
                     usage="simple"/>
    <sldap:attribute name="member" 
                     objectclass="groupOfNames" 
                     usage="recursive"/>
  </sldap:search>
</sldap:staffQueries>

Query evaluation sequence:

  1. Retrieve the LDAP objects that are below the baseDN and to which the filter applies. In this example, these are all objects at the first tree level under the organizational unit "mydivision".
  2. All objects found are resolved and evaluated.
    • Objects of class "inetOrgPerson" are resolved and the contents of their non-recursive attribute "uid" are added to the result set. It is assumed that the "uid" value is identical to the WebSphere Application Server authenticated user ID.
    • Objects of class "groupOfNames" are resolved and evaluated, and the objects where a dn value is found in the member attribute (group members) are resolved and evaluated as follows:
      • Objects of class "inetOrgPerson" are resolved and the content of their non-recursive attribute "uid" is added to the result set.
      • Objects of class "groupOfNames" are subgroups and are therefore ignored.
Recursive search:
<sldap:staffQueries threshold="30">
  <sldap:search baseDN="ou=mydivision, o=acme, c=us" 
                filter="cn=*"
                searchScope="onelevelScope"
                recursive="yes">
    <sldap:attribute name="uid" 
                     objectclass="inetOrgPerson" 
                     usage="simple"/>
    <sldap:attribute name="member" 
                     objectclass="groupOfNames" 
                     usage="recursive"/>
  </sldap:search>
</sldap:staffQueries>

Query evaluation sequence:

  1. Retrieve the LDAP objects that are below the baseDN, and to which the filter applies. In this example, these are all objects at the first tree level under the organizational unit "mydivision".
  2. All found objects are resolved and evaluated:
    • Objects of class "inetOrgPerson" are resolved and the content of their non-recursive attribute "uid" is added to the result set. It is assumed that the "uid" value is identical to the WebSphere Application Server authenticated user ID.
    • Objects of class "groupOfNames" (groups/subgroups) are resolved and evaluated, and the objects where a dn value is found in the member attribute (group members) are resolved and evaluated as in step 2. This algorithm repeats recursively until all newly resolved subgroups have no further subgroups.

Queries of type "intermediateResult"

For some queries, the wanted result cannot be retrieved with a single LDAP query. To get the user ID of the manager of the process starter, for example, first the manager dn has to be retrieved from the LDAP object representing the process starter, and a second LDAP query resolves the manager's user ID.

The query type intermediateResult supports the specification of such queries. It encapsulates a single query of type <sldap:user .../>, <sldap:usersOfGroup .../>, or <sldap:search .../>, and stores the result in a buffer that can be used like a context variable in subsequent queries. The result of an intermediateResult query element is not stored in the global query result set, but only in this context variable.
The result of the query encapsulated by an intermediateResult must be a set of strings. No other kind of result objects can be used as a context variable.

The intermediateResult is defined as:

<sldap:intermediateResult name="variable name"
                          threshold="positive nonzero integer number"
  query of type user, usersOfGroup or search
</sldap:intermediateResult>
  • name is a mandatory attribute that specifies the name of the context variable, in which the intermediate result will be stored. This variable is only valid inside the <sldap:staffQueries> element where it is declared, and only after its declaration. The name of the context variable must not contain any "%" signs. In case of name collisions with context variable resolved by the Human Task Manager, the intermediate result overrides any "normal" context variables with the same name.
  • threshold is an optional attribute that allows you to limit the number of items in the context variable string set. If the attribute is not specified, the value of the threshold attribute of the <sldap:staffQueries> element is used (it defaults to 2,147,483,647 if not defined there either).
  • The actual query must be of type <sldap:user .../>, <sldap:usersOfGroup .../>, or <sldap:search .../> and it must return a set of strings. The number of specified queries is limited to exactly one.
How to retrieve the manager of the process starter:
<sldap:staffQueries>
  <sldap:intermediateResult name="myManager">
    <sldap:search baseDN="ou=mydivision, o=acme, c=us" 
                  filter="uid=%wf:process.starter%"
                  searchScope="onelevelScope"
                  recursive="no">
      <sldap:attribute name="manager" 
                       objectclass="inetOrgPerson" 
                       usage="simple"/>
    </sldap:search>
  </sldap:intermediateResult>
  <sldap:user dn="%myManager%" 
              attribute="uid" 
              objectclass="inetOrgPerson"/>
</sldap:staffQueries>

Query evaluation sequence:

  • The dn value of the manager of the process starter is retrieved. It is assumed that the "manager" attribute of every person contains the dn value of her manager.
  • The query result is stored in the context variable "myManager". It contains the manager's dn value.
  • The actual query result is retrieved by the user query, and contains the manager's user ID. The intermediate result "myManager" is used like any normal context variable. It is assumed that the "uid" attribute of every person contains the WebSphere Application Server authenticated user ID.

Staff plug-in configuration parameters

This section describes the parameters needed to create staff plug-in configurations in the WebSphere Application Server administration console. WebSphere Process Server comes with four default staff plug-in provider configurations, which are set up during the installation process:

  • The configuration bpe/staff/systemconfiguration is available for the system staff resolution plug-in, but not intended for production environments.
  • The bpe/staff/everybodyconfiguration is based on the same plug-in, and maps every staff verb to an everybody query result. It is intended for test purposes only.
  • The bpe/staff/userregistryconfiguration runs out of the box (when WebSphere Application Server security is enabled), and is set up for the user registry plug-in.
  • The bpe/staff/sampleldapconfiguration is configured for the LDAP plug-in. It is just a sample, since the connection parameters will not fit your environment in most cases. You should create your own configuration for the LDAP plug-in provider that connects to your LDAP server and eventually uses your own customized copy of the LDAP mapping XSLT file in order to match your LDAP schema.

For a better understanding of the staff resolution plug-ins, staff plug-in provider, and staff plug-in configurations, see Part 2.

This section includes:

  1. System staff resolution plug-in
  2. User registry staff resolution plug-in
  3. LDAP staff resolution plug-in

A. System staff resolution plug-in

This plug-in has no configuration parameters.

B. User registry staff resolution plug-in

The User Registry plug-in has no configuration parameters.

However, it leverages WebSphere Application Server user registry settings. It exploits information about the user registry configured for WebSphere Application Server global security (the class implementing the UserRegistry interface). For custom registries, it also considers the configuration parameter UseDisplayName value, in order to return the user registry parameter as query result that corresponds to the caller principal name.

C. LDAP staff resolution plug-in

The LDAP staff resolution plug-in requires several configuration parameters that can be set using the WebSphere Application Server administration console. Staff plug-in configurations are available in the WebSphere administrative console under Resources : Staff plug-in provider. In this panel, you can click on the LDAP staff plug-in provider, then select Staff plug-in configuration to get the list of staff plug-in configurations available for the plug-in provider you selected. After selecting the configuration of your choice, you can access its custom properties using the Custom properties link in the right of this screen.
You must not use the Custom properties link exposed by the staff plug-in provider panel, but the link on the staff plug-in configuration screen.

The plug-in connects to the LDAP server using a JNDI connection; most configuration parameters are used to set up this connection. The configuration parameters supported by this plug-in are:

  • AuthenticationAlias is an optional parameter. When not set, an anonymous connection to the LDAP server is opened. This parameter represents the authentication alias used to connect to the LDAP server. The alias must have been previously defined in the WebSphere Application Server administration console under Security : JAAS Configuration : J2C Authentication Data. For example: "mycomputer/My LDAP Alias".
  • AuthenticationType is an optional parameter. By default, the logon will be anonymous if the AuthenticationAlias is not set; otherwise it will use simple authentication. To establish an SSL connection to the LDAP server, no plug-in custom property is needed. The SSL connection setup between WebSphere Application Server and your LDAP server is handled by WebSphere Application Server with the usual SSL settings.
  • BaseDN is a mandatory parameter that defines the default base DN for all LDAP search operations; for example, "o=acme, c=us." You can override this parameter for every search query.
  • CasesentivenessForObjectclasses is an optional parameter that determines whether the objectclass name comparison for LDAP objects is made case-sensitive or not. By default, the comparison is case sensitive, which means that inetOrgPerson and inetorgperson are treated as different classes.
  • ContextFactory is a mandatory parameter that sets the JNDI context factory Java class used to establish the JNDI connection to the LDAP server, for example, "com.sun.jndi.ldap.LdapCtxFactory".
  • ProviderURL is a mandatory parameter that sets the URL pointing to the LDAP/JNDI directory server and port. The usual JNDI syntax ldap://hostname:port applies here, for example "ldap://localhost:389".
  • SearchScope is a mandatory parameter that defines the default search scope for LDAP search operations. Only the values "objectScope", "onelevelScope" and "subtreeScope" are supported. You can override this parameter for every search query.
  • additionalParameterName1-5 together with additionalParameterValue1-5 enable you to set arbitrary additional JNDI properties for the connection to the LDAP server. With these optional configuration parameters, up to five JNDI parameters can be specified as name-value pairs.

Staff query result post-processor plug-in

The staff resolution post-processor plug-in offers you the possibility to perform workload balancing for staff resolution results performed by a staff resolution plug-in, or to even perform full staff resolution with the post-processor.

Part 3 of this series and the WebSphere Process Server Information Center describe how to create a post-processor plug-in.
The reference documentation is also available in the Information Center, or as JavaDoc in the web directory of your WebSphere Process Server installation, if you chose to install the documentation.

Use these direct links to the WebSphere Process Server Information Center for direct pointers to key information:


XML schema specifications

This section includes:

  1. Staff verb set XML schema
  2. Parameterized verb XML schema
  3. System staff resolution plug-in XML schema
  4. User registry staff resolution plug-in XML schema
  5. LDAP staff resolution plug-in XML schema

A. Staff verb set XML schema

The staff query verb set is used by the WebSphere Integration Developer task editor to render the screen where you define authorization rules by parameterizing staff verbs:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema 
  targetNamespace="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/verbset" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:vs="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/verbset"
  xmlns="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/verbset"
  attributeFormDefault="unqualified" 
  elementFormDefault="qualified">

  <xsd:element name="VerbSet">
    <xsd:annotation>
      <xsd:documentation xml:lang="en-US">
        Root element
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Description" type="xsd:string" minOccurs="0"/>
        <xsd:element ref="DefineVerb" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
    <xsd:key name="Verb">
    	<xsd:selector xpath="./vs:DefineVerb"></xsd:selector>
    	<xsd:field xpath="@name"></xsd:field>
    </xsd:key>
  </xsd:element>

  <xsd:element name="DefineVerb">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Description" type="xsd:string" minOccurs="0"/>
        <xsd:element name="Mandatory">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element ref="Parameter" minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
        <xsd:element name="Optional">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element ref="Parameter" minOccurs="0" maxOccurs="unbounded"/>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
      <xsd:attribute name="name" use="required">
      	<xsd:simpleType>
      		<xsd:restriction base="xsd:string">
      			<xsd:minLength value="1"></xsd:minLength>
      		</xsd:restriction>
      	</xsd:simpleType>
      </xsd:attribute>
    </xsd:complexType>
    <xsd:key name="Parameter">
      <xsd:selector xpath=
        "./vs:Mandatory/vs:Parameter|./vs:Optional/vs:Parameter"/>
      <xsd:field xpath="vs:Name"/>
    </xsd:key>
  </xsd:element>

  <xsd:element name="Parameter">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Name" type="xsd:NCName"/>
        <xsd:element name="Type" type="dataType"/>
        <xsd:element name="Hint" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>

  <xsd:simpleType name="dataType">
    <xsd:restriction base="xsd:Name">
      <xsd:enumeration value="xsd:boolean"/>
      <xsd:enumeration value="xsd:string"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

B. Parameterized verb XML schema

The parameterized verb is the input document for the XSLT verb mapping.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  targetNamespace="http://www.ibm.com/schemas/workflow/wswf/plugins/staff" 
  attributeFormDefault="unqualified" 
  elementFormDefault="qualified" 
  xmlns="http://www.ibm.com/schemas/workflow/wswf/plugins/staff">

  
  <xsd:element name="verb">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="name" type="xsd:string"/>
        <xsd:element name="parameter" minOccurs="0" maxOccurs="unbounded">
          <xsd:complexType>
            <xsd:simpleContent>
              <xsd:extension base="typeUnion">
                <xsd:attribute name="id" type="xsd:string"/>
              </xsd:extension>
            </xsd:simpleContent>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  
  
  <xsd:simpleType name="typeUnion">
    <xsd:union memberTypes="xsd:string xsd:boolean"/>
  </xsd:simpleType>

</xsd:schema>

C. System staff resolution plug-in XML schema

The system staff resolution plug-in enables you to define simple static staff assignments. It is not intended for production and only supports simple staff queries:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/system"
  xmlns="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/system"
  version="1.0"
  attributeFormDefault="unqualified"
  elementFormDefault="qualified">


  <xsd:element name="staffQueries">
    <xsd:complexType>
      <xsd:choice>
        <xsd:element name="everybody" type="tEverybody"/>
        <xsd:element name="groupID" type="tGroupID"/>
        <xsd:element name="nobody" type="tNobody"/>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="remove" type="tRemove"/>
          <xsd:element name="userID" type="tUserID"/>
        </xsd:choice>
      </xsd:choice>
      <xsd:attribute 
        name="threshold" type="xsd:positiveInteger" default="2147483647" use="optional">
        <xsd:annotation>
          <xsd:documentation xml:lang="en-US">
            Limits the number of returned user ID values.
          </xsd:documentation>
        </xsd:annotation>
      </xsd:attribute>
    </xsd:complexType>
  </xsd:element>

  <!-- Queries -->
  <xsd:complexType name="tEverybody"/>

  <xsd:complexType name="tGroupID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a group ID (name) as it is contained in the WebSphere Application 
          Server JAAS subject group membership list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tNobody"/>

  <xsd:complexType name="tRemove">
    <xsd:attribute name="value" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere Application Server 
          security user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tUserID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere Application Server 
          security user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>
</xsd:schema>

D. User registry staff resolution plug-in XML schema

The user registry staff resolution plug-in enables you to define staff assignments using the WebSphere Application Server user registry as staff repository. It supports the staff queries "everybody", "groupID" "nobody", "remove", "search", "user", "userID", and "usersOfGroup":

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/userregistry"
  xmlns="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/userregistry"
  version="1.0"
  attributeFormDefault="unqualified"
  elementFormDefault="qualified">

  <xsd:element name="staffQueries">
    <xsd:complexType>
      <xsd:choice>
        <xsd:element name="everybody" type="tEverybody"/>
        <xsd:element name="groupID" type="tGroupID"/>
        <xsd:element name="nobody" type="tNobody"/>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="remove" type="tRemove"/>
          <xsd:element name="search" type="tSearch"/>
          <xsd:element name="user" type="tUser"/>
          <xsd:element name="userID" type="tUserID"/>
          <xsd:element name="usersOfGroup" type="tUsersOfGroup"/>
        </xsd:choice>
      </xsd:choice>
      <xsd:attribute
        name="threshold" type="xsd:positiveInteger" default="2147483647" use="optional">
        <xsd:annotation>
          <xsd:documentation xml:lang="en-US">
            Limits the number of returned user ID values.
          </xsd:documentation>
        </xsd:annotation>
      </xsd:attribute>
    </xsd:complexType>
  </xsd:element>

  <!-- Queries -->
  <xsd:complexType name="tEverybody"/>

  <xsd:complexType name="tGroupID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a group ID (name) as it is contained in the WebSphere Application 
          Server JAAS subject group membership list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tNobody"/>

  <xsd:complexType name="tRemove">
    <xsd:attribute name="value" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere Application Server 
          security user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tSearch">
    <xsd:attribute name="type" use="required" type="tType"/>
    <xsd:attribute name="pattern" use="required" type="xsd:string">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          UserRegistry search pattern.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>
    
  <xsd:complexType name="tUser">
    <xsd:attribute name="name" use="required" type="xsd:string">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Name of the user.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tUserID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tUsersOfGroup">
    <xsd:attribute name="groupName" use="required" type="xsd:string">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Name of the group.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <!-- Types -->
  <xsd:simpleType name="tType">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="user"/>
      <xsd:enumeration value="group"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

E. LDAP staff resolution plug-in XML schema

The LDAP staff resolution plug-in enables you to define staff assignments based on LDAP directories. It supports the staff queries "everybody", "groupID" "nobody", "remove", "search", "user", "userID", "usersOfGroup", and "intermediateResult":

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
  targetNamespace="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/ldap"
  xmlns="http://www.ibm.com/schemas/workflow/wswf/plugins/staff/ldap"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  version="1.0" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  
  
  <xsd:element name="staffQueries">
    <xsd:complexType>
      <xsd:choice>
        <xsd:element name="everybody" type="tEverybody"/>
        <xsd:element name="groupID" type="tGroupID"/>
        <xsd:element name="nobody" type="tNobody"/>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="intermediateResult" type="tIntermediateResult"/>
          <xsd:element name="remove" type="tRemove"/>
          <xsd:element name="search" type="tSearch"/>
          <xsd:element name="user" type="tUser"/>
          <xsd:element name="userID" type="tUserID"/>
          <xsd:element name="usersOfGroup" type="tUsersOfGroup"/>
        </xsd:choice>
      </xsd:choice>
      <xsd:attribute 
        name="threshold" type="xsd:positiveInteger" use="optional" default="2147483647">
        <xsd:annotation>
          <xsd:documentation xml:lang="en-US">
            Limits the number of returned user ID values.
          </xsd:documentation>
        </xsd:annotation>
      </xsd:attribute>
    </xsd:complexType>
  </xsd:element>
  
  <!-- Queries -->
  <xsd:complexType name="tEverybody"/>

  <xsd:complexType name="tGroupID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a group ID (name) as it is contained in the WebSphere Application 
          Server JAAS subject group membership list.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tIntermediateResult">
    <xsd:choice>
      <xsd:element name="search" type="tSearch"/>
      <xsd:element name="user" type="tUser"/>
      <xsd:element name="usersOfGroup" type="tUsersOfGroup"/>
    </xsd:choice>
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Name of the intermediate result.
          Can be referenced in subsequent queries as variable
          like e.g. filter="cn=%var%".
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="threshold" type="xsd:string" use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Limits the number of returned intermediateResult values.
          When not set, the value of the threshold attribute
          from the element <staffQueries> (or its default)
          will be used.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>
  
  <xsd:complexType name="tNobody"/>
  
  <xsd:complexType name="tRemove">
    <xsd:attribute name="value" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere Application Server 
          security user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tSearch">
    <xsd:sequence>
      <xsd:element name="attribute" type="tAttribute" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="baseDN" type="xsd:string" use="optional">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Startpoint distinguished name (dn) for the search.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="filter" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          LDAP search filter.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="recursive" type="tRecursive" use="optional" default="yes">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Defines whether the result shall be evaluated recursive or not.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="searchScope" type="tSearchScope" use="optional"/>
  </xsd:complexType>

  <xsd:complexType name="tUser">
    <xsd:attribute name="dn" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Distinguished name (dn) of the user.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="attribute" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Attribute containing the user ID of this user.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="objectclass" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          LDAP objectclass of the user object.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <xsd:complexType name="tUserID">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Must be a (or resolve to one or more) valid WebSphere user ID.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>
  
  <xsd:complexType name="tUsersOfGroup">
    <xsd:sequence>
      <xsd:element name="attribute" type="tAttribute" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="groupDN" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Distinguished name (dn) of the group.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="recursive" type="tRecursive" use="optional" default="yes">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Defines whether the result shall be evaluated recursive or not.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
  </xsd:complexType>

  <!-- Result evaluation specification -->
  <xsd:complexType name="tAttribute">
    <xsd:attribute name="name" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Name of the LDAP attribute to evaluate.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="objectclass" type="xsd:string" use="required">
      <xsd:annotation>
        <xsd:documentation xml:lang="en-US">
          Valid LDAP objectclass.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:attribute>
    <xsd:attribute name="usage" type="tUsage" use="required"/>
  </xsd:complexType>

  <!-- Types -->
  <xsd:simpleType name="tRecursive">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="yes"/>
      <xsd:enumeration value="no"/>
    </xsd:restriction>
  </xsd:simpleType>
  
  <xsd:simpleType name="tSearchScope">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="subtreeScope"/>
      <xsd:enumeration value="onelevelScope"/>
      <xsd:enumeration value="objectScope"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="tUsage">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="recursive"/>
      <xsd:enumeration value="simple"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Conclusion

Human Task Manager provides powerful support for human beings that interact with Web services and business processes. Its instance- and business context-based authorization model for business processes and human tasks enables you to model sophisticated authorization rules, such as the four-eyes principle in review or approval processes. Staff resolution is the basis for assignments of people to various roles for later authorization checks.

This article offered a detailed description of the staff resolution queries supported by the various staff resolution plug-ins available with Business Process Choreographer, and provided the details, pointers, and references you need when customizing Human Task Manager staff resolution.

This series described the concepts, architecture, and programming model for Human Task Manager authorization and staff resolution (Part 1 and 2), the customization options for Human Task Manager staff resolution (Part 3), provided the detailed specifications you need when customizing it (Part 4).

More in this series

Part 1: Understanding the concepts and components of staff resolution

Part 2: Understanding the programming model for staff resolution

Part 3: Customization options for staff resolution

Acknowledgements

I would like to thank my colleagues Thomas Bernhardt, Gabriel Dermler, and Hans Schoen for their help in preparing this article.


Download

DescriptionNameSize
Code sampleStaffResRef.zip53 KB

Resources

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=283378
ArticleTitle=Authorization and staff resolution in Business Process Choreographer: Part 4: Staff resolution specifications and reference guide
publish-date=01232008