BPMSyncExistingUsersTask command

Edit online
Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15
Use the BPMSyncExistingUsersTask command to synchronize existing users between the WebSphere® Application Server user registry and the IBM® Business Automation Workflow database. This command updates information for existing users in the Business Automation Workflow database, but it does not import new users from the user registry into the database. You can also use this command to synchronize the user state for users in the Business Automation Workflow database with the user availability in the user registry. For example, if users were deleted from the user registry, the command marks these users as inactive in the Business Automation Workflow database.

You can also synchronize existing users by using the syncExistingUsers.[bat|sh] script, as described in Synchronizing users or by calling the REST API that is described in Synchronizing users between the BPM database and the user registry.

How the synchronization command runs depends on whether federated repositories (VMM) are configured for WebSphere Application Server security:
Non-federated repositories
The WebSphere Application Server user registry API is used to run the commands.
Federated repositories
The federated repositories API is used to run the commands. This API performs significantly better than the user registry API. The number of VMM calls used to synchronize the user information depends on the command and the number of available users in the Business Automation Workflow database.
In the case of syncExistingUsers, by default, if you have fewer than 1000 available users in the Business Automation Workflow database, one VMM call per user is sent to synchronize the data. If you have more than 1000 available users in the Business Automation Workflow database, one call for all users is sent instead. This threshold value is configurable.
Attention: If the call for all users does not return all the available users in the user registry, take one of the following actions:
  • Force the use of one VMM call per user by changing the threshold value to reflect the actual number of users in the user registry.
  • Contact your LDAP administrator to adjust the LDAP configuration so that all users can be retrieved in one LDAP search call.

The output of the command contains the number of synchronized users.

The BPMSyncExistingUsersTask command is run using the AdminTask object of the wsadmin scripting client.

Location

Start the wsadmin scripting client from the install_root/profiles/deployment_manager_profile/bin directory.

Syntax

BPMSyncExistingUsersTask
[-userState sync|any_other_value] [-userIds [username_1 username_2 ... username_n]]

Parameters

The command has no parameters in Business Automation Workflow Version 8.5.7.0 Cumulative Fix 2016.06 and earlier versions.

-userState sync|any_other_value
This is an optional parameter that updates the user state for users in the Business Automation Workflow database.
  • Users who were deleted from the user registry become inactive in the Business Automation Workflow database.
  • Users who are reactivated in the user registry become active in the Business Automation Workflow database.
If any other value is provided, the user state is not refreshed.
-userIds [username_1 username_2 ... username_n]
This is an optional parameter that specifies the list of user names to be processed. If the parameter is missing, all users from the Business Automation Workflow database are processed.

Examples

The following example uses the BPMSyncExistingUsersTask command to update all existing users. 
wsadmin -conntype SOAP -port 8880 -host PC1.mycompany.com -user admin -password admin -lang jython

wsadmin>AdminTask.BPMSyncExistingUsersTask('[-userState sync]')
The following example uses the BPMSyncExistingUsersTask command to update the user IDs username_1 and username_2. 
wsadmin -conntype SOAP -port 8880 -host PC1.mycompany.com -user admin -password admin -lang jython

wsadmin>AdminTask.BPMSyncExistingUsersTask('[-userState sync, -userIds [username_1 username_2]]')

Configuration

SOAP connections
If you are using a SOAP connection, the command can take longer than the specified SOAP timeout value to complete. Although the command continues to run until it is finished, you might see the java.net.SocketTimeoutException: Read timed out exception in the systemOut.log file. To prevent this exception, set a higher value for the com.ibm.SOAP.requestTimeout property in the profile_root/properties/soap.client.props file. To disable timeouts, set the value of the property to 0.
VMM tuning
If you use one VMM call for all users, tune the VMM configuration for each of the associated LDAP repositories in the wimconfig.xml file. In particular, select an appropriate setting for configurationProvider->maxSearchResults property, and consider adapting the value for the ldapServers->connectTimeout and attributesCache->cacheSize properties. For more information about tuning VMM, refer to the WebSphere Application Server Network Deployment Knowledge Center.
User retrieval threshold
Based on the number of available users in the Business Automation Workflow database, the threshold-for-existing-user-retrieval-mode configuration property determines whether calls to the VMM are sent for each user or as one call for all users. The default value is 1000 available users.
  • For 1000 or fewer available users, calls are sent for each user (user-by-user).
  • For more than 1000 users, one call for all users is sent.
The value that you choose for the threshold property depends on the performance of your environment. For example, if you have 1500 users in your Business Automation Workflow database and it is quicker to retrieve these users from VMM on a user-by-user basis than with one VMM call for all users, set the value to at least 1500. Also check the following configuration settings:
  • The value of the configurationProvider->maxSearchResults property is appropriate for the value of the threshold property
  • The configuration of the associated user repository, for example, LDAP, doesn't limit the total number of returned search results.
To change the value of the property, add the following element with the appropriate value to the 100Custom.xml file for your topology.
<common merge="mergeChildren">
   <security>
      <threshold-for-existing-user-retrieval-mode merge="replace">1000</threshold-for-existing-user-retrieval-mode>
   </security>
</common>
For information about how to find the 100Custom.xml file, see Location of 100Custom configuration files.