About the staff service

With Business Process Choreographer you can separate the logic of your business processes and human tasks from the staff resolution. Staff queries are resolved using a plug-in that is specific to the directory service. The basic aspects of using the staff service are described below:

For detailed information on the staff resolution plug-ins, refer to the Process Choreographer: Staff Resolution Architecture, the Process Choreographer: Programming Model for Staff Resolution, and the Process Choreographer: Staff Resolution Parameter Reference White papers in WebSphere Business Process Choreographer

Staff query and staff service concept

Use WebSphere Integration Developer to define staff queries for the staff support service. Staff queries are based on staff query templates, staff verbs, and are associated with the roles foreseen for human tasks and business processes, such as ProcessStarter and PotentialOwners.

A staff verb is identified by a unique name and includes a set of query parameters. The parameterized staff verb is transformed at application deployment time to determine a repository-specific staff query. This is used during execution of a business process or human task to retrieve the identities of users from a user repository.

Every business process or human task is associated with a specific staff plug-in configuration by its JNDI name. The configuration is extracted at deployment time from the process or task definition, and is used to map every staff verb found to a repository specific staff query. The mapping is governed by an XSL transformation file which takes a staff verb as input and produces the corresponding repository-specific query as output.

By default, three staff plug-in providers are included, representing different user repository options:
  • The LDAP staff plug-in provider is used to generate staff queries which can be executed against an LDAP server.
  • The user registry staff plug-in provider is used to generate staff queries which can be executed against the WebSphere Application Server user registry.
  • The system staff plug-in provider is not associated with a user repository. Instead, it returns user identities that are derived directly from the staff verb parameters. This plug-in provider is intended for testing and prototyping purposes.
Each of the above staff plug-in providers is associated with at least one configuration. In particular, a configuration specifies an XSL transformation file that performs the mapping between staff verbs and staff queries that are specific to the repository. The following transformation files are provided by default:
  • The LDAPTransformation.xsl file maps of staff verbs to LDAP-specific staff queries which can be executed via an JNDI interface.
  • The UserRegistryTransformation.xsl file maps staff verbs to staff queries that are specific to the WebSphere user registry.
  • The SystemTransformation.xsl file maps staff verbs to the actual user IDs specified in the verbs. It does not require a real user repository.
  • The EverybodyTransformation.xsl file maps all staff verbs to the default result "everybody". It does not require a real user repository.

Implementing a staff query

The following example summarizes the steps involved in implementing a staff query:
  1. Using WebSphere Integration Developer, a modeler associates a newly created task with the staff plug-in configuration bpe/staff/sampleldapconfiguration.
  2. Using WebSphere Integration Developer, the modeler associates the roles for the task with corresponding staff verbs, for example, PotentialOwners is associated with the staff verb "Group Members" including the parameters :
    • "GroupName" set to the value "cn=group1,dc=mycomp,dc=com"
    • "IncludeSubgroups" set to the value "true"
  3. In the context of the task, WebSphere Integration Developer stores the verb definition as an XML snippet:
    <verb>
          <name>Group Members</name>
          <parameter id="GroupName">cn=group1,dc=mycomp,dc=com</parameter>
          <parameter id="IncludeSubgroups">true</parameter>
    </verb>
  4. When the task is deployed in WebSphere Application Server, the staff support service establishes that the LDAP staff plug-in provider bpe/staff/sampleldapconfiguration is to be used. The associated LDAPTransformation.xsl file is used to transform the staff verb into an LDAP-specific query, which is stored internally.

Staff query verb set

The staff support service accepts queries in an abstract form that is independent of the user repository infrastructure. Both the process editor and the task editor have a set of predefined staff verbs that can be used when you model processes and tasks. These verbs are contained in the VerbSet.xml file. This file is installed with WebSphere Integration Developer.

The individual staff resolution plug-ins and the XSLT mapping files do not support all of the verbs. The Manager of Employee verb, for example, is not available if you use the user registry or the system plug-in. You can modify the set of staff query verbs. Make your changes to a copy of the file. Ensure that the copied file has a different file name.

The following predefined set of verbs is available. For information on the parameters that can be used with each of the verbs, see Predefined staff verbs and their parameters.

Department Members
Use this verb to define a query to retrieve the members of a department. The retrieved users belong to any of the specified departments (DepartmentName, AlternativeDepartmentName1, or AlternativeDepartmentName2). This verb is supported by the LDAP plug-in. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Everybody
Use this verb to assign a work item to every user authenticated by the WebSphere Process Server. This verb is supported by the system, user registry, and LDAP plug-ins.
Group Members
Use this verb to define a query to retrieve the members of up to three groups. The retrieved users belong to any of the specified groups (GroupName, AlternativeGroupName1, or AlternativeGroupName2). This verb is supported by the user registry and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Group Members without Named Users
Use this verb to define a query to retrieve the members of a group except for explicitly named users of that group. One or more members can be specified for exclusion as a comma separated list. This verb is supported by the user registry and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Group Members without Filtered Users
Use this verb to define a query to retrieve the members of a group except for a set of users defined by an LDAP search filter. This verb is supported by the LDAP plug-in. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Group Search
Use this verb to search for a group based on an attribute match and to retrieve the members of the group. This verb is supported by the user registry and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Manager of Employee
Use this verb to retrieve the manager of a person using the person's name. This verb is supported by the LDAP plug-in. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Manager of Employee by user ID
Use this verb to retrieve the manager of a person using the person's user ID. This verb is useful in combination with context queries. This verb is supported by the LDAP plug-in. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Native Query
Use this verb to define a native query based on directory-specific parameters. This verb is supported by the user registry and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Nobody
Use this verb to deny normal users access to the work item; For inline tasks, only the business process administrator and business process system administrator have access. For standalone tasks, only the human task administrator and human task system administrator have access. Depending on the API used, the authorized J2EE administrator will be different. For the business process API this will be the BPESystemAdministrator user, for the human task API this will be the TaskSystemAdministrator user. This verb is supported by the system, user registry, and LDAP plug-ins.
Person Search
Use this verb to search for a person based on an attribute match. This verb is supported by the user registry and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Role Members
Use this verb to retrieve the users associated with a staff repository role. The retrieved users belong to any of the specified roles (RoleName, AlternativeRoleName1, or AlternativeRoleName2). This verb is supported by the LDAP plug-in. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Users
Use this verb to define a staff query for a user who is known by name. It is not recommended that you hard code user names in process templates. This verb is useful for testing purposes. This verb is supported by the system, user registry, and LDAP plug-ins. You might need to customize the default mapping XSLT file to match the LDAP schema of your organization.
Users by user ID
Use this verb to define a staff query for a user whose user ID is known. Even though it is not recommended that you hard code user IDs in process and task templates, this verb is useful in combination with context queries, for example:
User [username='%wf:process.starter%']
This verb is useful for testing purposes. This verb is supported by the system, user registry, and LDAP plug-ins.

Repository-specific staff queries

The XSL transformation file that is associated with a staff plug-in configuration is used to generate staff queries that are specific to a particular repository. Each query can be executed by the respective staff plug-in to obtain a list of user IDs. The predefined queries which are available to a staff plug-in corresponds to the calls which can be executed by the plug-in and are therefore fixed.

Based on predefined queries, more complex queries can be formed using the following mechanisms:
  • A union of query results implies that the user IDs returned by the individual queries will be added to the current result list of user identities. For example: The LDAP staff plug-in allows, among others, for predefined queries of the following types:
    The list of user IDs for the group members of a specified group:
    <sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
    ...
    </sldap:usersOfGroup>
    The user ID of a specified user:
    <sldap:user dn="uid=user1,dc=mycomp" .../>
    A complex query can be constructed for the list of user IDs for the members of the specified group, plus the identity of the specified user:
    <sldap:staffQueries>
         <sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
        ...
        </sldap:usersOfGroup>
        <sldap:user dn="uid=user1,dc=mycomp" .../>
    </sldap:staffQueries>
  • A difference of query results implies that user IDs returned by a <remove> query will be removed from the current result list. For example, removing "user1" from the list of IDs retrieved for the specified group members:
    <sldap:staffQueries>
         <sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
        ...
        </sldap:usersOfGroup>
        <sldap:remove value="user1"/>
    </sldap:staffQueries>
  • Referencing query results implies that the results obtained from one query are used to influence the behavior of in a subsequent query. For example, in the following snippet, two queries are performed. First, the value of the "manager" attribute in the LDAP entry for the user "uid=user1,…" is retrieved and saved in an intermediate variable "supervisor", which is then used to look up the manager's LDAP entry and retrieve the associated user identity.
    <sldap:staffQueries>
           <sldap:intermediateResult name="supervisor">
             <sldap:user dn="uid=user1,dc=mycomp" attribute="manager" ... />
           </sldap:intermediateResult>
          <sldap:user dn="%supervisor% .../>
        </sldap:staffQueries>
Staff queries constructed according to above three combination rules can be executed by the staff plug-ins. For a detailed description of all predefined staff queries for each of the supported staff plug-ins and more examples of combining them consult the Process Choreographer: Staff Resolution Parameter Reference White papers in WebSphere Business Process Choreographer.

Staff verb XSL transformation files

The XSL transformation file specified for a staff plug-in configuration defines the mapping between staff verbs and repository-specific staff queries. Every staff plug-in configuration is expected to have its own XSL transformation file.

The default transformation files are:
  • LDAPTransformation.xsl for the LDAP staff provider plug-in
  • UserRegistryTransformation.xsl for the user registry staff provider plug-in
  • SystemTransformation.xsl and EverybodyTransformation.xsl for the system staff provider plug-in
These transformation files map the predefined set of staff verbs to corresponding simple and composite repository-specific queries. These files are located in the install_root/ProcessChoreographer/Staff directory.

The transformation files assume certain semantics for staff verbs and their execution using generated repository-specific staff queries. If other semantics are required, the mapping in the transformation file must be changed accordingly.

For example, the LDAP staff plug-in comes with a predefined staff verb:
<staff:verb>
		<staff:name>Manager of Employee</staff:name>
   <staff:parameter id="EmployeeName">
          uid=anEmployeeName,cn=users,dc=ibm,dc=com
   </staff:parameter>
</staff:verb>
This is mapped by the LDAPTransformation.xsl file to an LDAP query:
<sldap:staffQueries> 
     <sldap:intermediateResult name="supervisor">
     <sldap:user dn="anEmployeeName" attribute="manager" 
                                objectclass="inetOrgPerson"/>
     </sldap:intermediateResult>
     <sldap:user dn="%supervisor%" attribute="uid" objectclass="inetOrgPerson"/>
</sldap:staffQueries>
Which explicitly assumes that the LDAP DN of the supervisor is stored in the employee's attribute "manager". If that the verb is to have different semantics, for example, if the supervisor should come from the LDAP attribute "teacher". Then the LDAP specific query must be changed accordingly:
<sldap:staffQueries> 
     <sldap:intermediateResult name="supervisor">
     <sldap:user dn="anEmployeeName" attribute="teacher" 
                          objectclass="inetOrgPerson"/>
     </sldap:intermediateResult>
     <sldap:user dn="%supervisor%" attribute="uid" objectclass="inetOrgPerson"/>
</sldap:staffQueries>
The means to achieve this is to adapt the LDAPTransformation.xsl file accordingly:
  <xsl:template name="ManagerOfEmployee">
      <sldap:staffQueries>...
      <sldap:intermediateResult>
           <xsl:attribute name="name">supervisor</xsl:attribute>
           <sldap:user>
                 <xsl:attribute name="dn">
                     <xsl:value-of select="staff:parameter[@id='EmployeeName']"/>
                 </xsl:attribute>
                 <xsl:attribute name="attribute">teacher</xsl:attribute>
                 ...
           </sldap:user>
      </sldap:intermediateResult>
      <sldap:user>
            <xsl:attribute name="dn">%supervisor%</xsl:attribute>
            ...
      </sldap:user>
      </sldap:staffQueries>
</xsl:template>
You can get an deeper understanding of the mapping behavior by viewing the default transformation files. The semantics of the default transformations are described in Staff query verb set.

Using task and process context variables in staff verbs

In certain staff verbs, you can use business process and human task context variables as parameter values. This enables the staff support service to resolve staff verbs at runtime, based on information supplied by the contexts. For example, the staff verb:
<verb>
<name>Users by user ID</staff:name>
	<parameter id="UserID">%htm:input.\name%</staff:parameter>
</verb>
specifies as a parameter, the task context variable htm:input.\name, which denotes the "name" part of the input message received by the task when it is initiated. The staff support service dynamically replaces the context variable with the actual task context value.

For a description of the verbs and the parameters in which you can use context variables, see Predefined staff verbs and their parameters.

E-mail verb set

The e-mail verb set in WebSphere Integration Developer is for e-mail notifications for task escalations. These e-mail verbs are transformed during modeling and deployment into a set of queries that can be run on a staff repository. E-mail verbs are defined for the most common staff verbs supported by the LDAP plug-in. The following e-mail verbs are available:

For the other LDAP staff verbs, the user identifiers retrieved by the staff verbs are used as input to the Email Address for Users by User ID verb.

Before the e-mail verbs can be run as queries on a specific staff repository, they must be translated into executable queries using the LDAP XSL transformation. The result of a transformation (mapping) can be run by the LDAP staff resolution plug-in. At run time, the query returns a set of e-mail addresses, for example, user1@mycomp.com, user2@mycomp.com, and so on.


Terms of use |

Last updated: Tue Feb 21 17:47:12 2006

(c) Copyright IBM Corporation 2005.
This information center is powered by Eclipse technology (http://www.eclipse.org)