Troubleshooting WebSphere Process Server projects, Part 1: Integrating LDAP systems for authentication and authorization

How to analyze and solve problems with staff assignments

Learn common issues that occur during application development and deployment of new business workflows with human interaction and how to solve them. This first part of an article series explains how to check if an LDAP server is responding as expected and how to deal with failing task assignments. It also covers best practices for performance and handling.

Stephan O. Volz (stephan.volz@de.ibm.com), Technical Team Lead, BPC L2 Support (EMEA), IBM

Photo of Stephan VolzStephan Volz is a Software Engineer in Software Support for WebSphere Process Server and Business Process Choreographer. Over the years, he has gained extensive skills in the areas of security and databases. Before joining IBM, Stephan was a Systems Administrator for Linux systems. Stephan holds a Ph.D. degree in Nuclear Physics from the Technical University of Darmstadt, Germany and has issued several publications on this topic.



20 July 2011

Introduction

A business process usually means interaction with a human being. WebSphere® Process Server (hereafter called Process Server) has, therefore, the construct of a human task that can be assigned to individual humans based on a user registry to work on the corresponding tasks assigned to them. The component responsible for human interactions is the Business Process Choreographer (BPC). In most cases, the user registry is an LDAP server, but other options like a database or a file-based user registry can be used as well. This article will focus on the LDAP user registry.

There are two ways to use LDAP as a user registry of Process Server. The first one is to use a standalone LDAP user registry. The second option is Virtual Member Manager (VMM), also called the federated repository or WebSphere Identity Manager. It was introduced in WebSphere Application Server V6.1 (hereafter called Application Server). Keep in mind that the People Directory Provider used for BPC can be configured separately from the Application Server security for user assignments. Nevertheless, we recommend using the same user registry for Application Server security and BPC. In the next section, a sample business process will be introduced to test the steps described in the rest of the article. There will be some examples given for practical exercises, but these depend on the environment you are using and need to be adjusted accordingly.

The first human task

When starting WebSphere Integration Developer (hereafter called Integration Developer) and creating a new project, it is rather straightforward to create a business process with a simple inline human task. For your convenience, a sample project interchange file is provided in the Download section of the article. You can import it "as-is" into Integration Developer V7. The project works in earlier versions, but the People Directory Provider needs to be selected as advised by Integration Developer. This sample application is sufficient to test and explore most of the procedures described in this article.

Figure 1 shows the business process with its inline human task. Figure 2 shows the respective user assignment settings, which is the "Group" people assignment criteria (staff verb) for this example. When starting a new process instance of the process template, which was deployed with the provided application, an input message is provided. The start activity of a new business process triggers the creation of a human task. This task contains the input message given during the business process instance creation. The human task is assigned to a number of potential owners. These potential owners are a group of people who are allowed to work on this message. Anyone in the group can claim the newly created human task exclusively. You need to adjust the potential owners to the testing environment being used. The potential owner becomes the owner of the task when claiming it. After providing an output message, the user can complete the human task. The business process then reaches the finished state. Information to assign the potential owners of the task is given in the following sections of the article.

Figure 1. Business process with an inline human task (provided sample application)
Screenshot of provided sample application with a human task
Figure 2. Assigned potential owners
Screenshot of assigned potential owners

Business requirements and the build process

Even though testing of human tasks can be fun, there is usually a business need to create a human task. It is vital to understand this business need for a human task and the entire application. Changing an application during production use may be impossible in some cases, but is always an expensive and painful action. Changes are common in any organization, therefore Process Server provides a feature called "versioning". Versioning is helpful when there is an application change needed for an already running system (see Versioning business processes and human tasks in WebSphere Process Server). Versioning allows you to avoid downtime when changing a deployed application. Using this feature is considered a proven best practice and is simple to implement.

Why is it so important to understand the business need? When assigning potential owners to a human task, there are a number of predefined "people assignment criteria" (previously called "staff verbs"). In the following text, "people assignment criteria" is used, but the behavior for the staff verbs is the same. People assignment criteria are used to assign human beings to work on specific tasks. It is possible as well to define your own people assignment criteria (staff verbs) to represent specific business structures.

This decision on such a people assignment criteria can have an impact on performance and task handling. For example, when assigning a group for a human task, this allows you to easily add or remove users from the system. If a specific user was hardcoded in the application for each user change, a new deployment of an application version is necessary. This is not the case if a group is assigned. Another example is the number of users being assigned as potential owners. The amount of assigned users has an influence on the used people assignment criteria (staff verb) as well as performance. At this point, it is necessary to be aware about the number of users who are assigned to the corresponding human tasks.


The LDAP server

Let's now take a look at the Lightweight Directory Access Protocol (LDAP) server, which is an industry standard. It is frequently used for authentication and authorization of users. The adaptability, flexibility, and quick response times are some major advantages. The LDAP protocol provides users the possibility to directly change their personal information without involving other people. In addition, it is cross-platform compatible that is independent of specific LDAP server products being used. However, there are some product specific settings that can prevent using it successfully. With some basic LDAP understanding, these can be solved easily. The next sections will go into details for different products and will show some BPC-related knowledge as well.

The LDAP standard and some BPC-related knowledge

The LDAP standard formulates all LDAP queries to be case insensitive (see RFC 4510: Lightweight Directory Access Protocol (LDAP): Technical Specification Roadmap). Because of other requirements, BPC so far was case sensitive. This is seen when working with human tasks. The assigned users or groups for human tasks need to match the case as they are provided by the LDAP server response. If the case does not match, users do not see their tasks or are not authorized to work on them. As some business requirements rely on the LDAP standard, the default behavior of BPC can be changed with an iFix that allows case insensitive access to the work items: IZ85270 (on top of Process Server V6.2.0.3) and IZ85271 + JR36398 (on top of Process Server V6.1.2.3). It is planned to be available for WebSphere Process Server V7 with FixPack 4.

Tip: When changing the BPC behavior to be case insensitive, carefully check the readme file provided with the iFix. Before applying the iFix, it is necessary to decide if case insensitivity is required and if the user or group information is translated to upper or lower case. The application needs to reflect this selection when assigning people to human tasks. In most cases, the system contains process instances and human tasks assigned to them. These need to be transferred before the iFix is applied. If the case setting of the iFix does not match the case of people assigned already, users will not see tasks that are assigned to them.

Different LDAP server products

Different LDAP server products use different default objectclasses. This can have an impact on users found during a search process. An objectclass is a definition file describing the objects stored in the directory of the LDAP server, which guarantees a consistent state of the directory and the LDAP server. The objectclass definition defines which attributes are mandatory or optional for a LDAP server data entry.

It is a best practice to define your own objectclasses instead of modifying one of the objectclasses shipped with the product. This can lead to unexpected behavior when moving to a different LDAP system or other users working with such a modified system. The objectclass is used in the Application Server authentication and authorization process, which makes it necessary for the objectclass to be configured correctly in Application Server. Process Server uses most of the Application Server security. With the LDAP configuration options in VMM, it is easier to configure the system correctly. This is different for a standalone LDAP server configuration, which might require some more manual interaction depending on which Process Server and LDAP server are in use. The configuration can be done under the advanced configuration section, which handles the used objectclasses and attributes. Necessary changes can apply if a non-default objectclass is used.

A short overview of the more frequently used objectclasses is shown in Table 1. Note that some attributes, such as the uid for the ePerson objectclass, are optional and associated attributes must be used if an objectclass is referenced. It is only possible to use the attribute of an objectclass, which is included in the system configuration.

Table 1. Frequently used objectclasses and associated attributes necessary for security configuration (some attributes are optional)
Users and Groupobjectclassselected attributes
UsersePersonuid
inetOrgPersonuid, cn
organizationalPersoncn
posixAccountcn, uid
GroupsgroupOfUniqueNamesuniqueMember
groupOfNamesMember

BPC provides some additional mechanism to modify search results provided by the LDAP server via so called "transformation files". These can modify the search result and adopt it to specific business requirements. We recommend to use your own transformation files because the sample files can undergo modifications without further notice (for example, during product upgrade to a newer version). The easiest way is to copy the sample transformation file to a significant file name and use the new file in a new People Directory Provider configuration. In general, the sample transformation files are sufficient. Slight modifications may be necessary, for example, when using Microsoft® Active Directory with the SAMAccountname attribute. To create more complex customized configuration files, refer to Authorization and staff resolution in Business Process Choreographer: Part 3: Customization options for staff resolution and Building human tasks with the Virtual Member Manager and LDAP.

ldapsearch and how to use it

ldapsearch is a flexible command-line tool, which is available for nearly all operating system platforms. It allows to query LDAP servers and show the responses. Over time, graphical tools like Apache Directory Studio have evolved. They provide a graphical user interface with similar and sometimes also extended functionality. For a production system, most likely the ldapsearch tool will have the benefit of being command-line based, and therefore, provide a smaller footprint.

When running ldapsearch on a Process Server host, it encounters effects from network components, and search results are completely independent from Process Server. This means that if the ldapsearch result set does not fulfill the requirements, it is not a Process Server problem, but an infrastructure problem or a problem with the business assignment.

If the search result is not as expected, check the topology for intelligent network equipment between Process Server and the LDAP system. Some examples of problems caused by network equipment are the following:

  • An intelligent network switch for failover had a firmware bug, which resulted in some packages being misrouted.
  • A firewall was configured to end a connection after 1 hour. The connection was just dropped and Process Server never learned about the connection that ended.
  • Advanced security configurations did not allow specific servers (based on IP addresses) to see the complete LDAP server content. Especially in this case, ldapsearch can help to clearly identify the reason for the failing people assignment criteria.

Summary: If problems are seen, be aware about network components between different systems, check the corresponding logs, and apply the latest firmware updates on the network devices.

The code section in Listing 1 shows the most frequently used options for the ldapsearch command. In addition, an example demonstrates how to query information for a specific user in the directory. Besides the user information, such as names and password information, associated objectclasses for this object are listed as well. For some of the queries being sent by Process Server, the corresponding objectclasses need to be configured in the security configuration of Process Server so that the associated entries are found in the directory.

Listing 1. Most frequently used options for ldapsearch and a sample execution of ldapsearch
usage: ldapsearch [options] [filter [attributes...]]
Search options:
  -b basedn  base dn for search
Common options:
  -d level   set LDAP debugging level to `level'
  -D binddn  bind DN
  -h host    LDAP server
  -H URI     LDAP Uniform Resource Identifier(s)
  -I         use SASL Interactive mode
  -p port    port on LDAP server
  -v         run in verbose mode (diagnostics to standard output)
  -V         print version info (-VV only)
  -w passwd  bind password (for simple authentication)
  -W         prompt for bind password
  -x         Simple authentication
  -Z         Start TLS request (-ZZ to require successful response)


example@myhost:~> ldapsearch -h 10.156.176.225 -p 389 -x -D "cn=root" 
-W -s subentry 
-b "dc=example,dc=com" uid=example1
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <dc=example,dc=com> with scope subtree
# filter: uid=example1
# requesting: ALL
#

# example1, people, example, com
dn: uid=example1,ou=people,dc=example,dc=com
objectClass: top
objectClass: posixAccount
objectClass: shadowAccount
objectClass: inetOrgPerson
objectClass: person
objectClass: organizationalPerson
objectClass: ePerson
cn: Max Mustermann
gidNumber: 100
homeDirectory: /home/example1
sn: Max
uid: example1
uidNumber: 1001
givenName: Mustermann
loginShell: /bin/bash
mail: example1@example.com
middleName: d
shadowInactive: -1
shadowLastChange: 13527
shadowMax: 99999
shadowMin: 0
shadowWarning: 7
userpassword:: dGVzdERhdGE=

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Advanced LDAP features (referrals, nested groups)

The LDAP standard includes the features of referrals and nested groups. Referrals are defined to point to a different LDAP server if the information is not stored locally. However, a corresponding target system is known. Process Server can follow such pointers if this feature is enabled. The enablement can be done on the LDAP user registry configuration page. As these features are technically more complex, they will be addressed in a more advanced article.

You can use nested groups to organize groups in LDAP and define groups as part of groups. In most cases, nesting of LDAP groups can lead to a larger number of users. Therefore, for Process Server with nested groups, special care is needed when using people assignment criteria (staff verbs) that create user work items as described in the next section. If too many users are assigned with user work items, this impacts performance. Handling large numbers of users in groups is described in the next section.

When configuring nested groups in VMM, special care must be taken for the configuration of nested and direct lookup. When using nested groups, you may need to use a direct, instead of a nested, lookup on the groupmembership configuration page. As this feature is also more advanced, it will be described in a separate article.


Development of a business process

The development of a business processes requires decisions on the fundamental design of an application. The following topics discuss important areas that have an impact on performance and maintainability.

Business requirements and associated LDAP server background

After the business requirements have been defined and first estimates about the expected process and task instances have been calculated, the following question arises: How many users will be assigned to specific tasks? The next section will focus on achieving performance benefits by using different people assignment criteria (staff verbs). In some scenarios, it is beneficial to create your own people assignment criteria (staff verbs).

Group work items vs. user work items

In most organizations, it is common to have LDAP groups with a large number of members. From a process design perspective, usually only a small number of people is intended to fulfill a special task. Therefore, it is vital to check in advance on the possible usage patterns for all human tasks and to use the corresponding people assignment criteria (staff verbs) as documented in this Information Center topic, Predefined people assignment criteria.

Process Server offers a number of pre-defined people assignment criteria (staff verbs). Let's compare the people assignment criteria (staff verbs) "Group" and "Group Members". For the "Group" people assignment criteria (staff verb), there is a group work item created. This means there is an entry in the database created that stores the group name given during the Integration Developer design process. The other people assignment criteria (staff verb) "Group Members" creates a similar entry for the assigned group, but the different handling results in a larger WORK_ITEM view. This leads to longer execution times in the database server. For this reason, if a group with a large number of members is used, the "Group" people assignment criteria (staff verb) can bring significant performance improvement. Details on the database queries and how to improve them will be covered in the next article of this series.

Be aware that the security mechanism is different for the "Group" people assignment criteria (staff verb) in comparison to the "Group Members" people assignment criteria (staff verb), which creates user work items. For the "Group" people assignment criteria (staff verb), the group membership of a user is determined during the login process. All groups the user is a member of at this point in time are stored in his security token being generated during the login. This user can work on all tasks that are assigned by a work item to the groups, which are stored in his security token. For user work items, changes in the group membership are reflected by the People Query Refresh daemon (formerly known as Staff Refresh daemon). It runs at predefined times and refreshes all expired information on stored people assignments.

Tip: You cannot use the "Group" staff verb for escalations with notifications because it is not clear where the email is sent.

JNDI name configuration for used task assignment

When using people assignment criteria (staff verbs) during application design, you need to define the underlying user registry. This is done by referencing the chosen user registry with a JNDI name. There are already some predefined user registries, but additional registries can be defined. In Integration Developer starting with Version 7, a new concept is used for the mapping: An arbitrary name for the user registry is defined under Window > Preferences > Business Integration > Human Task Editor > People Directory Provider as shown in Figure 3. It is no longer necessary to provide the full JNDI name by clicking on the Properties tab of a human task. Now the earlier defined name needs to be selected when defining a human task. Additional People Directory Provider JNDI names can be added on a workspace scope.

Figure 3. People Directory configuration in WebSphere Integration Developer (seeenlarged Figure 3)
Screenshot of People Directory configuration in WebSphere Integration Developer

WebSphere Process Server preparation

Before deploying a new application to an "empty" Process Server, read the following sections to avoid any problems during deployment or later application execution. You may find the following sections helpful if applications have already been deployed and unexpected behavior is observed.

People Query Refresh daemon (Staff Refresh daemon)

LDAP search results are cached in the BPEDB database. The retention of these results can be configured. Change is a common action in every enterprise, therefore the People Query Refresh daemon (Staff Refresh daemon) is included in Process Server to refresh the cached LDAP search results. When to run this daemon is defined in the Integrated Solutions Console (ISC) as shown in Figure 4. The notation is in a cron-like style. When deleting all entries in the time field, the daemon will not be executed. However, it is advised to trigger the people query refresh daemon regularly by other means instead.

Figure 4. People Query Refresh daemon configuration page - ISC (seeenlarged Figure 4)
Screenshot of People Query Refresh daemon configuration page

Security roles and their assignments

BPC provides a number of predefined security roles listed in Table 2 and Table 3. These roles are usually sufficient to handle any security requirements implied by the business requirements. It is important that these roles are mapped to the corresponding users that are intended to act in the corresponding security role. In most scenarios, it is not intended to assign all users to BPESystemAdministrator and TaskSystemAdministrator. However, it is observed regularly and it explains why users can see process and task instances they are not intended to see.

Tip: Do not add an administrative user for administration tasks to every group of the deployed applications. Because of the corresponding security checks during login, a login may take several minutes. Use the predefined user roles like BPESystemAdministrator or TaskSystemAdministrator for administration tasks.

Tip: If a performance problem is observed on a system and it is related to a large number of entries in the WORK_ITEM_T table of the BPEDB database, the problem, in most cases, cannot be solved quickly. This is more frequently seen when user work items are used. Users can be granted additional permissions to circumvent some of the more expensive security checks as a quick workaround. There are two additional roles available that might bring some relief without exposing too much risk: BPESystemMonitor and TaskSystemMonitor. These two roles skip some of the security checks, which can have a fundamental impact on query performance. By default, this allows members of these roles to see all the corresponding entries. The members do not have the rights to interfere with all processes or tasks, but they can see all process or task instances. This speeds up the response times in the BPC Explorer or the corresponding API calls. Whether this workaround is acceptable or not depends on your business requirements.

Table 2. Security roles defined for the BPE Container (ISC)
RoleDescription
BPEAPIUserUsers assigned to this role are authorized to execute Business Flowmanager (BFM) API calls.
BPESystemAdministratorUsers assigned to this role can see and act on all process instances in the system and perform all other administrative tasks. If a user sees more process instances than expected, then this setting should be checked. The number of assigned BPESystemAdministrators for a normal business is low in most cases.
BPESystemMonitorUsers assigned to this role can see all process instances, but cannot act on them. This role can be of special interest because it gives assigned users the benefit of better security check performance without giving too many permissions.
JMSAPIUserUsers assigned to this role can use the JMS API calls.
AdminJobUserUsers assigned to this role can do administrative work.
JAXWSAPIUserUsers assigned to this role can use the JAXWS webservice API calls.
Table 3. Security roles defined for the Task Container
RoleDescription
TaskAPIUserUsers assigned to this role can use the Human Task Manager (HTM) API.
TaskSystemAdministratorUsers assigned to this role can see and act on all tasks. If a user can see more task instances than expected, then this setting should be checked. The number of assigned TaskSystemAdministrators for a normal business is low in most cases.
TaskSystemMonitorUsers assigned to this role can see all tasks, but cannot act on them. Because this role can see all tasks, security checks perform better than for a normal user. This is beneficial in some scenarios with performance problems.
EscalationUserUsers assigned to this role can become Escalation users.
AdminJobUserUsers assigned to this role can do administrative work.
JAXWSAPIUserUsers assigned to this role can use the JAXWS webservice API calls.

People directory provider configuration

Depending on the Application Server security configuration, the people directory provider needs to be configured. For an Application Server security configuration with VMM, no additional configuration is needed if the VMM People Directory provider is used. It is also possible to configure the standalone LDAP People Directory provider in addition. For an Application Server security configuration with a standalone LDAP user registry, a standalone LDAP People Directory provider can be configured. It is a proven best practice to use the same user registry for Application Server security and People Directory Provider. This guarantees that the same users exist for authentication and authorization.

Group work items

When using group work items, consider also the LDAP server for optimum performance. Even though group work items will work fine with the default configuration, some additional settings can reduce the load on the LDAP server and thus, result in better response times. Corresponding settings can be made in the Integrated Solutions Console (ISC) for the group membership attribute as depicted in Figure 5.

Figure 5. Group membership configuration page (seeenlarged Figure 5)
Screenshot of group membership configuration page (ISC)

Group membership attribute settings are LDAP server product specific. Table 4 lists some examples. The advantage of this additional attribute is that an optimized access path on the LDAP server is used to check the group membership of the queried user. This results in lower load on the LDAP server and quicker response times. In some environments, such as the SunOne directory server, the structures for an optimized access path on the LDAP server side are of no default and their implementation might be denied for administrative or policy guidelines. If no performance problems are observed on the LDAP server or if response times are low, it is also valid to run without these additional parameters. For IBM® Tivoli® Directory Server, the group membership attribute "ibm-allgroups" is already implemented and no further configuration on the LDAP server is necessary.

Table 4. Some LDAP server products and groupmembership attributes
LDAP server product nameGroupmembership attribute
Microsoft Active DirectorymemberOf
OpenLDAPmemberof (check configuration on LDAP server)
IBM Tivoli Directory Serveribm-allgroups
IBM Lotus Domino ServerdominoGroup
SunOne Directory ServernsRole
Novell eDirectorygroupMembership

Tip: The usage of group work items is disabled by default for better performance when using small groups. As daily business has shown, assigned groups are often larger, and for this reason, group work items can bring a performance benefit. The decision during the application design process to use group work items requires to enable group work items on Process Server where the application is intended to be deployed. This is done on the Human Task Manager configuration page of the Integrated Solutions Console (see Figure 6). For clusters, the configuration is done on the Human Task Manager configuration page of the cluster. During the deployment process, a warning is printed in the SystemOut.log that group work items have not been enabled on the system if group work items are used in the newly deployed application and this feature is disabled on the server.

Figure 6. Human Task Manager configuration page - ISC (seeenlarged Figure 6)
Screenshot of Human Task Manager configuration page (ISC)

Deployment process

After an application has been designed and the corresponding potential owners have been assigned to the human task, you can deploy the application to WebSphere Process Server.

Tip: Even though it might be considered an unnecessary or nasty task, proper Function Verification Testing and proper load testing are important requirements. Especially for the latter, we strongly recommend to test with production loads, data, facilities, and so on. Analyzing and fixing performance problems in production is expensive in time, cost, and resources, not to mention negative end-user experiences in an organization.

Problems during deployment

If everything was done correctly, there should be no problems encountered during the deployment process. However, it can happen that the JNDI name of the user registry being defined in Integration Developer cannot be found on the target server. This results in an exception similar to the one shown in Listing 2.

Listing 2. Exception for user registry not found
[01/12/10 8:25:28:072 CET] 0000008b LocalExceptio E   CNTR0020E: EJB threw an unexpected 
(non-declared) exception during invocation of method  "transactionRequiredActivitySession
NotSupported" on bean "BeanId(TaskContainer_wpsnode_server1#h.jar#Module, null)".  
Exception data: com.ibm.task.api.StaffServiceRuntimeException: CWTKA0090E: User
information access error: ''{0}'' com.ibm.bpe.plugins.StaffPluginDeploymentException:
CWWBS0410E: Generic people directory (staff resolution) plug-in deployment error: Cannot
load Staff Support Service plug-in com.ibm.bpe.plugins.StaffPluginNotAvailableException:
CWWBS0417E: The people directory (staff) plug-in is not available.
javax.naming.PartialResultException: Unprocessed Continuation Reference(s); 
Remaining name: 'dc=example, dc=com'

Solution: Check the user registries provided in the People Directory Provider configuration section of Process Server. Adjust the JNDI name in the application or add a corresponding People Directory Provider configuration to Process Server. Most likely the server has already been configured and runs with some existing user registry. In this case, the application can be adjusted (see JNDI name configuration).


Tasks not getting assigned as expected

A frequently seen problem is either invisible human tasks or users accessing tasks or process instances that they are not allowed to see. Some causes for such unexpected behavior and how to resolve them are described in the following sections. As an example, an inline human task is used, which has a group of potential owners assigned. The described steps also apply to other scenarios.

Checking security role settings

Problem: Users see processes or task instances that they are not allowed to see.

Solution: Check the security role settings for BPEContainer and TaskContainer. These security settings can grant administrative privilege to a user. Hence, the user can see all process instances or task instances. In addition to that, we always recommend to check the user's group memberships and assigned groups as well. Sometimes a user is not directly assigned, but is a member of an assigned group. Sample screenshots for the BPEContainer are shown in Figure 7 and Figure 8. The TaskContainer shows similar settings, and for this reason, is not depicted here.

Figure 7. BPEContainer application configuration page (seeenlarged Figure 7)
Screenshot of BPEContainer application configuration page
Figure 8. Security role mappings of BPEContainer (seeenlarged Figure 8)
Screenshot of security role mappings of BPEContainer

Checking assigned staff via the BPC Explorer

Problem: Users cannot see tasks that are assigned to them.

Solution: As mentioned earlier, BPC handles work item assignments as case sensitive if the iFixes have not been applied. If a user cannot see tasks that are assigned to him, a user with administrative privilege can check the Staff tab for the corresponding human tasks (see Figure 9) and check if the assignment is done correctly.

Figure 9. Staff Assignment for a human task instance - BPC Explorer (seeenlarged Figure 9)
Screenshot of Staff Assignment for a human task instance (BPC Explorer)

If the potential owner for a human task is empty or an unexpected userid or groupid is displayed, the assignment is incorrect. The application needs to be checked for the assigned users and to make sure the correct user registry is referenced. If a userid is not found by Process Server, it assigns a task to an administrator or an administrative group (depending on the security role configuration) to make sure nothing gets lost.

Caution: For some people assignment criteria (staff verbs), you must provide the fully qualified domain name (for example, Group Members or Group).

When using VMM, be aware that the fully qualified domain name can be defined differently compared to the value stored in the LDAP system. This is mainly done when combining different user registries, but can also happen in other scenarios. The result can be confusing, but it actually works as configured. For reference, a screenshot of the Integrated Solutions Console (ISC) is shown in Figure 10.

Figure 10. User registry mapping performed for VMM - ISC (seeenlarged Figure 10)
Screenshot of ISC for the user registry mapping performed for VMM (ISC)

Checking assigned users and groups

In the last section, it was described how to check for the assigned potential owners of a task from the BPC Explorer perspective. If a specific user is not assigned, check the assignment done in the application. Therefore, open the application in Integration Developer and check the assigned users for a human task (see Figure 11).

Figure 11. Human task assignment in WebSphere Integration Developer (seeenlarged Figure 11)
Screenshot of human task assignment in WebSphere Integration Developer

Figure 11 shows how to run a test for assigned groups or users. This requires the Process Server host being added to Integration Developer and the server to be started. Although it is a rather uncommon activity for production systems, it is a regular problem determination step during development and testing. When pressing the Test button, the resolved LDAP entries are shown.

In case replacement variables are used, the correct usage and resolution must be checked. An incorrect replacement variable results in an unexpected or empty value in the Staff tab. To track down problems with replacement variables, you may want to insert a Java™ snippet into the process and print out the values used in this operation.

Tip: Sometimes placeholders are used in Integration Developer for assigned potential owners and these need to be adjusted before an .ear file is exported. If a different department provides an application .ear file for deployment and the "same" application works fine on a different system, it is worth a try to export the working application from the system and to import this .ear file on the non-working system (under the prerequisite that the same LDAP directory content is used). Sometimes placeholders are overseen, which can result in tasks not being assigned as expected.

After the assignment has been proven to be correct, the responses of the user registry for the failing system must be verified. As this article focuses on LDAP, which is the most often used user registry for handling human resources, the next section will explain how to use ldapsearch to investigate LDAP server responses.

Checking the LDAP server response

Given that all the previous analysis steps have been successfully finished and you still face the initial problem that users cannot see their tasks, it is time to check the results delivered from the LDAP server. It is proven best practice to run the "ldapsearch" tool on the machine hosting Process Server to analyze the responses. Using this approach, you can observe exactly the same behavior that Process Server observes. It is possible that intelligent network switches, firewalls, or proxy servers change the response based on the IP address origin or firmware that is not working. The same LDAP server might provide good result sets when running ldapsearch from a different workstation. The sample code in Listing 3 shows the ldapsearch execution and the resultset received. Slight modifications of the command is necessary, depending on the used platform (OS), general system configuration, and information to be queried. It is also important to check on the search scope, which was in the earlier example subtree (all entries below the given entry) and for this example base (which only uses the depth of the provided entry).

The first ldapsearch output in Listing 3 shows the members of the LDAP group cn=TestUsers2,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE. To know what members are part of a group can be important during the design process and also during runtime. The second ldapsearch command uses a Tivoli Directory Server specific attribute "ibm-allgroups" (not available for other LDAP server products) to show all the groups the user "svolz" is in. To know all group memberships of a user can help during the troubleshooting process.

Listing 3. ldapsearch command executed for the group TestUsers2
svolz@munlnx:~> ldapsearch -h 10.156.176.225 -p 389 -x -D "cn=root" -W -s base -b 
"cn=TestUser2,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE" objectclass=* 
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <cn=TestUsers2,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE> with scope baseObject
# filter: objectclass=*
# requesting: ALL
#

# TestUsers2, groups, wps_support, munich, ibm, de
dn: cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de
objectclass: groupOfUniqueNames
objectclass: top
cn: TestUsers2
description: TestUsers user group
uniquemember: uid=svolz,ou=people,ou=wps_support,l=munich,o=ibm,c=de
uniquemember: uid=example2,ou=people,ou=wps_support,l=munich,o=ibm,c=de
uniquemember: uid=example3,ou=people,ou=wps_support,l=munich,o=ibm,c=de

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
svolz@munlnx:~> ldapsearch -h 10.156.176.225 -p 389 -x -D "cn=root" -W 
 -s base -b 
"uid=svolz,ou=people,ou=wps_support,l=munich,O=IBM,C=DE" objectclass=* 
 ibm-allgroups
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <uid=svolz,ou=people,ou=wps_support,l=munich,O=IBM,C=DE> with scope 
 baseObject
# filter: objectclass=*
# requesting: ibm-allgroups
#

# svolz, people, wps_support, munich, ibm, de
dn: uid=svolz,ou=people,ou=wps_support,l=munich,o=ibm,c=de
ibm-allgroups: cn=testusers,ou=groups,ou=wps_support,l=munich,o=ibm,c=de
ibm-allgroups: cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de
ibm-allgroups: cn=nestedgroup,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Tip: Sometimes an application is moved from a test system to a pre-production system, or a production system with a different LDAP server. The LDAP servers are not always synchronized on a user basis. If assignments for potential owners fail, it is good practice to see if the users and groups being assigned are also in the LDAP server of the non-working system.

Checking used transformation files and other search result modifications

As mentioned above, LDAP search results may be modified automatically by Process Server via transformation files. If the files shipped with Process Server have not been modified, you can skip this section. If the transformation file was modified and the people assignment is not working as expected, check the used transformation file. Depending on your business requirements, it might be an option to exchange the customized transformation files with the ones that came with the product for a comparison test, or to simplify the used transformation file. If a new Problem Management Report (PMR) is raised, it is necessary to include the customized transformation files as well as the reproduced steps.

In addition to the transformation files, there are two advanced means to influence the LDAP search result: PostProcessor plugin and Substitution. These two options are more complex and cannot be discussed in this article. To rule out that the problem stems from these two options, it is a good idea to disable these features as described in Using a plug-in to post-process people query results or Configuring people substitution, and test again. If the test is successful, the corresponding documentation in the Information Center may help to solve it.

Administrative users and My ToDo tasks view

If a user is in an administrative role and also assigned as a potential owner of a task, he might not see his ToDo tasks as a potential owner because the administrative user check is considered first. This works as designed. Usually, an administrator does not work on business processes.

Query tables and work item sharing

A feature called "query tables" was introduced in Process Server V6.2.0.3 and V7.0 for the BPC Explorer. Query tables allow better performance for search activities in the BPEDB database. This means results surface more quickly on the page in the BPC Explorer and new API calls provide quicker response times. A comparison between the old APIs and the new APIs is given in this Information Center topic, Comparison of the programming interfaces for retrieving process and task data.

If a query table delivers empty results, this can have a number of reasons. Among these, incorrectly defined filters or tasks not being created are common. To verify query table results, issue a statement like the one shown in Listing 4. As the statement has no filters applied, it delivers all task entries from the table. If there is no entry seen, the task has not been created. If there is an entry seen, check the query table definition for any defined filters. The default query tables used by the BPC Explorer filter on the task kind 101 and 105, which corresponds to a collaboration and a to-do task. Thus, for an inline human task, an entry for task kind 105 is expected. If the entry cannot be seen in the search result, the task was not created and it needs to be investigated.

Listing 4. Test content of TASK view (for larger databases, define additional filters to limit the load and data output)
SELECT * from TASK;

With Process Server V7.0.0.3, another performance enhancing feature was introduced, "workitem sharing". Workitem sharing reduces the number of work items stored in the database and hence, increases the query performance. From Process Server 7.0.0.3 onwards, workitem sharing is enabled by default for every new profile created. In this case, no manual intervention is necessary. In the case of an upgrade or a migration to Process Server V7.0.0.3, workitem sharing is enabled by running the migrateWI.py script. For more information, see this Information Center topic, Business Process Choreographer data migration script for shared work items.

If workitem sharing is not enabled after the upgrade to WebSphere Process Server V7.0.0.3 during startup, there is an ffdc file written complaining that the table SWI_T could not be found. This is working as expected and causes no harm if workitem sharing is still disabled and no other exceptions show up.

Tip: If workitem sharing is enabled, immediately check that the following iFixes are applied: IZ82793 and IZ90994. Further details are described in this Technote.

Advanced troubleshooting: Checking trace and database content

This is the last section on troubleshooting. It provides further insight into Business Process Choreographer. If a people assignment problem cannot be solved with the steps above, contact the Support team. Be aware that Support will ask about the above points as well, therefore, it is beneficial to provide a detailed comment in the PMR regarding analysis steps performed so far and the results received. Make sure to attach all output to a PMR for further reference by the Support team. In addition, the following trace settings (see Listing 5) must be enabled during the time the problem is recreated. The number and size of the trace files must be sufficient to capture the complete scenario, or else the trace is useless.

Listing 5. Trace settings needed for analyzing a people assignment problem
com.ibm.bpe.*=all:com.ibm.task.*=all:com.ibm.ws.security.*=all:
com.ibm.ws.staffsupport.*=all:com.ibm.websphere.wim.*=all:
com.ibm.ws.wim.*=all:com.ibm.wsspi.wim.*=all

As mentioned in the previous paragraph, one powerful means to gain more details on a failing people assignment is a trace. In general, trace analysis is a complex job, therefore the focus is on some keywords that are helpful in the troubleshooting process.

When enabling the above mentioned trace, all internal processing is logged. This can produce a lot of data. For high load systems, several gigabytes of data is usual. It is impossible to read through all this data, therefore the focus is on two examples:

  1. How to determine if the user logged in is an administrative user (useful when a user can see all the process instances information).
  2. How to check the content of a LDAP server response that reached Process Server.

The example shown in Listing 6 explains how to use the keyword isBPESystemAdministrator=true to see if a user is an administrative user, which allows him to see all process instances. In the case of isBPESystemAdministrator=false and isBPESystemMonitor=false, the problem is not attributed to the fact that the user has administrative rights. In most of the cases seen, the problem is already identified and the corresponding user was assigned to an administrative role.

Listing 6. Trace extract showing user credential information
[9/15/10 19:09:58:967 CEST] 0000004b TraceBPE      3   
 com.ibm.bpe.framework.Business
FlowManagerBean.setContext (BusinessFlowManagerBean.java:18932) EngineContext:  
Logged-on user: svolz IsBPESystemAdministrator: true IsBPESystemMonitor: true
Groups: cn=testusers,ou=groups,ou=wps_support,l=munich,o=ibm,c=de,
cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de,
cn=nestedgroup,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE,
cn=testusers3,ou=groups,ou=wps_support,l=munich,O=IBM,C=DE

The example in Listing 7 shows a trace extract from the deployed staff query lookup for the people assignment criteria (staff verb) of "Group" and "Group Members". As shown for the "Group" people assignment criteria (staff verb), the default People Directory Provider configuration for VMM (bpe/staff/samplevmmconfiguration) is used. The potential owners of the task are in the assigned group cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de. A similar handling is seen for the "Group Members" people assignment criteria (staff verb), but here the trace also lists the members of the group by a lookup in the VMM user registry. The trace extract is shortened here and only lists the member "example1" as an example.

Listing 7. Trace extract showing potential owner work item creation
'Group' people assignment criteria:
[1/30/11 16:48:00:886 CET] 00001174 TraceHTM      <   com.ibm.task.staff.
StaffQueryManager.getDeployedStaffQuery(StaffQueryManager.java:48
3) RETURN Deployed Query = StaffSupportQueryImpl object content:
Context signature[0]:
Type: staffSupportService
JndiName: bpe/staff/samplevmmconfiguration
DeployedStaffQuery:
DeployedVMMStaffQuery object content:
Context signature (0):
SubstitutionPolicy: SUBSTITUTION_POLICY_NO_SUBSTITUTION
Queries (1):
1:
  GroupIDQuery object content:
  GroupID: cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de
  End GroupIDQuery object content.
Threshold: 1
Type: RESULT_TYPE_GROUPIDS
End DeployedVMMStaffQuery object content.
End StaffSupportQueryImpl object content.

'Group Members' people assignment criteria:
[1/30/11 16:54:40:014 CET] 00001174 TraceHTM  < com.ibm.task.staff.
StaffQueryManager.getDeployedStaffQuery(StaffQueryManager.java:48
3) RETURN Deployed Query = StaffSupportQueryImpl object content:
Context signature[0]:
Type: staffSupportService
JndiName: bpe/staff/samplevmmconfiguration
DeployedStaffQuery:
DeployedVMMStaffQuery object content:
Context signature (0):
SubstitutionPolicy: SUBSTITUTION_POLICY_NO_SUBSTITUTION
Queries (1):
1:
  UsersOfGroupQuery object content:
  Is Recursive: true
  Is intermediate Result: false
  Intermediate Result Threshold: -1
  Group ID: cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de
  Group ID Type: uniqueName
  Group Entity Type: Group
  Result Entities: { PersonAccount( uid->userID mail->eMailAddress 
  preferredLanguage->preferredLocale ) }
  End UsersOfGroupQuery object content.
Threshold: 1000000
Type: RESULT_TYPE_USERIDS
End DeployedVMMStaffQuery object content.
End StaffSupportQueryImpl object content.

...

[1/30/11 16:54:41:889 CET] 00001174 TraceHTM  <com.ibm.bpe.staff.VMMAccessControl.
doVMMGet(VMMAccessControl.java:580) RETURN HTM_PA_VMM

<?xml version="1.0" encoding="UTF-8"?>
<xml.type:datagraph xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:wim="http://www.ibm.com/websphere/wim" xmlns:xml.type="commonj.sdo">
  <wim:Root >
    <wim:entities xsi:type="wim:Group">
      <wim:identifier
          externalName="cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de"
          repositoryId="munlnx01_TDS" uniqueId="2efb79c0-3596-102f-832d-9724b7f9a7b0"
          uniqueName="cn=TestUsers2,ou=groups,ou=wps_support,l=munich,o=ibm,c=de"/>
      <wim:members xsi:type="wim:PersonAccount">
        <wim:identifier
            externalName="uid=example1,ou=people,ou=wps_support,l=munich,o=ibm,c=de"
            repositoryId="munlnx01_TDS" uniqueId="2e62e340-3596-102f-8325-9724b7f9a7b0"
            uniqueName="uid=example1,ou=people,ou=wps_support,l=munich,o=ibm,c=de"/>
        <wim:uid>example1</wim:uid>
        <wim:mail>example1@localhost</wim:mail>
          ...
    </wim:entities>
  </wim:Root>
</xml.type:datagraph>

Another approach is checking the use of specific database queries. Process Server provides some documented database views that allow to query for process and task instance information. Table 5 shows a subset of the views available in the system.

Table 5. Selection of Process Server views documented in the Info Center
View nameDescription
ACTIVITYThis view lists all available activity instances in the system
PROCESS_INSTANCEThis view lists all available process instances in the system.
PROCESS_TEMPLATEThis view lists all available process templates in the system. Sometimes an application was not cleanly removed. With this view, it is possible to check if there are still some process template remnants.
TASKThis view lists all available task instances in the system.
TASK_TEMPLThis view lists all available task templates in the system. Sometimes an application was not cleanly removed. With this view, it is possible to check if there are still some task template remnants.
WORK_ITEMThis view lists all available work items in the system.

Listing 8 provides an example on how to use the mentioned database views. The SQL statement retrieves the state information for a specific process instance where the PIID is already known. The output only reveals a number. The corresponding translation from the number to the actual state of the process instance is derived from the Information Center. For convenience, Tables 6 to 9 show values and value translations for several views and columns that are more frequently used. The task related columns shown in Tables 7 to 9 can help to determine if tasks are created and to whom these are assigned. For example, an inline human task has a value of 105 in the KIND column of the TASK view.

Listing 8. Showing a SQL query against PROCESS_INSTANCE view to determine the state of the process instance (Example 3)
SQL> select PIID, STATE 
            from PROCESS_INSTANCE 
            where PIID ='9003012D56E58E9FB44F63F50BF2A907';

PIID                                  STATE
-------------------------------- ----------
9003012D56E58E9FB44F63F50BF2A907          2
Table 6. PROCESS_INSTANCE view STATE column
STATEDescription
STATE_READY (1)The process instance is ready.
STATE_RUNNING (2)The process instance is started and running.
STATE_FINISHED (3)The process instance has finished successfully.
STATE_COMPENSATING (4)The process instance is in compensation processing.
STATE_INDOUBT (10)The process instance is in an indoubt state. This normally should not happen.
STATE_FAILED (5)The process instance failed.
STATE_TERMINATED (6)The process instance was terminated.
STATE_COMPENSATED (7)The process instance successfully completed compensation.
STATE_COMPENSATION_FAILED (12)The process instance compensation process failed.
STATE_TERMINATING (8)The process instance is in terminating process.
STATE_FAILING (9)The process instance is failing.
STATE_SUSPENDED (11)The process instance is suspended.
Table 7. TASK view KIND column
KINDDescription
KIND_HUMAN (101)The task is a collaboration task that is created and processed by a human.
KIND_ORIGINATING (103)The task is an invocation task that supports person-to-computer interactions, which enables people to create, initiate, and start services.
KIND_PARTICIPATING (105)The task is a to-do task that supports computer-to-person interactions, which enable a person to implement a service.
KIND_ADMINISTRATIVE (106)The task is an administration task.
Table 8. TASK view STATE column
STATEDescription
STATE_READY (2)States that the task is ready to be claimed.
STATE_RUNNING (3)The task is started and running.
STATE_FINISHED (5)States that the task has finished successfully.
STATE_FAILED (6)The task did not finish successfully.
STATE_TERMINATED (7)The task has been terminated because of an external or internal request.
STATE_CLAIMED (8)The task is claimed.
STATE_EXPIRED (12)The task ended because it exceeded its specific duration.
STATE_FORWARDED (101)The task completed with a follow-on task.
Table 9. WORK_ITEM view REASON column
REASONDescription
REASON_NONE (0)There is no reason assignment for the entry. Not all events have REASON entries.
REASON_POTENTIAL_OWNER (1)The assigned user or group is a potential owner.
REASON_EDITOR (2)The assigned user or group is an editor.
REASON_READER (3)The assigned user or group is a reader.
REASON_OWNER (4)The assigned user is an owner.
REASON_POTENTIAL_STARTER (5)The assigned user or group is a potential starter.
REASON_STARTER (6)The assigned user is the starter.
REASON_ADMINISTRATOR (7)The assigned user or group is an administrator.
REASON_ORIGINATOR(9)The assigned user is an originator.
REASON_ESCALATION_RECEIVER (10)The assigned user is an escalation receiver.
REASON_POTENTIAL_INSTANCE_CREATOR (11)The assigned user is the instance creator.

Conclusion

Part 1 of this series provided basic information on how to troubleshoot LDAP-related problems with WebSphere Process Server. The article explained what you need to consider during the application design process, such as how to access the information stored in the LDAP server with ldapsearch and what needs to be considered during the deployment of an application. Finally, it described how to troubleshoot problems during application runtime. The next article of this series will cover the topic of using a DB2® database server for the Business Process Choreographer database.


Acknowledgements

The author would like to thank Bonnie Brummond, Uta Dresch, Wolfgang Frey, Andreas Gräber, and Olaf Hoffmann for reviewing this article and providing valuable comments.


Download

DescriptionNameSize
Sample codeMyFirstHumanTask.zip20KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

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

 


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

All information submitted is secure.

Choose your display name



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

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

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=741576
ArticleTitle=Troubleshooting WebSphere Process Server projects, Part 1: Integrating LDAP systems for authentication and authorization
publish-date=07202011