Traditional:
Synchronizing users between the Business Automation Workflow database and the user registry

Edit online

You use the usersSync, syncExistingUsers, and usersFullSync commands to synchronize users between the WebSphere® Application Server user registry and the Business Automation Workflow database.

Important: Because the running of these commands imposes a high load on the system, consider running them during idle time.

You can also perform these tasks by using the AdminTask object of the wsadmin scripting client. For more information, see BPMUsersSyncTask, BPMUsersFullSyncTask, and BPMSyncExistingUsersTask command.

Use these commands to update user information in the Business Automation Workflow database in the following ways:

Table 1. Commands to synchronize users
Command	Usage
usersSync	Updates the information for a set of specified users. You can also use this command to create specific users in the Business Automation Workflow database who are already available in the user registry. If you specify a user who is not available in the user registry, the user is skipped.
syncExistingUsers	Updates information for existing users in the Business Automation Workflow database but 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.
usersFullSync	Imports all the user information from the user registry into the Business Automation Workflow database. If the user registry contains new users, these users are created in the Business Automation Workflow database. Attention: Use this command with care. Because all the users in the user registry are imported into the Business Automation Workflow database, the command might also import users who do not use Business Automation Workflow.

How the synchronization commands run 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.

usersSync

One VMM call per user.

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.

usersFullSync

One VMM call for all users is sent regardless of the number of users in the database.

Attention: If the call does not return all the available 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 commands contains the number of synchronized users.

Location

The scripts are in the deployment_manager_profile/bin directory and are available for both Windows and Linux® environments.

usersSync syntax

usersSync.[bat|sh]
  -username|-u|-user user_name
  -password|-p password
  [-host host_name]
  [-port port]
  username_1 username_2 ... username_n

syncExistingUsers syntax

syncExistingUsers.[bat|sh]
  -username|-u|-user user_name
  -password|-p password
  [-userState sync|any_other_value]
  [-host host_name]
  [-port port]
  [username_1 username_2 ... username_n]

If the optional list of users is not specified, all users from the Business Automation Workflow database are processed.

usersFullSync syntax

usersFullSync.[bat|sh]
  -username|-u|-user user_name
  -password|-p password
  [-host host_name]
  [-port port]

Parameters

-username|-u|-user user_name

Required. The name of the admin user.

-password|-p password

Required. The password of the user (unencrypted).

-host host_name

Optional. The host name of the AppTarget cluster member that the admin task runs on. You must also specify a port.

-port port

Optional. The SOAP port of the AppTarget cluster member that the admin task runs on.

-userState sync|any_other_value

syncExistingUsers command only. Optional. 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.

Configuration

SOAP connections

All commands. If you are using a SOAP connection, the commands can take longer than the specified SOAP timeout value to complete. Although commands continue to run until they are 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

syncExistingUsers and usersFullSync commands. 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

syncExistingUsers command only. 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>                                                                
    <vmm-options>                                                             
      <threshold-for-existing-user-retrieval-mode>1000</threshold-for-existing-user-retrieval-mode>                             
    </vmm-options>                                                            
  </security>                                                               
</common>

For information about how to find the 100Custom.xml file, see Location of 100Custom configuration files.