Summary
The Directory Services Migration API, contained in FNK_DirMigration.dll, allows you to programmatically control a Content Engine directory services migration. It consists of the following functions:
• GetDirectoryUsersForCurrentProvider(): Creates an XML file representing the users and groups for the source authentication provider.
• GetDirectoryUsersForNewProvider(): Creates an XML file representing the users and groups for the destination authentication provider.
• CreateDirectoryMigrationMapFile(): Creates an XML file that maps the users and groups from the source authentication provider to the destination authentication provider.
• GetCheckedOutDocuments(): Creates an XML file containing the list of all checked-out documents.
• MigrateDirectory(): Performs the actual directory migration. This function uses the XML mapping file to migrate the Content Engine from the source directory service to the target directory service.
Guide
To perform a migration using the Directory Services Migration API, follow this procedure:
1. On the Content Engine (CE) server, call GetDirectoryUsersForCurrentProvider() using the Content Engine Authentication Provider information:
• An XML data file is generated that contains all of the users and groups from the current Content Engine Authentication Provider.
• You can optionally specify that the DisplayName, PrincipalName, and DistinguishedName fields be included in the XML data file.
2. Locally or remotely, call GetDirectoryUsersForNewProvider() using the destination directory provider information:
• An XML data file is generated that contains all the destination directory service users and groups information for migration.
• You can optionally specify that the DisplayName, PrincipalName, and DistinguishedName fields be included in the XML data file.
3. Call CreateDirectoryMigrationMapFile():
• An XML data file is generated that contains the mapping, by the short name, between the source and destination user and group information. This XML file is generated from the source and desti-nation XML user and group data files.
• You can manually verify, change, and map any items in the XML mapping data file.
• You can optionally specify that the DisplayName, PrincipalName, and DistinguishedName fields be included in the XML data file.
4. Call GetCheckedOutDocuments():
• An XML data file is generated that contains all of the documents that are currently checked out.
• Use the output of GetCheckedOutDocuments() to check in all checked-out documents before you proceed with the directory migration.
5. Call MigrateDirectory() with the XML mapping file generated by CreateDirectoryMigrationMapFile() to migrate the Content Engine from the current directory service to the destination directory service.
• Optionally, you can run the directory migration in verify mode. This will report which fields will be updated but will not actually update any data.
• The directory migration process stops the Content Engine object store, file store, and content cache services so that no Content Engine database changes can occur during the migration.
• Internally, directory migration uses ADO DB to directly connect to the Content Engine database for better performance. The XML mapping data file is used to migrate fields from their current value to the new destination value.
• Directory migration is performed on all of the Content Engine object store databases.
• Directory migration migrates the nt_security_descriptor row field values of the SecurityDesc table and the reservation_owner_sid row field values of the DocVersion table.
• MigrateDirectory() enumerates through the GCD Domain, Marking, and ObjectStores objects and migrates the SecurityDescriptor fields to their new destination directory service value using the XML mapping file.
6. Manually restart the Content Engine object store, file store, and content cache services. After you have verified that the services have started without any errors, you can log on to Content Engine Enterprise Manager with a user that has administrator permissions.
Reference
Functions
GetDirectoryUsersForCurrentProvider
Creates an XML file representing the users and groups for the source (current) authentication provider. For information about the format of this file, see “Directory Service Users and Groups XML File Format” on page 36.
extern "C" HRESULT WINAPI GetDirectoryUsersForCurrentProvider (LPCWSTR pwszUser, LPCWSTR pwszPassword, LPCWSTR pwszUsersXmlFile, DIRMIGRATE_USERS_FLAGS eFlags = DIRMIGRATE_USERS_FLAGS_ALL, FNCALLBACK_DIRMIGRATE_PROGRESS_DIRUSERS pFnProgress = NULL, long lProgressInterval = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT, HWND hProgressWnd = NULL)
Arguments
• pwszUser: [in] Content Engine user name of an account with administration privileges.
• pwszPassword: [in] Password for pwszUser.
• pwszUsersXmlFile: [in] Name of the XML data file to be created containing the users and groups of the source authentication provider.
• eFlags: [in] One of the constants of the DIRMIGRATE_USERS_FLAGS enumeration, which deter-mines the output of the XML data file optional fields. Default =
DIRMIGRATE_USERS_FLAGS_ALL.
• pFnProgress: [in] UI callback function that updates a progress bar representing the progress of GetDirectoryUsersForCurrentProvider() according to the interval specified by lProgressInterval.
Set to NULL if you do not want to use the progress callback function.
• lProgressInterval: [in] The number of records for the interval used in measuring the progress of the function. Default = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT = 100.
• hProgressWnd: [in] Windows handle of the progress bar window. Set to NULL if you do not want a progress bar window.
TIP If the output XML file does not appear to contain all users in the current directory service, you may need to increase the MaxPageSize value for the directory service.
GetDirectoryUsersForNewProvider
Creates an XML file representing the users and groups for the destination authentication provider. For information about the format of this file, see “Directory Service Users and Groups XML File Format” on page 36.
extern "C" HRESULT WINAPI GetDirectoryUsersForNewProvider (LPCWSTR pwszDirName, int nDirType, LPCWSTR pwszUser, LPCWSTR pwszPassword, long lPort, LPCWSTR
pwszUsersXmlFile, DIRMIGRATE_USERS_FLAGS eFlags = DIRMIGRATE_USERS_FLAGS_ALL, FNCALLBACK_DIRMIGRATE_PROGRESS_DIRUSERS pFnProgress = NULL, long lProgressInterval
= DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT, HWND hProgressWnd = NULL) Arguments
• pwszDirName: [in] Destination directory service computer name.
• nDirType: [in] Directory service type of the destination authentication provider.
• pwszUser: [in] Destination directory service user name of an account with administration privi-leges.
• pwszPassword: [in] Password for pwszUser.
• lPort: [in] Port number of the destination authentication provider.
• pwszUsersXmlFile: [in] Name of the XML data file to be created containing the users and groups of the destination authentication provider.
• eFlags: [in] One of the constants of the DIRMIGRATE_USERS_FLAGS enumeration, which deter-mines the output of the XML data file optional fields. Default =
DIRMIGRATE_USERS_FLAGS_ALL.
• pFnProgress: [in] UI callback function that updates a progress bar representing the progress of GetDirectoryUsersForNewProvider() according to the interval specified by lProgressInterval. Set to NULL if you do not want to use the progress callback function.
• lProgressInterval: [in] The number of records for the interval used in measuring the progress of the function. Default = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT = 100.
• hProgressWnd: [in] Windows handle of the progress bar window. Set to NULL if you do not want a progress bar window.
TIP If the output XML file does not appear to contain all users in the destination directory service, you may need to increase the MaxPageSize value for the directory service.
CreateDirectoryMigrationMapFile
Creates an XML file that maps the users and groups from the source authentication provider to the destination authentication provider. For information about the format of this file, see “Directory Service Mapping XML Map File Format” on page 38.
extern "C" HRESULT WINAPI CreateDirectoryMigrationMapFile (LPCWSTR
pwszXmlFromUsersFile, LPCWSTR pwszXmlToUsersFile, LPCWSTR pwszXmlUsersMapFile, DIRMIGRATE_MAP_FLAGS eFlags = DIRMIGRATE_MAP_FLAGS_ALL)
Arguments
• pwszXmlFromUsersFile: [in] Name of the XML data file created by
GetDirectoryUsersForCurrentProvider() containing the users and groups of the source authenti-cation provider.
• pwszXmlToUsersFile: [in] Name of the XML data file created by
GetDirectoryUsersForNewProvider() containing the users and groups of the destination authen-tication provider.
• pwszXmlUsersMapFile: [in] Name of the XML data file to be created that maps users and groups from the source to the destination authentication provider.
• eFlags: [in] One of the constants of the DIRMIGRATE_MAP_FLAGS enumeration, which deter-mines the output of the XML data file optional fields. Default = DIRMIGRATE_MAP_FLAGS_ALL.
GetCheckedOutDocuments
Creates an XML file containing the list of documents that are checked out and by whom. For information about the format of this file, see “Checked-Out Documents XML File Format” on page 37.
extern "C" HRESULT WINAPI GetCheckedOutDocuments (LPCWSTR pwszXmlCheckedOutFile, LPCWSTR pwszCeUser, LPCWSTR pwszCePassword,
FNCALLBACK_DIRMIGRATE_PROGRESS_DOCS pFnProgress = NULL, long lProgressInterval = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT, HWND hProgressWnd = NULL)
Arguments
• pwszXmlCheckedOutFile: [in] Name of the XML data file to be created containing the list of checked-out documents.
• pwszCeUser: [in] Content Engine user name of an account with administration privileges.
• pwszCePassword: [in] Password for pwszCeUser.
• pFnProgress: [in] UI callback function that updates a progress bar representing the progress of GetCheckedOutDocuments() according to the interval specified by lProgressInterval. Set to NULL if you do not want to use the progress callback function.
• lProgressInterval: [in] The number of records for the interval used in measuring the progress of the function. Default = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT = 100.
• hProgressWnd: [in] Windows handle of the progress bar window. Set to NULL if you do not want a progress bar window.
MigrateDirectory
Performs the actual directory migration. Uses the XML mapping file to migrate the Content Engine from the source directory service to the target directory service.
extern "C" HRESULT WINAPI MigrateDirectory (LPCWSTR pwszXmlUsersMapFile, LPCWSTR pwszXmlOutputFile, LPCWSTR pwszCeUser, LPCWSTR pwszCePassword, LPCWSTR pwszDirUser, LPCWSTR pwszDirPassword, DIRMIGRATE_MIGRATE_FLAGS eFlags =
DIRMIGRATE_MIGRATE_FLAGS_DEFAULT,
FNCALLBACK_DIRMIGRATE_PROGRESS_MIGRATION pFnProgress = NULL, long
lProgressInterval = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT, HWND hProgressWnd = NULL)
Arguments
• pwszXmlUsersMapFile: [in] Name of the XML data file created by
CreateDirectoryMigrationMapFile() containing the mapping of users and groups from the source to the destination authentication provider.
• pwszXmlOutputFile: [in] Name of the XML output log file to be created.
• pwszCeUser: [in] User name of a Content Engine account with administration privileges.
• pwszCePassword: [in] Password for pwszCeUser.
• eFlags: [in] Specifies whether to log a sucessful migration, perform a test migration, or to continue migration if a user is missing in the mapping file. Default =
DIRMIGRATE_MIGRATE_FLAGS_DEFAULT.
• pwszDirUser: [in] User name of a directory service account with administration privileges.
• pwszDirPassword: [in] Password for pwszDirUser.
• pFnProgress: [in] UI callback function that updates a progress bar representing the progress of CreateDirectoryMigrationMapFile() according to the interval specified by lProgressInterval. Set to NULL if you do not want to use the progress callback function.
• lProgressInterval: [in] The number of records for the interval used in measuring the progress of the function. Default = DIRMIGRATE_PROGRESS_INTERVAL_DEFAULT = 100.
• hProgressWnd: [in] Windows handle of the progress bar window. Set to NULL if you do not want a progress bar window.
Enumerations
DIRMIGRATE_USERS_FLAGS
This enumeration allows you to control the output of the users and groups XML data file. The SID and short name of each user and group are always included in the XML data file; however, based on the value of DIRMIGRATE_USERS_FLAGS, you can also choose to include the display name, principal name, and the distinguished name. DIRMIGRATE_USERS_FLAGS contains the constants in the following table.
Name Value Description
DIRMIGRATE_USERS_FLAGS_NONE 0x0000 Include only the SID and short name.
DIRMIGRATE_USERS_FLAGS_DISPLAYNAME 0x0001 Include the display name (in addition to the SID and short name).
DIRMIGRATE_MAP_FLAGS
This enumeration allows you to control the output of the XML data file that maps the users and groups from the source authentication provider to the destination authentication provider.
The SID, short name, and principal type of each user and group are always included in the XML data file;
however, based on the value of DIRMIGRATE_MAP_FLAGS, you can also choose to include the display name and principal name. DIRMIGRATE_MAP_FLAGS contains the constants in the following table.
DIRMIGRATE_USERS_FLAGS_PRINCIPALNAME 0x0002 Include the principal name (in addition to the SID and short name).
DIRMIGRATE_USERS_FLAGS_DISTINGUISHEDNAME 0x0004 Include the distinguished name (in addition to the SID and short name).
DIRMIGRATE_USERS_FLAGS_ALL 0x0004 Default. Include the display name, principal name, and distinguished name (in addition to the SID and short name). Equivalent to DIRMIGRATE_USERS_FLAGS_DISPLAY NAME |
DIRMIGRATE_USERS_FLAGS_PRINCIP ALNAME |
DIRMIGRATE_USERS_FLAGS_DISTING UISHEDNAME.
Name Value Description
DIRMIGRATE_MAP_FLAGS_NONE 0x0000 Include only the SID, short name, and principal type.
DIRMIGRATE_MAP_FLAGS_DISPLAYNAME 0x0001 Include the display name (in addition to the SID, short name, and principal type).
DIRMIGRATE_MAP_FLAGS_PRINCIPALNAME 0x0002 Include the principal name (in addition to the SID, short name, and principal type).
DIRMIGRATE_MAP_FLAGS_DISTINGUISHEDNAME 0x0004 Include the distinguished name (in addition to the SID, short name, and principal type).
DIRMIGRATE_MAP_FLAGS_ALL 0x0003 Default. Include the display name and principal name (in addition to the SID, short name, and principal type). Equivalent to DIRMIGRATE_MAP_FLAGS_DISPLAYNA ME |
DIRMIGRATE_MAP_FLAGS_PRINCIPALN AME |
DIRMIGRATE_MAP_FLAGS_DISTINGUIS HEDNAME.
Name Value Description
DIRMIGRATE_MIGRATE_FLAGS
This enumeration allows you to control whether to log a sucessful migration, perform a test migration, or continue migration if a user is missing in the mapping file. DIRMIGRATE_MIGRATE_FLAGS contains the constants in the following table.
Name Value Description
DIRMIGRATE_MIGRATE_FLAGS_NONE 0x0000 Do not log a sucessful migration, perform a test migration, or continue migration if a user is missing in the mapping file.
DIRMIGRATE_MIGRATE_FLAGS_LOG_SUCCESS 0x0001 Log a successful migration to the XML output file.
DIRMIGRATE_MIGRATE_FLAGS_UPDATE_DB 0x0002 Update the database during migration.
DIRMIGRATE_MIGRATE_FLAGS_TEST 0x0004 Do not update the database during migration (perform a test migration).
DIRMIGRATE_MIGRATE_FLAGS_CONTINUE 0x0008 Continue the migration even if user information is missing in the mapping file.
DIRMIGRATE_MIGRATE_FLAGS_DEFAULT 0x0001 Default. Equivalent to
DIRMIGRATE_MIGRATE_FLAGS_LOG_SUC CESS.
DIRMIGRATE_MIGRATE_FLAGS_ALL 0x000F Log a sucessful migration, perform a test migration, and continue migration even if user information is missing in the mapping file.
Equivalent to
DIRMIGRATE_MIGRATE_FLAGS_LOG_SUC CESS |
DIRMIGRATE_MIGRATE_FLAGS_UPDATE_D B | DIRMIGRATE_MIGRATE_FLAGS_TEST | DIRMIGRATE_MIGRATE_FLAGS_CONTINUE .