FileNet P8 Platform Directory Service Migration Guide

Transcription

1 FileNet P8 Platform Directory Service Migration Guide Release 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 capabilities are subject to change without notice. Copyright 2001, 2005 FileNet Corporation. All rights reserved. FileNet Corporation 3565 Harbor Boulevard Costa Mesa, California FILENET ( ) Outside the U.S., call:

2 Notices For notices regarding this documentation, refer to Help directory > Notices in the FileNet P8 online documentation.

3 Table of Contents 3 Introduction Requirements General Content Engine Limitations General Process Engine Content Engine Assumptions General Process Engine Content Engine Process Engine Migration Overview Procedure Errors and recovery System failure during migration Duplicated users Already initiated workflows Launching new workflows Content Engine Migration Overview Procedure Active Directory to Active Directory with no trust relationship Appendix A Directory Services Migration API Summary Guide Reference Functions Enumerations Appendix B Content Engine XML File Formats Directory Service Users and Groups XML File Format Checked-Out Documents XML File Format Directory Service Mapping XML Map File Format Migration XML Output File Format Appendix C Content Engine Debugging Tools Content Engine trace functionality FNSysInfo Appendix D FileNet P8 Platform and Directory Service Integration Vendor-specific unique IDs Short Name Process Engine Content Engine Application Engine

4 Table of Contents 4 Web Content Manager Records Manager eforms Team Collaboration Manager (TCM)

5 Introduction 5 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 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.)

6 Introduction 6 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.

7 Process Engine Migration 7 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 Engine. Leave the Process Service on the Process Engine running.

8 Process Engine Migration 8 2. Create and populate the Directory Migration Information table. 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 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: Verbose? Initialize Directory Migration Information table? n y 3. Delete the current directory service configuration, and configure the Process Engine to use the destination directory service. 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. a. Enter the following at the ldapmigrate prompt: PE LDAP Configuration? d

9 Process Engine Migration 9 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 Process Task Manager > Process Engine > Process Service > Configure the Process 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. 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. a. On the primary Process Engine, start vwtool again. b. Enter ldapmigrate at the vwtool command prompt. Answer the prompts as follows: Verbose? Initialize Directory Migration Information table? PE LDAP Configuration? 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. n n n y

10 Process Engine Migration Migrate the Process Engine environment records. 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. 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: Verbose? Initialize Directory Migration Information table? PE LDAP Configuration? Acquire new GUID values for the Directory Migration Information table? 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. n n n n y b. Restart Process Services on the Process Engine. 7. Process Engine migration is complete.

11 Process Engine Migration 11 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.

12 Content Engine Migration 12 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 or in \\englib\working\trees\klxxx.xxx\dev03\bin\release\testtools, where xxx is the number of the latest build.

13 Content Engine Migration 13 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. This step calls the GetDirectoryUsersForCurrentProvider() API using the current Content Engine Authentication Provider information. a. In the From Users tab, enter the following: Users File UserID Password Include Display Name Include Principal Name Include Distinguished Name The name of the output XML file that will contain the list of users in the current directory service. 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. 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. 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.

14 Content Engine Migration 14 b. Install FileNet P8 Client Connectivity. i. Run the Content Engine installer. This can be found in P8CE or in \\englib\working\disks\perxxx.xxx\contentengine\contentengine, where xxx is the number of the latest build. ii. iii. iv. Choose Custom install. Deselect all packages except for FileNet P8 Client Connectivity. 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. This step calls the GetDirectoryUsersForNewProvider() API using the destination directory provider information. a. In the To Users tab, enter the following: Users File Type Host Name UserID Password Port Include Display Name Include Principal Name Include Distinguished Name The name of the output XML file that will contain the list of users for the destination directory service. The type of the destination directory service. The name of the machine containing the destination directory service. (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. (Sun Java System Directory Server and Novell edirectory only) The port used by the directory service. 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. 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.

15 Content Engine Migration 15 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 original Content Engine. 5. Create the map file. This process uses the short name to search for matches in the current and destination XML files. This step calls the CreateDirectoryMigrationMapFile() API to generate an XML map file. a. In the Map Users tab, enter the following: From Users To Users File Map File Include Display Name Include Principal Name Include Distinguished Name 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. 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. The name of the output XML file that will contain the mapping between the current directory service and the destination directory service. 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. 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 destination directory service. If it is missing, add the user or group to the destination 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.

16 Content Engine Migration 16 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 > Enterprisewide Administration > Security > Users and groups for a complete list of required users. In particular, be sure to map the users and groups referenced in Table 1, Roles referenced in Active Directory migration steps, on page 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.) This step calls the GetCheckedOutDocuments() API to generate a list of checked-out files. a. In the Checked-Out tab, enter the following: Docs File UserID Password The name of the output XML file that will contain the list of checked-out documents. 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. 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.

17 Content Engine Migration Migrate the users. 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. a. In the Migration tab, enter the following: Map File Output File Log Success 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. The name of the output XML file that will contain the list of security principals that were modified. 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.

18 Content Engine Migration 18 Update Test before migrating Continue Current Content Engine UserID Password To Directory Service UserID Password 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. Check this box to perform a trial run, then automatically perform the actual migration if no errors were encountered during the trial run. Indicates that the migration is to continue through both phases even if errors are encountered. 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. 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. 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).

19 Content Engine Migration 19 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. iii. iv. Go to Workflow Properties/Workflow Groups. Select each workflow group. An error message displays when the workflow group is opened for editing: VWServer Exception: [Err=d ] Domain mismatch. Click OK. Delete each participant from the current directory service, then add the equivalent participant from the destination directory service.

20 Content Engine Migration 20 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. Name Description Default User or Group Name Administrators A group with administrative Administrators privileges. Administrator P8 domain service group Content Engine service user Can refer to the current or destination Active Directory, or the local machine account. A user who is a member of the Administrators group. Can refer to the current or destination Active Directory, or the local machine account. 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. 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. Administrator Table 1: Roles referenced in Active Directory migration steps Content Engine Servers FNCE_<servername> 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

21 Content Engine Migration 21 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. iii. iv. On the Security tab, click Advanced. Select the P8 domain service group in the Permission entries. 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. iii. iv. On the Security tab, click Advanced. Select the P8 domain service group and the current Active Directory Administrator in the Permission entries. 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.

22 Content Engine Migration 22 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. iii. iv. Select the Security Tab. Click Advanced, then select the Owner tab. 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. iii. iv. Select the Security tab. Click Advanced, then select the Owner tab. 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. iii. Select the Security tab, and click Advanced. 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. Click OK.

23 Content Engine Migration 23 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. iii. iv. Select the Internet Protocol (TCP/IP) entry, then click Properties. Change the Preferred DNS server to the IP address of the destination Active Directory server. Click OK twice. b. Join the destination Active Directory domain: i. Right-click on My Computer, and select Properties. ii. iii. iv. On the Computer Name tab, click Change. Enter the destination Domain. 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.

24 Content Engine Migration 24 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. iii. 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. Double-click the Administrators group. 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.

25 Content Engine Migration 25 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. iii. iv. On the Security tab, click Advanced. Click Add. 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. iii. iv. On the Security tab, click Advanced. Click Add. 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. Click Add.

26 Content Engine Migration 26 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. iii. iv. Right-click on file store folder, and select Properties. Select the Security tab, and click Advanced. 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. xv. Click OK.

27 Content Engine Migration 27 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. iii. iv. Select the Security tab. Click Advanced, then select the Owner tab. 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. d. Click OK.