Synchronize user data using administrative commands 

Use the synchronization administrative commands provided for each application to synchronize user state and data between the IBM Connections applications databases and the corporate directory.

Only use this method to synchronize user data in the following cases:

• You have just migrated to version 3.0.1 from an earlier version of IBM Connections.

• You do not have Profiles installed.

• You want to synchronize data for a specific person in a specific application.

New commands

The following commands were added in version 3. Use these commands to update the state (active or inactive) of the users listed in the database.

Important: Starting in version 3, the Files and Wikis databases are no longer automatically synchronized. You must synchronize them using these commands.

Note: The use of square brackets indicate that the parameters within the square brackets are optional - you do not need to input them if you do not want to. The square brackets are not used in the input of the command.

The<application_name> variable represents the name of the application. The options are:

• Activities

• Blogs

• For Bookmarks, specify Dogear

• Communities

• Files

• Forums

• News repository: The Home page, News repository, and Search applications share the same database, so running the synchronization command against News repository applies to all three areas.

• Profiles

• Wikis

<application_name>MemberService.syncAllMembersByExtId( {"updateOnEmailLoginMatch": ["true" | "false"] } )

This command checks to see if the external ID is present in the corporate directory as follows:

• If it is present, then the command gets the display name, email address, and login names from the corporate directory and updates the application database tables with the values from the directory, if they are different. This update operation is not logged to the output file.

• If a match for the user's external ID is not found in the directory, then the command uses the email address and login names contained in the application database tables to continue to search for the user in the corporate directory. How the command works when a match on the login names or email address is found differs depending on the parameter you specified with the command:
  Parameter: updateOnEmailLoginMatch: String. Options are true or false.

  true

  Specifies that when a match is found in the corporate directory based on the login names or email address of the user, the external ID in the application database is automatically updated with the external ID in the corporate directory.

  false

  Specifies that when a match is found in the corporate directory based on the login names or email address of the user, the external ID in the application database is written to the <application>UIcSyncCmd.log file. You can manually make the update after confirming that the change should be made.
  

• If a match for the user's external ID is not found in the corporate directory, nor is a match found for the user's email address and login names, then the state of the user is changed to inactive in the application database.
  

Note: When none of the credentials match, the Boolean (true or false) parameter is ignored; the user is always inactivated.

<application_name>MemberService.syncMemberByExtId("currentExternalId"[, {"newExtId" : "id-string" [, "allowExtIdSwap" : ["true" | "false"] ] } ] )

Determines whether a user is active or inactive by checking the directory for the external ID used in the application directory to represent that user. The main purpose of this command is to reactivate a user.
You can perform the following tasks with this command:


• When only one parameter is provided, the intent is to correct the state information for that user in the application database.
  Parameters:

  currentExternalId

  String. Unique ID that represents a user. The command looks for this external ID in the application member table. If it does not find the ID, an error is generated. If the member is found, but is currently defined as "inactive", an attempt is made to activate the member. To do so, the command looks up whether the member exists in the corporate directory, and if so, then the member is activated in the application member table and the associated display name, email and login values for that member are restored. When this action is taken, the update is logged in the <application>UIcSyncCmd.log file. If the member is found and is currently defined as "active" in the application database, the code first looks up 'currentExternalId' in the corporate directory. If 'currentExternalId' is not found, the command attempts to find the member by email or login value. If this succeeds, the external ID is updated along with a refresh of display name, email, and logins, and the change is logged. If this does not succeed, then the user is inactivated and the change is logged.
  

  Example:

  CommunitiesMemberService.syncMemberByExtId("F8E59CA4-7FE1-4195-AA96-A49CE5F8E17F")

  
  

• When multiple parameters are provided, the intent is to activate the user identified by 'currentExternalId' with the identity of the user defined by the 'newExtId'. This command might be used when a user has some data on the server, but then leaves the company. The user is removed from the LDAP and the user's state is set to "inactive" in the application database tables. However, six months later, that person is rehired by the company. The person is added back into LDAP and is assigned a new external ID. In order for this person to gain access to his old content, this command can be used to swap their external IDs.
  Parameters:

  currentExternalId

  String. Unique ID that represents a user.

  newExtId

  Optional. String. If you provide this parameter:

  1. The same person is being represented by two different external IDs: the currentExternalId in the application database where the member is marked as inactive and the newExtId, which is stored in the corporate directory.

  2. The newExtId updates that person in the application database and the person is marked active.
     

  Important: Be careful using this command. It should only be used when you are sure that the two IDs represent the same person.
  

  allowExtIdSwap

  Optional. String. Accepts the values true or false. The default value is false. Specifies whether to swap the new and current ID of the user. This parameter is only needed if the user was previously employed by the organization and existed in the application member tables with the current ID, and left for a time and was given a new ID upon returning. After that person logs into the product with that new ID, the new ID is added to the application member tables. If you want this new user to have access to the data that she created previously using her current ID, provide this parameter and set it to true. However, be sure to run this command soon after the person returns because once the IDs are swapped, the user is not able to access any new data that she created using the new ID. She can only access her previous data. There is no way to merge the data associated with the current and new IDs. If you provide this parameter and set it to false, an error message is displayed in the wsadmin client that indicates that the command could not complete because the "newExtId" already exists.
  

  Example:

  CommunitiesMemberService.syncMemberByExtId("7d71d8b2-7de511df-80b6c81b-5330ca0e", 
   {"newExtId": "7d71d8b3-7de511df-80b6c81b-5330ca0e", "allowExtIdSwap": "true"})

  
  

<application_name>MemberService.inactivateMemberByEmail("email")

Marks the person identified by the email address as inactive in the application's membership database tables. This command changes the state of the specified user to inactive. In addition, the email address and login names for this user are removed from the application's database tables. The user's external ID and Display Name are left intact; not modified. When the command runs successfully, a 0 (zero) is returned to the wsadmin console. The command also writes a status message to the <application_name>UlcSyncCmd.log file indicating that the user has been deactivated.
Parameter:

email

String. Email address of the user you want to mark as inactive in the corporate directory.

<application_name>MemberService.inactivateMemberByExtId("externalID")

Marks the person identified by external ID as inactive in the application's membership database tables. This command changes the state of the specified user to inactive. In addition, the email address and login names for this user are removed from the application's database tables. The user's external ID and Display Name are left intact; not modified. When the command runs successfully, a 0 (zero) is returned to the wsadmin console. The command also writes a status message to the <application_name>UlcSyncCmd.log file indicating that the user has been deactivated.
Parameter:

externalID

String. Unique ID that represents the user you want to mark as inactive in the corporate directory.

<application_name>MemberService.getMemberExtIdByEmail("email")

Retrieves the external ID of the person identified in the email parameter and returns it to the wsadmin console. The external ID returned from this command can be used as input to some of the other wsadmin commands that require the user's external ID as an input parameter.
Parameter:

email

String. Email address of the user whose external ID you want to retrieve.


Example:


• Command:

  wsadmin>CommunitiesMemberService.getMemberExtIdByEmail("userB@example.com")

  
  

• Result:

  510b99c0-0101-102e-8923-f78755f7e0ed

  
  

<application_name>MemberService.getMemberExtIdByLogin("login")

Retrieves the external ID of the person identified in the login parameter and returns it to the wsadmin console. The external ID returned from this command can be used as input to some of the other wsadmin commands that require the user's external ID as an input parameter.

Parameter:

login

String. Login name of the user whose external ID you want to retrieve.


Example:


• Command:

  wsadmin>CommunitiesMemberService.getMemberExtIdByLogin("User A")

  
  

• Result:

  806edb40-e8ba-102e-91cd-d74ea1c96b51

  
  

Existing commands

The following commands were available in previous releases of the product. Some have been updated to also enable you to change the user state of a person from active to inactive or the other way around. You might want to use these commands in the following cases:

• For backward compatibility with version 2.5; you already have scripts written that use these commands and work well for you. You can continue to use existing scripts because the "allowInactivate" parameter defaults to "false" if not specified, which means that the command behaves the same as it did in version 2.5 by default.

• To synchronize a batch of users from a file based on their login names and emails instead of external IDs.

• To synchronize a particular user by login name or email, instead of by external ID.
  

The<application_name> variable represents the name of the application. The options are:

• Activities

• Blogs

• For Bookmarks, specify Dogear

• Communities

• Files

• Forums

• News repository: The Home page, News repository, and Search applications share the same database, so running the synchronization command against News repository applies to all three areas.

• Profiles

• Wikis
  

Note: The <application_name>MemberService.syncAllMemberExtIds() command was deprecated in version 3.

<application_name>MemberService.syncBatchMemberExtIdsByEmail("emailFile" [, {"allowInactivate" : ["true" | "false"] } ] )

The command <application_name>MemberService.syncBatchMemberExtIds(filename) was deprecated in version 2.5. Use this command or the syncBatchMemberExtIdsByLogin(loginFile) command instead.

Synchronizes a list of users contained in a specified text file. The text file must define one email address per line. If a match is found, for example, the email address identifies a member, the command checks the external ID in the application member table against the value in the corporate directory to see if it is the same or different. If the external ID matches, then the user's email address and display name and any additional login names are refreshed if needed, so that they match those in the corporate directory. The refresh operation is not logged.

If the external ID in the member table in the application database does not match the one in the corporate directory, then a synchronize operation is performed and the user's external ID in the member table in the application database is updated with that of the external ID in the corporate directory. Also, the user's email, display name, and any additional login names are refreshed. Each user that is synchronized by this operation is logged in the log file. If the user cannot be found in the corporate directory by any means (external ID, login names, or email) then the user is inactive, because the person left the company and is no longer in the corporate directory. The command can do one of two things in this situation, depending on whether the "allowInactivate" input parameter is set to true or false (see below for explanation of the two flags).

Parameters:

emailFile

String. Path and name of text file that contains one entry per line of user email addresses (jdoe@example.com).

allowInactivate

String. Options are true or false. Optionally specify one of these values to allow changes to the state of the user. If you specify true, the user is inactivated in the member table of the application database if there is no match. The user's email and login names are deleted from the table and the state flag is set to inactive. If you specify false or omit the flag, the user is not made inactive. Instead, a log message is written to the log file.


This command does not return anything.

For example:

ActivitiesMemberService.syncBatchMemberExtIdsByEmail("c:/foo/bar/my_sync_file.txt", 
 { "allowInactivate":"true"})

<application_name>MemberService.syncBatchMemberExtIdsByLogin("loginFile" [, {"allowInactivate" : ["true" | "false"] } ] )

The command <application_name>MemberService.syncBatchMemberExtIds(filename) was deprecated in version 2.5. Use this command or the <application_name>MemberService.syncBatchMemberExtIdsByEmail(emailFile) command instead.

Synchronizes a list of users contained in a specified text file. The text file must define one user login name per line. If a match is found, the command checks the external ID in the application member table against the value in the corporate directory to see if it is the same or different. If the external ID matches, then the user's email address and display name and any additional login names are refreshed if needed so that they match those in the corporate directory. The refresh operation is not logged.

If the external ID in the member table in the application database does not match the one in the corporate directory, then a synchronize operation is performed and the user's external ID in the member table in the application database is updated with that of the external id in the corporate directory. Also, the user's email, display name, and any additional login names are refreshed. Each user that is synchronized by this operation is logged in the log file. If the user cannot be found in the corporate directory by any means (external ID, login names, or email) then the user is inactive because the person left the company and is no longer in the corporate directory. The command can do one of two things in this situation, depending on whether the "allowInactivate" input parameter is set to true or false (see below for explanation of the two flags).

Parameters:

loginFile

String. Path and name of a text file that contains one user login name entry per line.

allowInactivate

String. Options are true or false. Optionally specify one of these values to allow changes to the state of the user. If you specify true, the user is inactivated in the member table of the application database if there is no match. The user's email and login names are deleted from the table and the state flag is set to inactive. If you specify false or omit the flag, the user is not made inactive. Instead, a log message is written to the log file.


This command does not return anything.

For example:

ActivitiesMemberService.syncBatchMemberExtIdByLogin("c:/foo/bar/login_sync_file.txt", 
 { "allowInactivate":"false"})

<application_name>MemberService.syncMemberExtIdByEmail("email" [, { "allowInactivate" : ["true" | "false"] } ])

The command <application_name>MemberService.syncMemberExtId(java.lang.String key) was deprecated in version 2.5. Use this command or the syncMemberExtIdByLogin(java.lang.String loginName) command instead.

Synchronizes member records in the member table in the application's database based on the member's email address. If a match is found, the command checks the external ID in the application member table against the value in the corporate directory to see if it is the same or different. If the external ID matches, then the user's email address and display name and any additional login names are updated so that they match those in the corporate directory. The refresh operation is not logged.

If the external ID in the member table in the application database does not match the one in the corporate directory, then a synchronize operation is performed and the user's external ID in the member table in the application database is updated with that of the external ID in the corporate directory. Also, the user's email, display name, and any additional login names are refreshed. Each user that is synchronized by this operation is logged in the log file. If the user cannot be found in the corporate directory by any means (external ID, login names, or email) then the user is inactive because the person left the company and is no longer in the corporate directory. The command can do one of two things in this situation, depending on whether the "allowInactivate" input parameter is set to true or false (see below for explanation of the two flags).

Parameters:

email

String. A user's email address.

allowInactivate

String. Options are true or false. Optionally specify one of these values to allow changes to the state of the user. If you specify true, the user is inactivated in the member table of the application database if there is not match. The user's email and login names are deleted from the table and the state flag is set to inactive. If you specify false or omit the flag, the user is not made inactive. Instead, a log message is written to the log file.


For example:

ActivitiesMemberService.syncMemberExtIdByEmail("jdoe@example.com", 
 {"allowInactivate":"false"})

<application_name>MemberService.syncMemberExtIdByLogin("name" [, {"allowInactivate": ["true" | "false"] } ])

The command <application_name>MemberService.syncMemberExtId(java.lang.String key) was deprecated in version 2.5. Use this command or the <application_name>MemberService.syncMemberExtIdByEmail(java.lang.String emailAddress) command instead.

Synchronizes member records in the member table in the application's database based on a user login name. If a match is found, the command checks the external ID in the application member table against the value in the corporate directory to see if it is the same or different. If the external ID matches, then the user's email address and display name and any additional login names are updated so that they match those in the corporate directory. The refresh operation is not logged.

If the external ID in the member table in the application database does not match the one in the corporate directory, then a synchronize operation is performed and the user's external ID in the member table in the application database is updated with that of the external id in the corporate directory. Also, the user's email, display name, and any additional login names are refreshed. Each user that is synchronized by this operation is logged in the log file. If the user cannot be found in the corporate directory by any means (external ID, login names, or email) then the user is inactive because the person left the company and is no longer in the corporate directory. The command can do one of two things in this situation, depending on whether the "allowInactivate" input parameter is set to true or false (see below for explanation of the two flags).

Parameters:

name

String. User login name.

allowInactivate

String. Options are true or false. Optionally specify one of these values to allow changes to the state of the user. If you specify true, the user is inactivated in the member table of the application database if there is no match. The user's email and login names are deleted from the table and the state flag is set to inactive. If you specify false or omit the flag, the user is not made inactive. Instead, a log message is written to the log file.


For example:

ActivitiesMemberService.syncMemberExtIdByLogin("jdoe", {"allowInactivate":"true"})

Parent topic

Manage users when the Profiles application is not installed

Related concepts
Troubleshooting user data synchronization

Related tasks

Use administrative commands
Manage user data using Profiles administrative commands

Related reference
Activities administrative commands
Communities administrative commands
Files administrative commands
Forums administrative commands
News administrative commands
Profiles administrative commands
Wikis administrative commands

   

 

});

+

Search Tips   |   Advanced Search