IBM FileNet P8, Version 5.2.1

Extracting a security principal half map

When a source or a destination environment is defined, or after a deployment data set is created, you can extract its user and group (security principal) data to create a security principal half map.

To extract user and group data:

In the FileNet® Deployment Manager Tree View pane, expand the Environments node and double-click an environment.
On the Overview tab, click Retrieve Data button for Security Principal Data.

From the Update Principal Half Map dialog box, select the security principal data source:

Option Description

Option	Description
Deploy Dataset	For a source half map, it is best to retrieve principal data from a FileNet P8 deployment data set because these sources contain only the principals that must be converted for the destination environment. Retrieving from these sources takes much less time than retrieving all the principals from a large LDAP directory. Tip: If you merge principals that are retrieved from a deployment data set that contains both object store and workflow system assets, the half map might contain duplicate or incomplete entries. To eliminate duplicate entries, perform a retrieval from the LDAP directory that is filtered on the half map of the environment. This action fully resolves the principals and eliminates the duplicate entries. See also Important Considerations. Click Next. In the Select Deploy Dataset field, enter the fully qualified name of the deployment data set from which the security principal data is to be retrieved.
Content Platform Engine LDAP Provider	For a destination half map, use the LDAP directory for the destination environment, with a filter applied if the LDAP directory is large. See also Important Considerations. Click Next. Click Retrieve Realms. The accessible LDAP realms are displayed. Select the LDAP realm to use. Select the filter to be applied in retrieving the users and groups: None Retrieve data for all users and groups in the selected realm from the LDAP provider. Retrieving all of these principal data can require some time, depending on the size of the LDAP directory. You might use this option if you expect that the objects you are exporting require most of the principals in the LDAP realm. Use the Environment Principal Half Map Retrieve data only for those users and groups that are identified in the security principal half map for a specified environment. If you select this filter, select the environment to use for the security principal half map from a list of currently defined environments. Use a Label File Retrieve data only for those users and groups that are identified in a specified file. If you select this filter, select a file to use. This file must be a text file that contains the short name and can include a label for each user or group to retrieve. Enter the values (short names first) for each user and group on a separate line and use a comma to separate the short name and label. For example: `suser, systemuser CEAdmin, administrator` Alternatively, you can include only the short name values of each user and group, which causes FileNet Deployment Manager to base its query on the short names only. For example: `suser CEAdmin` Refer to the sample label file generated in the Samples directory. For more information, see Create sample files.

Deploy Dataset

For a source half map, it is best to retrieve principal data from a FileNet P8 deployment data set because these sources contain only the principals that must be converted for the destination environment. Retrieving from these sources takes much less time than retrieving all the principals from a large LDAP directory.

Tip: If you merge principals that are retrieved from a deployment data set that contains both object store and workflow system assets, the half map might contain duplicate or incomplete entries. To eliminate duplicate entries, perform a retrieval from the LDAP directory that is filtered on the half map of the environment. This action fully resolves the principals and eliminates the duplicate entries.

See also Important Considerations.

Click Next.
Click Retrieve Realms. The accessible LDAP realms are displayed.
Select the LDAP realm to use.
Select the filter to be applied in retrieving the users and groups:
None

Retrieve data for all users and groups in the selected realm from the LDAP provider. Retrieving all of these principal data can require some time, depending on the size of the LDAP directory.
You might use this option if you expect that the objects you are exporting require most of the principals in the LDAP realm.

Use the Environment Principal Half Map

Retrieve data only for those users and groups that are identified in the security principal half map for a specified environment. If you select this filter, select the environment to use for the security principal half map from a list of currently defined environments.

Use a Label File
Retrieve data only for those users and groups that are identified in a specified file. If you select this filter, select a file to use. This file must be a text file that contains the short name and can include a label for each user or group to retrieve. Enter the values (short names first) for each user and group on a separate line and use a comma to separate the short name and label. For example:
```
    suser, systemuser
    CEAdmin, administrator
```
Alternatively, you can include only the short name values of each user and group, which causes FileNet Deployment Manager to base its query on the short names only. For example:
```
    suser
    CEAdmin      
```
Refer to the sample label file generated in the Samples directory. For more information, see Create sample files.

For the chosen security principal data source, if you are updating an existing security principal half map, select one of the following options:
- Merge: Adds any new security principal data to the security principal half map. If an item with the same ID is retrieved from the environment, existing data is updated with any changes. This option does not delete any data from the security principal half map.
- Overwrite Replaces the contents of the security principal half map with the new data. Overwrite begins with an empty half map. If the half map used as the filter is also the half map that you are building, any entries that are not found in the LDAP are removed from the half map. In this scenario, it is best to use the Merge option.
Click Finish.
FileNet Deployment Manager processes the specified file, retrieves the security principal data, and creates a half map that contains this data (HalfMap_Principal.xml) in the DeploymentTreeRootFolder\Environments subfolder for the specified environment.

If principal data is retrieved from a Content Platform Engine deployment data set, not all of the fields in the resulting security principal half map contain values. The exported objects can contain only the SID, or the short name. If the resulting security principal data map is only used on the Content Platform Engine deployment data set, no inconsistencies occur.

However, if the resulting security principal data map is also used for subsequent data sets, those later data sets might include other types of objects that require the additional, missing field values. Before you use the data map on subsequent data sets, update all the fields in an existing security principal half map by electing to retrieve the security principal from the Content Platform Engine LDAP Provider. Select the Use Environment's Principal Half Map option to retrieve the security principal half map. When you use this filter option, FileNet Deployment Manager retrieves data only for the existing principals in the security principal half map, rather than iterating over the potentially much larger set of principals in the Content Platform Engine LDAP repository.