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:
- Using WebSphere Integration Developer, a modeler associates a newly created
task with the staff plug-in configuration bpe/staff/sampleldapconfiguration.
- 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"
- 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>
- 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:
- Email Address for Department Members
- Email Address for Group Members
- Email Address for Group Members without Names Users
- Email Address for Group Members without Filtered Users
- Email Address for Group Search
- Email Address for Role Members
- Email Address for Users
- Email Address for Users by User ID
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.