IBM Support

IBM Business Process Manager (BPM) cannot communicate with the IBM BPM document store

Technote (troubleshooting)


Problem(Abstract)

IBM Business Process Manager cannot communicate with the IBM BPM document store. All attempts to communication with the IBM BPM document store result in an exception.
In version 8.5.5, when this exception happens during start-up, the Event Manager is not started and the connection between Process Server and Process Center cannot be established.

Symptom

When IBM Business Process Manager tries to access the IBM BPM document store, the following exception is thrown:

com.ibm.bpm.embeddedecm.exception.UnexpectedFailureException: CWTDS0000E: An unexpected failure occurred. Details: 'FNRCE0051: The requested item was not found.'

You observe an FFDC entry with the following stack trace:

com.filenet.api.exception.EngineRuntimeException: FNRCE0051E: E_OBJECT_NOT_FOUND: The requested item was not found. errorStack={
at com.filenet.engine.retrieve.BaseGCDRetriever.loadActiveSecurity(BaseGCDRetriever.java:366)
at com.filenet.engine.retrieve.BaseGCDRetriever.getObject(BaseGCDRetriever.java:197)
at com.filenet.engine.retrieve.IndependentClassRetriever.getObject(IndependentClassRetriever.java:707)
at com.filenet.engine.retrieve.IndependentClassRetriever.getObject(IndependentClassRetriever.java:355)
at com.filenet.engine.jca.impl.RequestBrokerImpl.getObjects(RequestBrokerImpl.java:760)
at com.filenet.engine.jca.impl.RequestBrokerImpl.getObjects(RequestBrokerImpl.java:663)
at com.filenet.engine.ejb.EngineCoreBean._getObjects(EngineCoreBean.java:208)
at com.filenet.engine.ejb.EngineCoreBean.getObjects(EngineCoreBean.java:175)
at com.filenet.engine.ejb.EJSLocalStatelessEngineCore_22877cb1.getObjects(Unknown Source)
at com.filenet.engine.ejb.EngineBean.getObjects(EngineBean.java:393)
at com.filenet.apiimpl.transport.ejbstubs.EJSRemoteStatelessEngine_2e64c374.getObjects(Unknown Source)
[....]

In 8.5.5 you see a more specific exception, like the following:

CWTDS0021E: The user registry configuration was changed in a way that causes the access to the IBM BPM document store to fail for the technical user 'tw_admin'.
Explanation: The technical user defined in the BPM role type 'EmbeddedECMTechnicalUser' is not permitted to access the 'BPM' domain.
Action: Revert the recent user registry configuration changes and follow the instructions of the 'Administering the technical user for the IBM BPM document store' topic in the IBM BPM Information Center to ensure the technical user keeps access to the IBM BPM document store.
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMInternalUtils$7.run(EmbeddedECMInternalUtils.java:1776)
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMInternalUtils$7.run(EmbeddedECMInternalUtils.java:1761)
at java.security.AccessController.doPrivileged(AccessController.java:362)
at javax.security.auth.Subject.doAs(Subject.java:573)
at com.ibm.websphere.security.auth.WSSubject.doAs(WSSubject.java:195)
at com.ibm.websphere.security.auth.WSSubject.doAs(WSSubject.java:152)
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMInternalUtils.executeAsEcmAdmin(EmbeddedECMInternalUtils.java:1191)
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMInternalUtils.getDefaultDocsDomain(EmbeddedECMInternalUtils.java:1761)
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMConfiguration.validateAndCreateDefaultConfiguration(EmbeddedECMConfiguration.java:256)
at com.ibm.bpm.embeddedecm.init.EmbeddedECMInitializerComponentImpl$1.run(EmbeddedECMInitializerComponentImpl.java:510)
at com.ibm.bpm.embeddedecm.internal.EmbeddedECMInternalUtils.synchronizeCurrentTransaction(EmbeddedECMInternalUtils.java:3719)
at com.ibm.bpm.embeddedecm.init.EmbeddedECMInitializerComponentImpl.stateChanged(EmbeddedECMInitializerComponentImpl.java:507)
at com.ibm.ws.runtime.component.ApplicationMgrImpl.stateChanged(ApplicationMgrImpl.java:1122)
at com.ibm.ws.runtime.component.DeployedApplicationImpl.fireDeployedObjectEvent(DeployedApplicationImpl.java:1353)
at com.ibm.ws.runtime.component.DeployedApplicationImpl.setState(DeployedApplicationImpl.java:294)
at com.ibm.ws.runtime.component.DeployedApplicationImpl.setState(DeployedApplicationImpl.java:289)
at com.ibm.ws.runtime.component.DeployedApplicationImpl.start(DeployedApplicationImpl.java:978)
at com.ibm.ws.runtime.component.ApplicationMgrImpl.startApplication(ApplicationMgrImpl.java:776)
at com.ibm.ws.runtime.component.ApplicationMgrImpl$5.run(ApplicationMgrImpl.java:2195)
at com.ibm.ws.security.auth.ContextManagerImpl.runAs(ContextManagerImpl.java:5474)
at com.ibm.ws.security.auth.ContextManagerImpl.runAsSystem(ContextManagerImpl.java:5600)
at com.ibm.ws.security.core.SecurityContext.runAsSystem(SecurityContext.java:255)
at com.ibm.ws.runtime.component.ApplicationMgrImpl.start(ApplicationMgrImpl.java:2200)
at com.ibm.ws.runtime.component.CompositionUnitMgrImpl.start(CompositionUnitMgrImpl.java:446)
at com.ibm.ws.runtime.component.CompositionUnitImpl.start(CompositionUnitImpl.java:123)
at com.ibm.ws.runtime.component.CompositionUnitMgrImpl.start(CompositionUnitMgrImpl.java:389)
at com.ibm.ws.runtime.component.CompositionUnitMgrImpl.access$500(CompositionUnitMgrImpl.java:117)
at com.ibm.ws.runtime.component.CompositionUnitMgrImpl$CUInitializer.run(CompositionUnitMgrImpl.java:995)
at com.ibm.wsspi.runtime.component.WsComponentImpl$_AsynchInitializer.run(WsComponentImpl.java:502)
at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1864)


Cause

To communicate with IBM BPM document store, you must define a technical user by mapping the IBM Business Process Manager role type "EmbeddedECMTechnicalUser" to an authentication alias, which in turn is mapped to a user. All communication with the IBM BPM document store is done on behalf of this user. However, authorization to the IBM BPM document store is based on unique IDs. Only the user with a particular unique ID can manage the IBM BPM document store and access the documents that are stored in it.


If you change your user registry configuration, for example, by removing the file-based repository so that you use only an LDAP server in federated repositories, a user with the same user ID and password in the LDAP cannot access the IBM BPM document store. Even though the user has an identical name, the unique ID has changed and this change is the reason why it is no longer considered to be the same user by the document store.

For more information about the embedded ECM technical user, see Administering the technical user for the IBM BPM document store.


Resolving the problem

Prevent the problem

The best solution is to prevent this situation from happening. That is, before you start modifying the user registry or deleting the file-based user registry, make sure that there is at least one user that is allowed to connect to the embedded ECM at any time.

You can use the maintainDocumentStoreAuthorization admin command to modify the set of users that are allowed to work with embedded ECM. For example, use the special keyword #AUTHENTICATED-USERS to temporarily authorize all users who successfully authenticate to the IBM BPM document store using the following wsadmin command:

AdminTask.maintainDocumentStoreAuthorization('[-deName De1 -add #AUTHENTICATED-USERS]')

After all authenticated users are allowed to access the document store, you can modify the user registry. After you finish modifying the user registry configuration, restrict access to one or two users again.

For more information about the maintainDocumentStoreAuthorization command, see the maintainDocumentStoreAuthorization command documentation

Resolve the problem

To resolve the issue, complete the following steps to restore the uniqueId from a backup of the fileRegistry.xml file. If you deleted and recreated the embedded ECM technical user from the file-based repository, and you still have a backup of your configuration, you can restore the uniqueId for this user.

  1. Stop the environment.

  2. Back up the current fileRegistry.xml file, which is located in the profile_root/config/cells/cell_name directory.


    Note: The profile_root and cell_name variables are specific to your environment.

  3. Back up the database that contains the embedded ECM tables.

  4. Edit the profile_root/config/cells/cell_name/fileRegistry.xml file and locate the user ID that is defined as the embedded ECM technical user. The following XML snippet shows an example of a user entry:
    <wim:entities xsi:type="wim:PersonAccount">
    <wim:identifier externalId="5e50a25b-d95e-40a6-99a8-888b439738b4"
    externalName="uid=tw_admin,o=defaultWIMFileBasedRealm"
    uniqueId="5e50a25b-d95e-40a6-99a8-888b439738b4"
    uniqueName="uid=tw_admin,o=defaultWIMFileBasedRealm"/>
    <wim:parent>
    <wim:identifier uniqueName="o=defaultWIMFileBasedRealm"/>
    </wim:parent>
    <wim:createTimestamp>2012-10-09T06:22:36.934Z</wim:createTimestamp>
    <wim:password>XXXXXXXXXXXXXXXXXXXXXXXXXXX</wim:password>
    <wim:uid>tw_admin</wim:uid>
    <wim:cn>tw_admin</wim:cn>
    <wim:sn>tw_admin</wim:sn>
    </wim:entities>



    Replace the values of externalID and uniqueId with the values from your back up file.

  5. Start the environment.

  6. Run the syncNode command. For more information on this command, see the product documentation.

Determine authorization details with JR52438

Starting with version 8.5.5, a fix is available that extends the existing admin task getDocumentStoreStatus to help you determine which user is allowed to access the document store. For more details about this fix, see JR52438.

Related information

Product documentation
JR52438


Cross reference information
Segment Product Component Platform Version Edition
Business Integration IBM Business Process Manager Advanced Security AIX, Linux, Linux zSeries, Solaris, Windows, z/OS 8.5
Business Integration IBM Business Process Manager Express Security Linux, Linux zSeries, Windows 8.5

Product Alias/Synonym

BPM

Document information

More support for: IBM Business Process Manager Standard
Security

Software version: 8.5, 8.5.5, 8.5.6, 8.5.7

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 1673250

Modified date: 28 May 2014


Translate this page: