Synchronize user data between application DBs and the LDAP

Overview

Use the following commands if...

• You have migrated from an earlier version of Connections.
• Determine if any application member data is out of sync with the LDAP.
• Profiles is not installed or Profiles integration is disabled.
• Synchronize data for a specific application or a specific person in a specific application.

Each Connections application owns membership tables containing user external IDs, and user data related to the application.

The commands below are not necessary for the Profiles application, as it set to synchronize LDAP user data using TDI. Profiles is not installed, or is installed but Profiles integration is not enabled, the LDAP is the corporate LDAP directory. to synchronize users in the Profiles database with a source LDAP database.

Logs are located in...

PROFILE_HOME/logs/App/UlcSyncCmd.log

Parameters in brackets are optional.

Example: Preview, then update, Community membership information

1. Using preview, we discover that active member Jane Smith's application, and LDAP IDs do not match...
   wsadmin>execfile("communitiesAdmin.py")
   wsadmin>CommunitiesMemberService. previewSyncAllMembersByExtId({"updateOnEmailLoginMatch": "true", "verbose" : "true"}
   UpDt ExtId: c32c2f3a2ad1XX Name: Jane Doe has a superseded external ID, and would have been updated:
   New ExtId: c32c2f3a2ad1
   [2012-08-07] Additional application possibly-stale member data: Email: jane_doe@us.acme.com Logins: [Doe, jane_doe@us.acme.com, Jane Doe]
   [2012-08-07] Directory service basic user data: Display name: Jane Smith Update External id: c32c2f3a2ad1
   [2012-08-07] Directory service email and logins: Email: sTestuser5@janet.iris.com Logins: [Smith, Jane Smith, jane_doe@us.acme.com]

2. Synchronize Jane's Community DB identity to LDAP external id c32c2f3a2ad1.
   wsadmin>CommunitiesMemberService.syncMemberExtIdByEmail("jane_doe@us.acme.com ")
   

Commands

AppMemberService.syncAllMembersByExtId({"updateOnEmailLoginMatch": ["true" | "false"]})

Check if the external ID found in the member database table is present in the LDAP :

• If the external ID is present, then the command gets the display name, email address, and login names from the LDAP and updates the application database tables with the values from the directory, if they are different. This refresh 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 LDAP. When none of the credentials match the user is inactivated. 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. The default is false.

  true

  When a match is found in the LDAP 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 LDAP.

  false

  When a match is found in the LDAP based on the login names or email address of the user, the external ID in the application database is written to the AppUIcSyncCmd.log file. We can manually make the update after confirming the change should be made.

• If a match for the user's external ID is not found in the LDAP, 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.

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

AppMemberService.previewSyncAllMembersByExtId({"updateOnEmailLoginMatch": ["true" | "false" ][, “multiLine” : ["true" | "false"] ] [, “verbose” : ["false" | "true"] ] }] )

The preview command reports the action the corresponding syncAllMembersByExtId command would take (or not take) depending on the updateOnEmailLoginMatch parameter value

The results are placed in...

AppUlcSyncCmd.log

There are two optional parameters, multiLine and verbose, both of which take a Boolean string value. Default is true for multiLine and false for verbose.

If multiLine is true, each action report is broken into multiple short lines to make it easier to read. If multiline is false, each action report is a single line for ease of searching the file programmatically, for example with a grep utility. If verbose is false, only out of sync results are reported independent of the value of updateOnEmailLoginMatch. This includes members that would simply be refreshed. A member is refreshed if the member is active and the external ID is a match, but the display name, email, or the logins don’t match. If verbose is true, all members are reported, including active and inactive members.

The format of each reported action is timestamp, action code, action data and action message. The code is a four letter code, listed at the end of this section. At the end of the file five numbers are reported.

These are also explained at the end of this section. At the very end of the file is a number that is the total actionable items found.

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

Determines whether the user identified by the first parameter, which is an eternal ID, should be is active or inactive by checking the LDAP for the external ID. The main purpose of this command is to reactivate a user.

This is a complicated command that should be used carefully, particularly when swap is allowed.

We can perform the following tasks with this command:

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

  Parameters:

  currentExternalId

  String. Unique external 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 LDAP, 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 applicationUIcSyncCmd.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 LDAP. 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 application content, such as a Community, 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, if that person is rehired by the company, the person is added back into LDAP and is assigned a new external ID. For this person to gain access to their old content, we can use the following command to swap their external IDs.

  Parameters:

  currentExternalId

  String. Unique ID that represents a user.

  newExtId

  Close the widget palette. . String. If we provide this parameter:

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

  2. The newExtId updates that person’s external ID in the application database, and the person is marked active.

  Only use this command when we are sure the two IDs represent the same person.

  allowExtIdSwap

  Close the widget palette. . String. Accepts the values true or false. Default is false. Whether to swap the new and current ID of the user in the two records that represent the same person. 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, departed the organization, and was given a new ID upon returning. After that person logs in to an application for the first time with their new ID, the new ID is added to the application member tables. This new user to have access to the content that she created previously using the 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 content that she created using the new ID, just her previous content. We cannot merge the data associated with the current and new IDs. If we provide this parameter and set it to false, an error message is displayed in the wsadmin client that indicates the command could not complete because the newExtId already exists.

  Example:

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

AppMemberService.inactivateMemberByEmail("email-address")

This marks the person identified by email-address as inactive in the application's membership database tables, for example it 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 not modified. The command also writes a status message to the AppUlcSyncCmd.log file indicating the user has been deactivated.

Parameter:

email-address

String. Email address of the user to mark as inactive in the application membership database tables.




AppMemberService.inactivateMemberByExtId("externalID")

This 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 not modified. The command also writes a status message to the AppUlcSyncCmd.log file indicating the user has been deactivated.

Parameter:

externalID

String. Unique ID that represents the user to mark as inactive in the application membership database tables.





AppMemberService.getMemberExtIdByEmail("email")

This 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 to retrieve.

Example:

• Command:
  wsadmin>CommunitiesMemberService.getMemberExtIdByEmail("userB@myco.com")

• Result:
  510b99c0-0101-102e-8923-f78755f7e0ed




AppMemberService.getMemberExtIdByLogin("login")

This 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 to retrieve.

Example:

• Command:
  wsadmin>CommunitiesMemberService.getMemberExtIdByLogin("User A")

• Result:
  806edb40-e8ba-102e-91cd-d74ea1c96b51

Administrative commands from previous releases

These commands from earlier releases have been updated to enable changing the user state of a person from active to inactive. Use these commands in the following cases:

AppMemberService.syncBatchMemberExtIdsByEmail("emailFile" [, {"allowInactivate" : ["true" | "false"] } ] )

Synchronize a list of users contained in the 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 retrieves the external ID in the application member table and looks it up in the LDAP. If the external ID is found, then the user's display name and any additional login names are refreshed if needed, so they match those in the LDAP. The refresh operation is not logged.

If the external ID is not found in the LDAP, then a synchronize operation is performed based on the email and login values and the user's external ID in the member table is updated with the external ID in the LDAP. Also, the user's 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 LDAP by any means (external ID, login names, or email) then the user may be inactive. The command can do one of two things in this situation, depending on whether the following allowInactivate input parameter is set to true or false.

See also: syncBatchMemberExtIdsByLogin(loginFile)

Parameters:

emailFile

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

allowInactivate

String. Options are true or false. Specify one of these values to allow changes to the state of the user.

If 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 false or null, the user is not made inactive. Instead, a log message is written to the log file.

For example:

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




AppMemberService.previewSyncBatchMemberExtIdsByEmail("emailFile"[, { "allowInactivate" : ["true" | "false"] [, "multiLine" : ["true" | "false"] ] [, "verbose" : ["true" | " false"] ] } ] )

See previewSyncAllMembersByExtId(). Default is true.




AppMemberService.syncBatchMemberExtIdsByLogin("loginFile" [, {"allowInactivate" : ["true" | "false"] } ] )

Synchronize a list of users contained in a text file containing one login name per line.

1. If match found, check the external ID in the application member table against the value in the LDAP.
2. If match found, the user's email address and display name and any additional login names are refreshed if to match those in the LDAP

The refresh operation is not logged.

If the external ID is not found in the LDAP, then a synchronize operation is performed based on the email and login values and the user's external ID in the member table in the application database is updated with the external ID in the LDAP. 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 LDAP by any means (external ID, login names, or email) then the user may be inactive. 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 the following explanation of the two flags).

See also AppMemberService.syncBatchMemberExtIdsByEmail(emailFile) command instead.

Parameters:

loginFile

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

allowInactivate

String. Options are true or false. Specify one of these values to allow changes to the state of the user.

If 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 false or null, 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"})

AppMemberService.previewSyncBatchMemberExtIdsByLogin("loginFile" [, { "allowInactivate" : ["true" | "false"] [, "multiLine" : ["true" | "false"] ] [, "verbose" : ["true" | " false"] ] } ] )

See previewSyncAllMembersByExtId(). Default is true.

AppMemberService.syncMemberExtIdByEmail("email" [, { "allowInactivate" : ["true" | "false"] } ])

Synchronize member record in the application member table identified by the member's email address parameter.

If a match found retrieve external ID in the application member table, and look it up in the LDAP directory. If the external ID is found, the user's email address and display name and any additional login names are refreshed to match those in the LDAP directory. The refresh operation is not logged.

If the external ID is not found in the LDAP, then a synchronize operation is performed based on the email and login values and the user's external ID in the member table is updated with the external ID in the LDAP. 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 LDAP by any means (external ID, login names, or email) then the user may be inactive. 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 the following explanation of the two flags).

See also syncMemberExtIdByLogin(java.lang.String loginName)

Parameters:

email

String. A user's email address.

allowInactivate

String. Options are true or false. Specify one of these values to allow changes to the state of the user.

If 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 false or null, the user is not made inactive. Instead, a log message is written to the log file.

For example:

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

AppMemberService.previewSyncMemberExtIdByEmail("emailAddr" [, { "allowInactivate" : ["true" | "false"] [, "multiLine" : ["true" | "false"] ] [, "verbose" : ["true" | " false"] ] } ] )

See previewSyncAllMembersByExtId(). Default is true.

AppMemberService.syncMemberExtIdByLogin("name" [, {"allowInactivate": ["true" | "false"] } ])

This synchronizes the member record in the application member table identified by the user login name parameter. If a match is found, for example the email address identifies a member, the command retrieves the external ID in the application member table and looks it up in the LDAP. If the external ID is found, then the user's email address and display name and any additional login names are updated so they match those in the LDAP. The refresh operation is not logged.

If the external ID is not found n the LDAP, then a synchronize operation is performed and the user's external ID in the member table is updated with that of the external ID in the LDAP. 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 LDAP by any means (external ID, login names, or email) then the user may be inactive. 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 also: AppMemberService.syncMemberExtIdByEmail(java.lang.String emailAddress)

Parameters:

name

String. User login name.

allowInactivate

String. Options are true or false. Specify one of these values to allow changes to the state of the user.

If 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 false or null, the user is not made inactive. Instead, a log message is written to the log file.

For example:

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

To understand the ‘preview’ version of the command see the explanation of preview under the previewSyncAllMembersByExtId() command at the beginning of this section. Note the default value for the verbose parameter is true.

AppMemberService.previewSyncMemberExtIdByLogin("name"[, { "allowInactivate" : ["true" | "false"] [, "multiLine" : ["true" | "false"] ] [, "verbose" : ["true" | " false"] ] } ])

See previewSyncAllMembersByExtId(). Default is true.

App

• Activities
• Blogs
• Dogear (Bookmarks)
• Communities
• Files
• Forums
• News (Includes Home page and Search)
• Wikis
• Metrics

Parent topic:
Manage users when the Profiles application is not installed

Related:

Troubleshoot user data synchronization

Related:
Synchronize remote application data with the Communities database
Use administrative commands
Inactivate users to manage users with administrative commands
Set user roles for external collaboration
Change WAS environment variables
Communities administrative commands
Home page administrative commands
News repository error messages