Release 3.5.1 November 2005
FileNet is a registered trademark of FileNet Corporation.
All other product and brand names are trademarks or registered trademarks of their respective companies.
Due to continuing product development, product specifications and capabili-ties are subject to change without notice.
Copyright © 2001, 2005 FileNet Corporation. All rights reserved.
FileNet Corporation 3565 Harbor Boulevard Costa Mesa, California 92626 800.FILENET (345.3638) Outside the U.S., call: 1.714.327.3400 www.filenet.com
Introduction . . . 5
Requirements . . . 5 General . . . 5 Content Engine . . . 5 Limitations . . . 5 General . . . 5 Process Engine . . . 6 Content Engine . . . 6 Assumptions . . . 6 General . . . 6 Process Engine . . . 6 Content Engine . . . 6Process Engine Migration . . . 7
Overview . . . 7
Procedure . . . 7
Errors and recovery. . . 11
System failure during migration . . . 11
Duplicated users . . . 11
Already initiated workflows . . . 11
Launching new workflows. . . 11
Content Engine Migration . . . 12
Overview . . . 12
Procedure . . . 12
Active Directory to Active Directory with no trust relationship . . . 20
Appendix A – Directory Services Migration API. . . 29
Summary. . . 29
Guide. . . 29
Reference . . . 30
Functions . . . 30
Enumerations . . . 33
Appendix B – Content Engine XML File Formats . . . 36
Directory Service Users and Groups XML File Format . . . 36
Checked-Out Documents XML File Format . . . 37
Directory Service Mapping XML Map File Format . . . 38
Migration XML Output File Format . . . 40
Appendix C – Content Engine Debugging Tools . . . 42
Content Engine trace functionality . . . 42
FNSysInfo . . . 42
Appendix D – FileNet P8 Platform and Directory Service Integration . . . 43
Vendor-specific unique IDs . . . 43
Short Name . . . 43
Process Engine . . . 44
Content Engine . . . 44
Web Content Manager . . . 46
Records Manager . . . 46
eForms . . . 47
Introduction
FileNet P8 Platform integrates with third-party directory service products to provide user and group information and authorization functionality. The directory service migration tools allow you to reconfigure an existing FileNet P8 Platform installation to use a different directory service. The destination directory service can be another instance of a directory service of the same type (for example, migrating user and group information from one portion of the directory tree to another), or a different directory service type entirely.
This guide provides detailed instructions for migrating the Process Engine and Content Engine, including migration API documentation.
CAUTION Directory migration has not been tested on the following FileNet P8 Platform components. • Application Engine
• Records Manager • Web Content Manager • Team Collaboration Manager • eForms
“Appendix D – FileNet P8 Platform and Directory Service Integration” on page 43 details all directory service-specific persisted data for each FileNet P8 component.
Requirements
General
• The Content Engine and Process Engine must be at version 3.5.1 or higher. • You can only migrate between LDAP-based directory service providers.
• You can migrate between any of the following formats: Microsoft Active Directory, Sun Java System Directory Server, and Novell eDirectory, or between the same directory service in a different forest.
Content Engine
• The Content Engine migration API uses the Content Engine COM API and must run on a Windows platform.
• The user account you use to run the Content Engine portion of the directory migration must be a member of the P8 domain service group in order to access the database and SysConfig directory. You can remove the user account from this group, if desired, after the migration is complete.
Limitations
General
• You cannot change the user’s short name during a directory migration. (The short name is the simple, non-unique portion of the distinguished name that does not indicate its location relative to a domain or directory. For the Process Engine, the short name is determined by the Login Attribute set in Process Task Manager.)
Process Engine
• The Process Engine directory migration does not handle the SEC-to-LDAP migration path.
Content Engine
• Active Directory SIDHistory is maintained only when the source and destination directory services are in the same Active Directory forest.
• The directory migration tools only migrate internal Content Engine information. Customer-specific properties and user preference titles must be migrated separately.
• The Microsoft .NET Framework is not used, since the Content Engine does not currently install its components.
• Directory migration is not currently (kl180, Content Engine 3.5.1) supported against Object Stores installed on a DB2 database.
Assumptions
General
• Directory service migration will always be performed by or in cooperation with FileNet Professional Services.
• The system is unavailable during migration.
Process Engine
• Performance is affected by the number of Process Engine environment records for users and groups. Migration for large systems will take some time. For example, a Process Engine with 150,000
environment records might take about four hours.
Content Engine
• The user interface (FNK_DirMigrationTest) is provided as is, and is not a supported component of the Content Engine migration tools. You can modify it or develop your own interface as desired.
• Performance is affected by the kind of access (local or remote), the number of Content Engine users and groups, the number of directory service users and groups, and the number of documents. Migration for large systems will take several hours.
Process Engine Migration
Overview
The Process Engine migration involves the following steps: 1. Build a list of Process Engine users.
2. Delete the existing directory service configuration, and reconfigure it for the destination directory service.
3. For each Process Engine user, acquire the user's new GUID from the destination directory service. 4. Update the Process Engine’s environment records to hold the new values for the full distinguished
name (FDN) and the corresponding LDAP-based GUIDs as defined by the destination LDAP directory service.
Procedure
The procedures to migrate the Process Engine use the Process Task Manager and the vwtool
ldapmigrate command. For detailed instructions on the use of the Process Task Manager and vwtool, see FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > Process Task Manager and FileNet P8 Documentation > FileNet P8 Administration > Process Engine
Administration > Administrative tools > vwtool, respectively. Where applicable, additional help topics are noted below. Navigation to the additional topics starts from the locations noted here.
The boxed text in each step below contains background information for the step. You do not need this information in order to follow the procedure; however, it can be useful in understanding the process. 1. Prevent users from accessing the system during the migration process.
a. Use the Process Task Manager to stop the Process Router(s) on the Application Engine. b. Use the Process Task Manager to stop any Process Router(s) and the PPM on the Process
2. Create and populate the Directory Migration Information table.
a. On the primary Process Engine (server 0), start vwtool at the command line. See vwtool > Start vwtool for instructions on starting vwtool.
b. Enter ldapmigrate at the vwtool command prompt. See vwtool > Commands > ldapmigrate for detailed descriptions of the ldapmigrate syntax and parameters. Answer the prompts as follows:
3. Delete the current directory service configuration, and configure the Process Engine to use the destination directory service.
a. Enter the following at the ldapmigrate prompt:
The ldapmigrate command uses the Directory Migration Information table during the LDAP directory migration to store required information about each Process Engine user and group.
The ldapmigrate command populates the table by looking at the Process Engine’s existing environment records (each user referenced by a workflow or a user’s preferences has an
environment record on the Process Engine). For each Process Engine user, ldapmigrate retrieves the current GUID, Login Name (short name), and Process Engine User ID values, and stores the information in the Directory Migration Information table. The migration state for each newly created record is set to 1 (ready to get new GUID).
The Directory Migration Information (VWLDAPMig) table is defined as follows: F_OldLoginNamevarchar(100) F_OldGuid varchar(100) F_PEUserIdint F_NewLoginNamevarchar(100) F_NewGuid varchar(100) F_MigrationStateint Migration states include: 1 ready to get new GUID 2 ready to migrate 3 needs BLOb fixup 9 migration complete 11 error updating the key 12 error updating the BLOb
Verbose? n
Initialize ‘Directory Migration Information’ table? y
The ldapmigrate command provides a simple single-level “undo” capability, allowing you to restore the current LDAP configuration.
When you choose d (to “delete” the current configuration), ldapmigrate renames the current ldap.config record to ldap.config.deleted. If there was already an ldap.config.deleted record, that record is deleted at this point. Choosing r (to “restore” the previously deleted configuration) renames the ldap.config.deleted record back to ldap.config.
b. Enter quit to exit vwtool.
4. Configure the Process Engine to use the destination directory service.
a. Use the Process Task Manager to stop Process Services on the Process Engine.
b. Close the Process Task Manager and restart it to clear the current LDAP settings from the Process Task Manager memory.
c. Start Process Services on the Process Engine.
d. Use the Process Task Manager to configure the destination LDAP server configuration. See Pro-cess Task Manager > ProPro-cess Engine > ProPro-cess Service > Configure the ProPro-cess Service > Configure the LDAP connection (Workplace) for detailed instructions.
e. Restart Process Services when prompted.
5. Acquire new GUID values for the Directory Migration Information table.
a. On the primary Process Engine, start vwtool again.
b. Enter ldapmigrate at the vwtool command prompt. Answer the prompts as follows:
In this step, ldapmigrate iterates through the existing Directory Migration Information table. For each user in the table with an F_MigrationState of 1 or 13, ldapmigrate uses the user’s short name to retrieve the new GUID from the destination LDAP server. The new GUID is stored in the user’s directory migration information row. As each Directory Migration Information record is updated with the new GUID value, the record’s F_MigrationState value is set to 2 (ready to migrate).
If a user can’t be found in the destination LDAP server, ldapmigrate displays a message and the user’s F_MigrationState (in the Directory Migration Information record) is set to 13 (user not defined in destination LDAP).
You can run this step as many times as is necessary to ensure that all current Process Engine users are ready for migration. For example, the first time, you may get new GUID values for one hundred Process Engine users, with five Process Engine users not defined in the destination LDAP server. You can then create LDAP entries for the missing users in the destination directory service server, and re-run this step. When ldapmigrate processes these users again, it retrieves the new GUID values and updates the directory migration information table.
Verbose? n
Initialize ‘Directory Migration Information’ table? n
PE LDAP Configuration? n
Acquire new GUID values for the ‘Directory Migration Information’ table?
NOTE If you plan on running this step again, answer “n” to subsequent prompts. If you are ready to migrate the Process Engine records, proceed to the next step.
6. Migrate the Process Engine environment records.
a. Enter ldapmigrate at the vwtool command prompt. (NOTE If you are proceeding directly from the preceding step, you do not need to re-enter the ldapmigrate command or answer the first four prompts below.) Answer the prompts as follows:
b. Restart Process Services on the Process Engine. 7. Process Engine migration is complete.
In this step, ldapmigrate uses the Directory Migration Information table to update each user’s environment record. This work is done in two passes.
The first pass iterates through the Directory Migration Information table and migrates each user whose F_MigrationState is 2 or 11. This part of the migration updates each user’s environment record so that the F_ObjName column uses the destination directory service GUID instead of the old directory service GUID. If the update succeeds, the user’s F_MigrateStatus is set to 3 (needs BLOb fixup). If the GUID can’t be updated, the user’s F_MigrateStatus is set to 11 (error updating the key).
The second pass iterates though the Directory Migration Information table and migrates each user whose F_MigrationState is 3 or 12. This part of the migration updates each user’s environment record to correct the GUID and the full distinguished name (FDN) in the BLOb. The BLOb is changed to specify the destination GUID. The environment record’s FDN is set to null. The null FDN is automatically updated the next time the environment record is accessed.
If this update succeeds, the user’s F_MigrateStatus is set to 9 (migration complete). If the BLOb can’t be updated, the user’s F_MigrateStatus is set to 12 (error updating the BLOb).
The updates to the environment records (keys and BLObs) can be run multiple times. If an initial run results in some users ending up with an F_MigrateStatus of 11 (error updating the key), a
subsequent run will pick up users in that error state and re-try the key update. Similarly, if there was a problem updating the BLOb, a subsequent migration will pick up users in the “error updating the BLOb” state and retry the BLOb update. Once a user has gotten to the “migration complete” state, subsequent runs ignore that user’s environment record.
Verbose? n
Initialize ‘Directory Migration Information’ table? n
PE LDAP Configuration? n
Acquire new GUID values for the ‘Directory Migration Information’ table? n Migrate the live PE environment records now?
CAUTION Answering “yes” here performs the actual migration. Recovery at this point involves migrating back to the original directory service.
Errors and recovery
Until the final migration step, you can easily undo any changes.
System failure during migration
All updates to the environment records and the LDAP migration information table are transactional. Generally, 50 to 100 users are handled per transaction. Should the Process Engine or vwtool be unexpectedly interrupted during an LDAP migration, the operation is completely restartable and recoverable. Simply restart vwtool and restart the step of the migration that was interrupted; migration continues from where it was interrupted.
Duplicated users
During the final migration step, it is possible that a user has somehow already gotten a “new” environment record. This is true, for example, for the user who is running vwtool to do the LDAP migration. The
migration routine recognizes this case and automatically deletes the new environment record for this user so that the user's old environment record can be migrated, preserving his internal Process Engine user ID. Similarly, other users may already have a new environment record. For example, after having switched to the destination LDAP directory service, if you try to log on to vwtool as a user that isn't privileged to run vwtool, the logon attempt creates a new environment record for this user. During migration, this user will already have a new environment record. In this case, vwtool will “hide” the user's new environment record, migrate his old environment record, and display a descriptive message.
Already initiated workflows
If a user from the current directory service is not defined in the destination directory service, any use of his short name in a workflow (launched before or after the migration) is treated as an invalid user. The work item is sent to the Malfunction system map (unless the Ignore Missing Participants option has been selected or no valid users remain).
See FileNet P8 Documentation > Workplace > Workflow Overview > Process Engine Reference > Administration and Configuration > Troubleshooting > Resolve workflow errors for further information.
Launching new workflows
A reference to a user who no longer exists prevents a workflow from being launched, unless the Ignore Missing Participants option has been selected. The Process Designer application must be used to fix these references before the workflow can be launched.
Content Engine Migration
Overview
From the user’s perspective, the Content Engine migration consists of the following steps.
1. On the Content Engine, gather user and group information from the source directory server using the current Content Engine provider.
2. Gather user and group information from the destination directory server.
3. Create a mapping between the source and destination user and group information.
4. Using the mapping data, perform a migration of the Content Engine, and update the Content Engine to use the destination directory service.
CAUTION FileNet recommends that you run the Content Engine migration process from a machine with 1GB or more of memory. This recommendation is based on the number of security principals in the LDAP provider.
In addition, the XML files that are created may potentially be huge. Besides using up disk space, this may pose a problem when you edit a large XML file, because it requires loading into memory the entire XML file. Past trials have shown that LDAP providers with 150,000 or more security principals may create large XML files of 50MB or more. These files, when edited using the map editor or any other XML editor, may be extremely slow to load, possibly taking ten minutes or more.
Procedure
The following procedure uses the FNK_DirMigrationTest GUI application, which is based on the Directory Services Migration APIs. See Appendix A for a complete description of the Directory Services Migration APIs.
NOTE You can run the directory migration tool from any server that can connect to the current and destination directory service servers.
The boxed text in each step below contains background information for the step. You do not need this information in order to follow the procedure; however, it can be useful in understanding the process. 1. Prepare to run the FNK_DirMigrationTest application.
a. Ensure that the Content Engine user account (referred to below as the Content Engine user) to be used during the directory service migration has the proper permissions. The Content Engine user account must be a member of the P8 domain service group (by default Content Engine Servers) in order to access the database and SysConfig folder. The permissions can be removed after migration is complete.
b. On a Content Engine in the current directory service domain, create a temporary folder.
c. Copy FNK_DirMigrationTest.exe and FNK_DirMigration.dll to the temporary folder. These files can be found in P8CE-3.5.1-1003 or in
\\englib\working\trees\klxxx.xxx\dev03\bin\release\testtools, where xxx is the number of the latest build.
d. The following FIleNet and Windows system files are also required in order to run the directory migration tool. As a general rule, these files are already installed and available on your system. • FNK_SecuritySystem.dll
• MFC71U.dll • MSVCR71.dll
e. Start FNK_DirMigrationTest.exe from the temporary folder. 2. Generate the list of security principals in the current directory service.
a. In the From Users tab, enter the following:
b. Click Get From Users.
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.
3. If you are migrating from one Active Directory forest to another Active Directory forest with no trust relationship between them, you must run the next step from a server that has access to the destination forest rather than the current forest. To set up a temporary Content Engine client machine that can be used for this purpose, do the following:
a. On a machine added to the destination forest, log on as Administrator in the destination forest. This step calls the GetDirectoryUsersForCurrentProvider() API using the current Content Engine Authentication Provider information.
Users File The name of the output XML file that will contain the list of users in the current directory service.
UserID Password
The name of the Content Engine user, and the associated password.
(Sun Java System Directory Server and Novell eDirectory) Use the fully distinguished name.
(Microsoft Active Directory) Use the short name. Include ‘Display Name’
Include ‘Principal Name’ Include ‘Distinguished Name’
Indicate whether additional information is to be included in the output XML file. By default, each option is checked.
This allows you to control the size of the resulting XML file by configuring how much information it contains. FileNet
recommends including all options if space allows, since they provide greater details of each security principal which may help during debugging.
b. Install FileNet P8 Client Connectivity.
i. Run the Content Engine installer. This can be found in P8CE-3.5.1-1003 or in
\\englib\working\disks\perxxx.xxx\ContentEngine\ContentEngine, where xxx is the number of the latest build.
ii. Choose Custom install.
iii. Deselect all packages except for FileNet P8 Client Connectivity. iv. Click Next.
v. Click Install.
c. Perform Step c through Step e (from Step 1above) on this machine.
4. Generate the list of security principals in the destination directory service. You can perform this step locally or remotely.
a. In the To Users tab, enter the following:
b. Click Get To Users.
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.
This step calls the GetDirectoryUsersForNewProvider() API using the destination directory provider information.
Users File The name of the output XML file that will contain the list of users for the destination directory service.
Type The type of the destination directory service.
Host Name The name of the machine containing the destination directory service.
UserID Password
(Sun Java System Directory Server and Novell eDirectory) The fully distinguished name of the service user in the destination directory service, and the associated password. (Microsoft Active Directory) The short name of the service user in the destination directory service, and the associated password.
Port (Sun Java System Directory Server and Novell eDirectory only) The port used by the directory service.
Include ‘Display Name’ Include ‘Principal Name’ Include ‘Distinguished Name’
Indicate whether additional information is to be included in the output XML file. By default, each option is checked.
This allows you to control the size of the resulting XML file by configuring how much information it contains. FileNet
recommends including all options if space allows, since they provide greater details of each security principal which may help during debugging.
c. If you are migrating from one Active Directory forest to another Active Directory forest with no trust relationship between them, you must now copy the XML file you generated here back to the Content Engine you were using for the previous steps. Perform the subsequent steps on the origi-nal Content Engine.
5. Create the map file. This process uses the short name to search for matches in the current and destination XML files.
a. In the Map Users tab, enter the following:
b. Click Create Map. 6. Edit the map file.
Use an XML editor that will handle large XML files to find users or groups that exist in the current directory service but not in the destination directory service. You can then either add the user to the destination directory service or map the current user to a different user in the destination directory service. Following are some guidelines for editing the map file.
• Find records whose destination entry is unmapped (blank). Determine if the current user or group is missing from the destination service, or if it will be mapped to a different user/group in the desti-nation directory service. If it is missing, add the user or group to the destidesti-nation directory service. If the current user or group will be mapped to a new user, make a note of it. Do not reassign at this time, as it will have to be done again after you re-run Step 4 and Step 5. Handle all of the unmapped destination entries that you can, then re-run Step 4 and Step 5. Repeat this process until you are sure that the destination directory service contains all the necessary users and group from the current directory service.
• Find the remaining unmapped destination entries. Delete the entry from the map file or leave it unmapped only if you are sure the user or group is not referenced by any object in the Content Engine system. Incorrectly deleting the entry or leaving it unmapped could result in objects with properties or ACEs that refer to non-existent users.
This step calls the CreateDirectoryMigrationMapFile() API to generate an XML map file.
From Users The name of the XML file that contains the list of users for the current directory service. This is the file you created in Step 2 above.
To Users File The name of the XML file that contains the list of users for the destination directory service. This is the file you created in Step 4 above.
Map File The name of the output XML file that will contain the mapping between the current directory service and the destination directory service.
Include ‘Display Name’ Include ‘Principal Name’ Include ‘Distinguished Name’
Indicate whether additional information is to be included in the output XML file. By default, each option is checked.
This allows you to control the size of the resulting XML file by configuring how much information it contains. FileNet
recommends including all options if space allows, since they provide greater details of each security principal which may help during debugging.
TIP If you are unsure whether a user or group is unused, you can map the entry to a dummy user or group on the destination system.
• You do not need to delete entries from the map file where users or groups exist in the destination directory service but not in the current directory service.
• Investigate all users and groups in the duplicates section at the end of the map file. The mapping process automatically creates an entry when a duplicate user or group is encountered. If the entry that was encountered first is not the entry that you want to migrate, you must modify the first entry to reflect the current user or group information.
TIP The migration process ignores all entries in the duplicates section, so the duplicate entry does not need to be deleted from the map file.
• Make sure that users required by the FileNet P8 Platform are mapped to users in the destination directory service. See FileNet P8 Documentation > FileNet P8 Administration > Enterprise-wide Administration > Security > Users and groups for a complete list of required users. In par-ticular, be sure to map the users and groups referenced in Table 1, “Roles referenced in Active Directory migration steps,” on page 20.
7. Ensure that there are no checked-out files. (The migration process assumes that no files are checked out, so reservation objects normally associated with checked-out documents are not processed.)
a. In the Checked-Out tab, enter the following:
b. Click Get Docs.
c. Review the XML list. The list contains entries for each checked-out document’s major version and its corresponding ID. Use the list to retrieve each document and check it in or cancel the checkout. d. Repeat this step until the list contains no documents.
This step calls the GetCheckedOutDocuments() API to generate a list of checked-out files.
Docs File The name of the output XML file that will contain the list of checked-out documents.
UserID Password
The name of the Content Engine user, and the associated password.
(Sun Java System Directory Server and Novell eDirectory) Use the fully distinguished name.
8. Migrate the users.
a. In the Migration tab, enter the following:
This step calls the MigrateDirectory() API with the XML map file to migrate the Content Engine from the current directory service to the destination directory service.
You can run this process with Update unchecked as many times as needed to eliminate errors, then run it with Update checked to migrate the users.
TIP By checking Update and Continue, you can reprocess a previously processed input file if necessary. Users or groups that have been previously processed successfully will result in errors. By checking Continue, these errors are ignored. Any users or groups that were previously unsuccessfully processed will be reprocessed at this time, and will be successfully migrated if the original errors have been corrected.
Map File The name of the XML file that contains the mapping between the current directory service and the destination directory service. This is the file you created in Step 5 above. Output File The name of the output XML file that will contain the list of
security principals that were modified.
Log Success Indicates whether to log detailed information about all SIDs. This is not checked by default.
Check this option for test migrations and when debugging problems.
b. Click Migrate DB.
9. If you are migrating from one Active Directory forest to another Active Directory forest with no trust relationship between them, you must perform the additional steps in the next section on Active Directory to Active Directory with no trust relationship before restarting the Content Engine. 10. Manually restart the Content Engine Object Store, File Store, and Content Cache services. 11. Some migration steps are not performed by the migration tools, and must be done manually.
a. User preferences: You can delete and recreate user preferences, or you can create a custom application via the COM AIP to extract the old SID from the title/containmentName, find that SID and its replacement in the map XML file, and replace old with new.
b. Entry templates contain an XML document that represents the entry template definition. Included in the XML document is the “granteeid” Security Descriptor from the current directory service (see the sample below).
Update Indicates that the migration is to take place.
Check this box if you want the actual migration to take place. Leave it unchecked to perform a trial run.
The update is done in two phases: first the Content Engine databases are updated, then the GCD. By default, if errors occur during either phases, the migration stops at the end of the current phase.
Test before migrating Check this box to perform a trial run, then automatically perform the actual migration if no errors were encountered during the trial run.
Continue Indicates that the migration is to continue through both phases even if errors are encountered.
Current Content Engine UserID
Password
The name of the Content Engine user, and the associated password.
(Sun Java System Directory Server and Novell eDirectory) Use the fully distinguished name.
(Microsoft Active Directory) Use the short name. To Directory Service
UserID Password
The service user in the resulting GCD for the destination directory service.
(Sun Java System Directory Server and Novell eDirectory) The fully distinguished name of the service user, and the associated password, for the destination directory service. (Microsoft Active Directory) The short name of the service user, and the associated password, for the destination directory service.
See FileNet P8 Documentation > FileNet P8
Administration > Enterprise-wide Administration > Security > Configure Authentication Provider for more information about the service user.
The security descriptor in the XML document is not migrated by the Content Engine migration APIs. This applies to all Entry Template types: document, folder, custom object, form data and all WCM-based entry templates.
After the Content Engine is migrated, you can check out each of these documents, manually update them and check them back in. Since there may be many Doc Entry Templates, a large MAP file (to get source/destination SecDesc from), or lots of permissions inside each
EntryTemplate, FileNet recommends creating a tool using existing APIs to accomplish this. c. Fixed Approval and Sequential Approval workflows fail after migration because they use the full
distinguished name for participants. You must reassign the participants in the workflow groups in the associated workflows:
i. Open the Fixed Approval or Sequential Approval workflow in Process Designer. ii. Go to Workflow Properties/Workflow Groups.
iii. Select each workflow group. An error message displays when the workflow group is opened for editing: “VWServer Exception: [Err=d5140177] Domain mismatch”. Click OK.
iv. Delete each participant from the current directory service, then add the equivalent participant from the destination directory service.
Active Directory to Active Directory with no trust relationship
The following procedures reference several users and groups that represent certain roles on the current and destination domains. The users and groups assigned to these roles can vary depending on the customer site, and the users and groups assigned to these roles can differ between the current and destination Active Directories.
The following chart lists the roles, along with the default user or group assigned to each role. In order to eliminate confusion in the instructions that follow, the value in the Name column is used when referring to a user or group that functions in any of these roles, and appears in italics in the instructions.
Steps before changing Domains/Forests
Perform the following changes before changing the machines in the FileNet P8 domain to the destination Active Directory domain.
1. On each Content Engine in the FileNet P8 domain, stop each of the following Content Engine services, and set it to start manually:
• Content Engine Content Cache Service • Content Engine File Store Service
Name Description Default User or Group Name
Administrators A group with administrative privileges.
Can refer to the current or
destination Active Directory, or the local machine account.
Administrators
Administrator A user who is a member of the Administrators group.
Can refer to the current or
destination Active Directory, or the local machine account.
Administrator
P8 domain service group A Windows domain global group that is created or assigned during installation. It contains the list of FNCE_machinename accounts in the FileNet P8 domain.
Can refer to the current or destination Active Directory.
Content Engine Servers
Content Engine service user The account used by the Content Engine to connect to and search the directory service. Also referred to as the Windows Service Logon
Account.
Can refer to the current or destination Active Directory.
FNCE_<servername>
• Content Engine Object Store Service • FileNet P8 CFS Server for Image Services • FileNet Publishing HTML Plug-In Service • FileNet Publishing PDF Plug-In Service a. Open the Windows Services console. b. Double-click each service listed above.
c. Change Startup type to Manual, if necessary. d. Click Stop if the service is running.
e. Click OK.
2. On each Content Engine in the FileNet P8 domain, temporarily reassign ownership of the log and sysconfig folders and contents to the local administrative user:
a. Log on as a member of the local Administrators group.
b. Using Windows Explorer, navigate to the <Content_Engine_Installation> folder, by default, C:\Program Files\FileNet\Content Engine.
c. Select the log subfolder and do the following: i. Right-click on the folder and choose Properties. ii. On the Security tab, click Advanced.
iii. Select the P8 domain service group in the Permission entries. iv. Make sure the local Administrators group is not selected. v. Click Remove.
vi. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
vii. Click OK.
viii. Click Yes to the Security warning. ix. Click OK to exit.
d. Select the sysconfig subfolder and do the following: i. Right-click on the folder and choose Properties. ii. On the Security tab, click Advanced.
iii. Select the P8 domain service group and the current Active Directory Administrator in the
Permission entries.
iv. Make sure the local Administrators group is not selected. v. Click Remove.
vi. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
viii. Click Yes to the Security warning. ix. Click OK to exit.
3. On each File Store server in the Content Engine domain (including any running on Object Store servers), temporarily reassign ownership of the file store folder and all its subfolders and files to the local administrative user.
a. Ensure that you are still logged on as a member of the local Administrators group.
b. Using Windows Explorer, navigate to the file store folder. This is the folder directly below the shared folder, and by default starts with FS_. For each folder (content, inbound, index, system), do the following:
i. Right-click on the folder, and select Properties. ii. Select the Security Tab.
iii. Click Advanced, then select the Owner tab.
iv. Select the local Administrators group in the Change owner to list. v. Check Replace owner on subcontainers and objects.
vi. Click OK twice.
c. Select the Area.sf file and do the following: i. Right-click and select Properties. ii. Select the Security tab.
iii. Click Advanced, then select the Owner tab. iv. Select the local Administrators group. v. Click OK twice.
d. Select the file store folder and do the following:
i. Right-click on file store folder, and select Properties. ii. Select the Security tab, and click Advanced.
iii. Add the local Administrators group with Allow Full Control privileges: • Click Add.
• Click Locations.
• Select the local machine name, then click OK.
• Enter Administrators under Enter the object name to select, and click Check Names.
The full verified name appears. • Click OK.
• Check Full Control in the Allow column.
• Uncheck Apply these permissions to objects and/or containers within this container only.
iv. In Permission entries, select the P8 domain service group and the current Active Directory Administrator.
v. Make sure the local Administrators group is not selected. vi. Click Remove.
vii. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
viii. Click OK.
ix. Click Yes to the Security warning. x. Click OK to exit.
4. If Apache is installed, change the logon information and startup type: a. Open the Windows Services console.
b. Double-click the Apache2 service. c. Set the Startup type to Manual.
d. On the Log On tab, click Local System account. e. Click OK.
5. Change all of the machines in the FileNet P8 domain from the current Active Directory domain to the destination Active Directory domain:
a. Update the preferred DNS server:
i. Navigate to the Windows Network Connections folder. Right-click on your network connection, and select Properties.
ii. Select the Internet Protocol (TCP/IP) entry, then click Properties.
iii. Change the Preferred DNS server to the IP address of the destination Active Directory server.
iv. Click OK twice.
b. Join the destination Active Directory domain:
i. Right-click on My Computer, and select Properties. ii. On the Computer Name tab, click Change.
iii. Enter the destination Domain. iv. Click OK as needed to exit. v. Reboot when prompted.
Steps after changing Domains/Forests
Perform the following changes after changing all of the machines in the FileNet P8 domain to the destination Active Directory domain.
1. Before proceeding, verify that the following user and group configurations exist in the destination Active Directory. If not, make the necessary corrections before continuing.
a. Verify that the destination Active Directory Administrator is a member of the local Administrators group on each Content Engine in the FileNet P8 domain:
i. Log on as the local Administrator.
ii. Open up the Local Users and Groups snap-in:
• Right-click on My Computer, and choose Manage.
• Navigate to the Groups folder in Local Users and Groups.
iii. Double-click the Administratorsgroup. Verify that the Administrator is a member, either directly or indirectly.
b. Verify that the P8 domain service group contains the Content Engine service user:
i. On the destination Active Directory server, open the Active Directory Users and Computers
console.
ii. Verify that the P8 domain service group appears in the Users folder. 2. Log on as the destination Active Directory Administrator.
3. If the destination domain has any Windows 2003 SP1 machines, change their COM Security so as to grant access to <DESTINATION_DIRECTORY_SERVICE_DOMAIN>\P8 domain service group. The settings should match the settings for the P8 domain service group before migrating. For more information, see the FileNet P8 Platform Installation and Upgrade Guide > Configure a FileNet P8 environment for Windows Server 2003 SP1 > COM Security.
a. Open the Component Services snap-in (under Administrative tools in the Start menu). b. Expand Component Services, then expand Computers.
c. Right-click on My Computer and select Properties. d. Select the COM Security tab.
e. In the Access Permissions section, click Edit Limits, then click Add.
f. Enter P8 domain service group and click Check Names. The full verified name appears. g. Click OK.
h. In the Allow column, verify that Local Access is checked. i. Click OK.
j. In the Launch and Activation section, click on Edit Limits, then click Add.
k. Enter P8 domain service group and click Check Names. The full verified name appears. l. Click OK.
m. In the Allow column, verify that Local (and/or Remote) Activation is checked. Verify that Allow is not checked next to Remote Launch or Local Launch.
n. Click OK.
o. In the Launch and Activation section, click Edit Default, then click Add.
p. Enter P8 domain service group and click Check Names. The full verified name appears. q. Click OK.
r. In the Allow column, verify that Local (and/or Remote) Activation is checked. Verify that Allow is not checked next to Remote Launch or Local Launch.
s. Click OK as needed to exit.
4. On each Content Engine in the destination Active Directory domain, grant access to the log and sysconfig folders and contents to the P8 domain service group:
a. Log on as a member of the local Administrators group.
b. Using Windows Explorer, navigate to the <Content_Engine_Installation> folder. c. Select the log subfolder and do the following:
i. Right-click on the folder and choose Properties. ii. On the Security tab, click Advanced.
iii. Click Add.
iv. Enter P8 domain service group under Enter the object name to select, and click Check Names. The full verified name appears.
v. Click OK.
vi. Check Full Control in the Allow column.
vii. Uncheck Apply these permissions to objects and/or containers within this container only.
viii. Click OK.
ix. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
x. Click OK.
xi. Click Yes to the Security warning. xii. Click OK to exit.
d. Select the sysconfig subfolder and do the following: i. Right-click on the folder and choose Properties. ii. On the Security tab, click Advanced.
iii. Click Add.
iv. Enter P8 domain service group under Enter the object name to select, and click Check Names. The full verified name appears.
v. Click OK.
vi. Check Full Control in the Allow column.
vii. Uncheck Apply these permissions to objects and/or containers within this container only.
viii. Click OK.
x. Enter the destination Active Directory Administrator user, and click Check Names. The full verified name appears.
xi. Click OK.
xii. Check Full Control in the Allow column.
xiii. Uncheck Apply these permissions to objects and/or containers within this container only.
xiv. Click OK.
xv. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
xvi. Click OK.
xvii.Click Yes to the Security warning. xviii.Click OK to exit.
5. On each File Store server in the Content Engine domain (including any running on Object Store servers), grant access and change ownership as necessary:
a. Ensure that you are still logged on as a member of the local Administrators group.
b. Grant access to the file store folder and all its subfolders and files to the destination Active Directory Administrator user and P8 domain service group by doing the following:
i. Using Windows Explorer, navigate to the file store folder. This is the folder directly below the shared folder, and by default starts with FS_.
ii. Right-click on file store folder, and select Properties. iii. Select the Security tab, and click Advanced. iv. Click Add.
v. Enter P8 domain service group under Enter the object name to select, and click Check Names. The full verified name appears.
vi. Click OK.
vii. Check Full Control in the Allow column. viii. Click OK.
ix. Click Add.
x. Enter Administrator under Enter the object name to select, and click Check Names. The full verified name appears.
xi. Click OK.
xii. Check Full Control in the Allow column. xiii. Click OK.
xiv. Check Replace permission entries on all child objects with entries shown here that apply to child objects.
xvi. Click Yes to the Security warning. xvii.Click OK to exit.
c. Reassign ownership of the file store’s subfolders and contents to the Content Engine service user. For each subfolder (content, inbound, index, system, Area.sf), do the following:
i. Right-click on the folder or file, and select Properties. ii. Select the Security tab.
iii. Click Advanced, then select the Owner tab. iv. Click Other Users or Groups.
v. Select the Content Engine service user in the Enter the object name to select box, and click
Check Names. The full verified name appears. vi. Click OK.
vii. Check Replace owner on subcontainers and objects. (This setting does not apply to Area.sf.)
viii. Click OK.
ix. If this is the inbound folder, grant List folder contents permission to Authenticated Users: • Click Add.
• Enter Authenticated Users in the Enter the object name to select box, and click Check Names. The full verified name appears.
• Click OK.
• Check List folder contents in the Allow column. Uncheck any other allowed permissions in the Allow column.
x. Click OK.
6. On each Content Engine in the FileNet P8 domain, change the Content Engine services back to automatic startup mode, and change the logon user to the service user for the destination Active Directory.
• Content Engine Content Cache Service • Content Engine File Store Service • Content Engine Object Store Service • FileNet P8 CFS Server for Image Services • FileNet Publishing HTML Plug-In Service • FileNet Publishing PDF Plug-In Service a. Open the Windows Services console. b. Change Startup type to Automatic.
c. On the Log On tab, select This account and enter the Content Engine service user’s name and password.
7. On each Object Store server, update the password of the Windows Service Logon account used in the Global Configuration Data (GCD):
a. Run the GCD Wizard.
• Navigate to the <Content_Engine_Installation> folder, and double-click on ConfigGCD.exe. b. When the GCD Wizard comes up, choose Join an existing domain if it is not already chosen, and
enter the machine name of the Object Store server you are on.
c. When informed that no domain configuration can be found, click No to manually enter the domain's SYSINIT path. Enter the following:
i. SYSINIT Path: \\<machinename>\FNCE_<machinename>$\sysinit.dat ii. P8 Domain Service Group: P8 domain service group
iii. If you are logged on as a user who is a domain administrator, check Use Default accounts. Otherwise, do the following:
• Uncheck Use Default accounts. • Click List Members.
• Select the Content Engine service user.
iv. Enter the password for the Content Engine service user. This is the password you entered in Step 6 above.
v. Click Finish.
8. If Apache is installed, change the logon information and startup type: a. Open the Windows Services console.
b. Double-click the Apache2 service. c. Set the Startup type to Automatic.
d. On the Log On tab, select This account and enter the desired username and password. e. Click OK.
9. If you have any WEBDAV network folders, you must delete and re-create the share in order to use them. See FileNet P8 Documentation > FileNet WebDAV Clients for further information.
10. To verify that you have successfully migrated the directory service, start the Enterprise Manager. Log on as Administrator in the destination Active Directory.
11. FileNet recommends that you run the consistency checker after logging in. a. Expand the Object Store folder.
b. Select each file store, and right-click.
c. From the context menu, select All Tasks, then Run Content Consistency Checker. d. Select the file store from the File Stores list.
Appendix A – Directory Services Migration API
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():
• 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 =
• 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
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.
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 .
