37 Migrating Configurations and Customizations

The Deployment Manager is a tool for exporting and importing Oracle Identity Manager configurations and customizations. The Deployment Manager lets you export the objects that constitute the Oracle Identity Manager configuration. Usually, you use the Deployment Manager to migrate a configuration from one deployment to another, for example, from a test to a production deployment, or to create a backup of your system.

Important:

To use Deployment Manager, JRE 1.4.2 or a higher version must be installed on any computer that is running the Oracle Identity System Administration.

You can save some or all of the objects in your configuration. This lets you develop and test your configurations in a test environment, and then import the tested objects into your production environment. You can export and import an object and all of its dependent and related objects at the same time. Alternatively, you can export and import each object individually.

The Deployment Manager allows you to retrieve configuration information and binary data from the source system, store the information in an XML file, and then import the information from the XML file to the target system. The binary data includes plug-ins, JARs, and custom resource bundles. The Deployment Manager allows you to import data from the Oracle Identity Manager database, Meta Data Store (MDS) repository, or API repository. As a result, you can import all types of objects from these repositories, such as system properties, jobs, and scheduled tasks, which are not in the same repository. For example, you can import the scheduled tasks that are in the MDS repository instead of the database.

An object exported from one type of repository is imported to the same type of repository. For example, if a scheduled task is exported from the MDS repository, then the scheduled task is imported to the same repository, which is MDS, in the target system.

Note:

In addition to the Deployment Manager, you can use the sandbox feature to migrate configurations and customizations from one deployment to another. See "Managing Sandboxes" for information about working with sandbox.

This chapter includes the following topics:

37.1 Features of the Deployment Manager

The Deployment Manager helps you to migrate Oracle Identity Manager deployments from one server environment to another, such as from a testing environment to a staging environment, or from a staging environment to a production environment.

The Deployment Manager enables you to:

  • Update individual components of a deployment in different test environments

  • Identify objects associated with components to be exported, so that those resources can be included

  • Provide information about exported files

  • Add comments

The Deployment Manager handles the following types of information:

  • Application instances

  • Catalog definitions

  • Plug-ins

  • JAR files

  • Custom resource bundles

  • Roles

  • Organizations

  • Access policies

  • Attestation processes

  • User metadata

  • Role metadata

  • Organization metadata

  • Scheduled tasks

  • Scheduled jobs

  • IT resources

  • Resource objects

  • Lookup definitions

  • Process forms

  • Provisioning workflows and process task adapters

  • Data object definitions

  • Rules

  • Notification templates

  • Generic Technology Connectors (GTC)

  • GTC providers

  • Error codes

  • System properties

  • E-mail definitions

  • Password policies

  • IT resource definition

  • Request datasets

  • Approval policies

  • Event handlers

  • Prepopulation adapters

  • Process definitions

The following are limitations of the Deployment Manager:

  • Merge Utility: The Deployment Manager is not a merge utility.

    It cannot handle modifications done in both production and test environments. It replaces the object in the target system with that in the XML file.

  • Version Control Utility: The Deployment Manager does not track versions of imported files, and does not provide rollback functionality.

    You can only use it as a means to move data between environments.

37.2 Exporting Deployments

You can export objects from your Oracle Identity Manager system and save them in an XML file. The Deployment Manager has an Export Wizard that lets you create your export file. Add objects by type, one type at a time, for example, roles, then forms, then processes, and so on.

Note:

  • Application instances are exported and imported without the datasets. Datasets are migrated as a part of UI customization.

  • Deployment Manager must not be used for exporting large JAR files between environments. Use the Upload/Download JARs utilities to migrate large files between environments.

If you select an object that has child objects or dependencies, you have the option to add them or not. After adding objects of one type, you can go back and add other objects to your XML files. When you have all the objects you want, the Deployment Manager saves them all at once in a single XML file.

Note:

When user-defined fields are associated with a specific resource object, during the export process one of the following events can occur:
  • If the user-defined fields contain values (entered information), then the Deployment Manager will consider them to be dependencies.

  • If the user-defined fields contain no values (the fields are blank), then the Deployment Manager will not consider them to be dependencies.

To export a deployment:

  1. Login to Oracle Identity System Administration.

  2. In the left pane, under System Management, click Export. The Deployment Manager opens and the Search Objects page of the Export Wizard is displayed.

    Note:

    To open the Deployment Manager by using Mozilla Firefox Web browser, an additional authentication dialog box might be displayed. Providing authentication in this dialog box allows access to the Deployment Manager. To avoid this additional authentication:
    1. In Mozilla Firefox Web browser, from the Tools menu, select Options. The Options dialog box is displayed.

    2. Click Privacy.

    3. Select the Accept third-party cookies option.

    4. Click OK.

    The additional authentication is not required when the Deployment Manager is opened by using Microsoft Internet Explorer, Google Chrome, and Apple Safari Web browsers.

  3. On the Search Objects page, select an object type from the menu, and enter search criteria. If you leave the criteria field blank, an asterisk (*) is displayed automatically to find all the objects of the selected type.

    All the objects supported by Deployment Manager for migration are available for exporting. See "Features of the Deployment Manager" for the list of objects supported by Deployment Manager for migration.

  4. Click Search to find objects of the selected type.

    To select an object, select the option of the object.

  5. Click Select Children.

    The Select Children page is displayed with the selected objects and all of their child objects.

  6. Select the child objects that you want to export.

    To select or remove an item, select the appropriate option.

    Click Back to go to the Search Objects page.

  7. Click Select Dependencies.

    The Select Dependencies page is displayed with any objects required by the selected objects.

  8. Select the dependent objects that you want to export.

    To select or remove an item, select the option of the item.

    Click Back to go to the Select Children page.

  9. Click Confirmation.

    The Confirmation page is displayed.

  10. Ensure that all the required items are selected, then click Add for Export.

    After you click Add for Export, you can still add more items to this export file.

    Select Add More and click OK to go to Search Objects Page to add more objects for export.

  11. Use the wizard to add more items, or finish and exit the wizard. Select the appropriate option and click OK.

    If you select Add more, repeat Steps 2 through 7. Otherwise, the Export page is displayed.

    The Export page displays your current selections for export. Your selections have icons next to them that indicate what types of objects are selected. The Summary information pane shows the objects you are exporting. The Unselected Dependencies pane displays the list of dependent or child objects that you did not select for export.

  12. Make any adjustments to your export file as follows:

    • Click Reset to clear the form.

    • Click Legend to see icon definitions.

    • Click Add Objects to restart the wizard and add more items to your export file.

    To remove an object from the Current Selections list:

    • Right-click the object to remove and select Remove from the shortcut menu. If the object has child objects, then select Remove including children from the shortcut menu to remove the child objects all at the same time.

    • Click Remove to confirm. If the object is a child or dependency of a selected item, then it is added to the Unselected Children or Unselected Dependencies list.

    To add an object back to the Current Selections list from the Unselected Children or Unselected Dependencies list,

    1. Right-click the object, and select Add.

    2. Click Confirmation.

      The Confirmation page is displayed.

    3. Click Add for Export.

  13. Click Export.

    The Add Description dialog box is displayed.

  14. Enter a description for the file.

    This description is displayed when the file is imported.

  15. Click Export.

    The Save As dialog box is displayed.

  16. Enter a file name.

    You can browse to find a location.

  17. Click Save.

    The Export Success dialog box is displayed.

  18. Click Close.

37.3 Importing Deployments

Objects that were exported into an XML file by using the Deployment Manager can be imported into Oracle Identity Manager by using the Deployment Manager. You can import all or part of the XML file, and you can import multiple XML files at once. The Deployment Manager ensures that the dependencies for any objects you are importing are available, either in the import or in your system. During an import, you can substitute an object you are importing for one in your system. For example, you can substitute a group specified in the XML file for a group in your system.

Note:

  • If a user belongs to a group to which the Import menu item has been assigned, then that user must also have the necessary permissions for the objects that the user wants to import. Without these object-specific permissions, the Import operation fails. The user must be a Deployment Manager Administrator to be able to see Deployment Manager menu items on the UI based on menu permissioning model.

  • When more than 1000 resources, process definitions, parent forms, child forms, access policies, roles, and rules are imported by using the Deployment Manager, the size of the EIF table increases. The data can be truncated from this table by running a simple SQL query such as Delete from EIF.

To import an XML file:

Note:

Before importing data that contains references to menu items, you must first create the menu items in the target system.
  1. Login to Oracle Identity System Administration.

  2. In the left pane, under System Management, click Import. The Deployment Manager opens and the Search Objects page of the Export Wizard is displayed.

    Note:

    To open the Deployment Manager by using Mozilla Firefox Web browser, an additional authentication dialog box might be displayed. Providing authentication in this dialog box allows access to the Deployment Manager. To avoid this additional authentication:
    1. In Mozilla Firefox, from the Tools menu, select Options. The Options dialog box is displayed.

    2. Click Privacy.

    3. Select the Accept third-party cookies option.

    4. Click OK.

    The additional authentication is not required when the Deployment Manager is opened by using Microsoft Internet Explorer, Google Chrome, and Apple Safari Web browsers.

  3. Select a file.

    The Import dialog box is displayed.

  4. Click Open.

    The File Preview page is displayed.

  5. Click Add File.

    The Substitutions page is displayed

  6. To substitute a name, click the New Name field adjacent to the item you want to replace, and enter the name.

    You can substitute only items that exist in the target system.

  7. Click Next. If you are exporting an IT resource instance, then the Provide IT Resource Instance Data page is displayed. Otherwise, you are redirected to the Confirmation page.

  8. Modify the values in the current resource instance and click Next, or click Skip to skip the current resource instance, or click New Instance to create a new resource instance.

    The Confirmation page is displayed.

  9. Confirm that the information displayed on the Confirmation page is correct.

    To go back and make changes, click Back, or click View Selections.

    The Deployment Manager Import page displays your current selections.

    The Import page also displays icons next to your current selections. The icons indicate what types of objects are selected. The icons on the right indicate the status of your selections. The file names of any selected files, summary information about the objects you are importing, and substitution information are displayed on the left side of the page. On the right, the Objects Removed from Import list displays any objects in the XML file that will not be imported.

  10. Make any of the following adjustments:

    • Click Reset to clear the form.

    • Click Legend to see icon definitions.

    • To remove an object from the Current Selections list, right-click the object, select Remove from the shortcut menu, and then click Remove to confirm that you want to remove the object.

      If the object has child objects, then select Remove including children from the shortcut menu to remove all the child objects at the same time. The item is added to the Objects Removed From Import list.

    • To add an item back to the Current Selections list, right-click the list, and click Add.

      If the object has child objects, then select Add including children from the shortcut menu to add all the child objects at the same time.

    • To make substitutions, click Add Substitutions.

    • To add objects from another XML file, click Add File and repeat Steps 2 through 7.

    • Click Show Information to see information about your imported information.

      The Information page is displayed.

      To see more information, select the Show Info Level Messages option, and then click Show Messages. Click Close to close the Information page.

  11. To import the current selections, click Import.

    A confirmation dialog box is displayed.

  12. Click Import.

    The Import Success dialog box is displayed.

  13. Click OK.

    The objects are imported into Oracle Identity Manager.

37.4 Horizontal Migration of Entities (Deprecated)

Note:

In Oracle Identity Manager 11g Release 2 (11.1.2), the Deployment Manager supports migration of all artifacts that are migrated by using the horizontal migration utility in earlier releases of Oracle Identity Manager. Therefore, Oracle recommends using the Deployment Manager for migrating all such artifacts, for example, custom resource bundle and plug-ins.

The Deployment Manager is used for performing migration of metadata entities from an Oracle Identity Manager deployment to another. However, for Oracle Identity Manager 11g Release 2 (11.1.2), there are other non-metadata entities that are not supported by the Deployment Manager. These entities include custom resource bundles and plug-ins. Therefore, a complete migration of entities is performed by using a command-line utility, which is the horizontal migration utility, along with the Deployment Manager.

The horizontal migration command-line utility supports the migration of the following metadata entities that are not supported by the Deployment Manager:

  • Custom resource bundle

  • Plug-ins

The migration of metadata entities take place in the following steps:

  1. Export data: When data from an Oracle Identity Manager deployment is exported by running the Deployment Manager and the horizontal migration command-line utility, a set of artifacts are generated. The Deployment Manager generates XML files, and the horizontal migration utility generates binaries and XML files.

    Note:

    Deployment Manager supports the migration of all the entities in the form of XML. The command-line utility supports the migration of binaries, which are entities that are not exportable and importable in the form of XML.

    Figure 37-1 shows the exporting of data:

    Figure 37-1 Exporting Migration Data

    Description of Figure 37-1 follows
    Description of "Figure 37-1 Exporting Migration Data"

  2. Import data: The Deployment Manager and the horizontal migration utility are run to import the metadata on the second Oracle Identity Manager deployment, as shown in Figure 37-2:

    Figure 37-2 Importing Migration Data

    Description of Figure 37-2 follows
    Description of "Figure 37-2 Importing Migration Data"

The horizontal migration utility is used to migrate the entities that are not supported by the Deployment Manager. This section describes the export and import of entities by using the horizontal migration utility in the following sections:

37.4.1 Creating a Backup of the Existing Entities

Before performing the migration, create a backup of the existing entities in the Oracle Identity Manager deployment. If you are importing any entity, then create a backup of the existing ones so that you can roll back if required.

To create the backup, use the horizontal migration utility in the export mode to extract the existing entities. See "Running the Horizontal Migration Utility" for information about running the utility in export mode.

37.4.2 Running the Horizontal Migration Utility

When you run the horizontal migration utility in EXPORT mode, a ZIP file is created that contains all the artifacts of the entities to be migrated. You must migrate the ZIP file into the second deployment where the data is to be imported back. When you run the utility in IMPORT mode, the contents of the ZIP file is extracted in a temporary location and all the artifacts are imported in the Oracle Identity Manager deployment. The configuration in the properties file controls the export and import. All the configurations in the file are defined at runtime.

Note:

Before running this utility, set APP_SERVER, OIM_ORACLE_HOME, JAVA_HOME, MW_HOME, WL_HOME, and DOMAIN_HOME.

In the EXPORT mode, you run the exportMetaData.sh or exportMetaData.bat script, which is in the OIM_HOME/bin directory.

To run the horizontal migration utility in EXPORT mode:

  1. Check the location of the Config.xml file. The Config.xml file contains the filter criterion for filtering the entities for export. You can modify this file to provide custom filters.

    Save the Config.xml file before running the utility.

  2. In a text editor, edit the exportMetaData.sh or exportMetaData.bat script to specify the following parameters:

    • CONTEXT_FACTORY: Context to connect to Oracle Identity Manager

    • PACKAGE_LOCATION: Destination path for the package to be exported

    • CONFIGURATION_FILE: Configuration file that you must create with the definition of the parameters and filtering criteria for the Export of the metadata

      The following is a sample configuration XML file:

      <?xml version="1.0" encoding="UTF-8"?>
      <MigrationDetails operation ="Export">
              <entityDetails>
                    <EntityType>Jars</EntityType>
                    <FilteringCriteria>
                           <Attribute>
                                <Name>OJ_NAME</Name>
                                <Filter>*</Filter>
                           </Attribute>
                    </FilteringCriteria>
              </entityDetails>
              
              <entityDetails>
                    <EntityType>Plugins</EntityType>
                    <FilteringCriteria>
                           <Attribute>
                                <Name>PLUGIN_NAME</Name>
                                <Filter>*</Filter>
                           </Attribute>
                    </FilteringCriteria>
              </entityDetails>
              
              <entityDetails>
                    <EntityType>CustomResourceBundles</EntityType>
                    <FilteringCriteria>
                           <Attribute>
                                <Name>RES_NAME</Name>
                                <Filter>*</Filter>
                           </Attribute>
                    </FilteringCriteria>
              </entityDetails>
      </MigrationDetails>
      

      The configuration file supports three entity types: Jars, Plug-ins, and CustomResourceBundles. For each entity type, the following filters are supported:

      • Jars: Jar_Type or OJ_TYPE, Jar_Name or OJ_NAME

      • Plugins: PLUGIN_NAME or plugins.ID

      • CustomResourceBundles: Resource_Type or RES_TYPE, Resource_Name or RES_NAME

    • TEMP_LOCATION_TO_EXTRACT: Temporary location to keep the files temporarily before packaging for export

  3. Run the exportMetaData.sh or exportMetaData.bat script.

  4. Specify the following when prompted:

    • Oracle Identity Manager administrator user name to connect to Oracle Identity Manager

    • Oracle Identity Manager administrator password to connect to Oracle Identity Manager

    • JNDI URL to connect to Oracle Identity Manager: t3://localhost:PORT_NUMBER

    • LogFileLocation path where log file is to be generated

  5. Verify the export list that is displayed.

  6. When prompted for confirmation, enter YES.

  7. Verify the export. All the listed items are exported to the destination provided as input. Check the contents of the ZIP package that is created at the destination.

In the IMPORT mode, you run the importMetaData.sh or importMetaData.bat script, which is in the OIM_HOME/bin directory.

To run the horizontal migration utility in IMPORT mode:

  1. Before running the utility, run the client targets by using the following commands:

    ant fullbuild XellerateClient.view-install
    ant assemble-ear client-archive
    
  2. Run the importMetaData.sh or importMetaData.bat script after specifying the following input parameters in the utility script:

    • Username to connect to Oracle Identity Manager.

    • Password to connect to Oracle Identity Manager.

    • JNDI URL to connect to Oracle Identity Manager.

    • Context to connect to Oracle Identity Manager.

    • Path of the package to be imported.

    • Configuration file updated with the information about items to be imported. If this configuration is not used in import, then the entire content of the package is imported.

    • Temporary location where the package is to be extracted before importing.

  3. Specify the following when prompted:

    • Oracle Identity Manager administrator username

    • Oracle Identity Manager administrator password

    • Server URL: t3://localhost:PORT_NUMBER

  4. Verify the import list that is displayed.

  5. When prompted for confirmation, enter YES.

  6. Verify the import. All the items in the package are imported to the application. Check if the import utility creates the entries corresponding to all the package contents in the database tables if you have access to the schema. Otherwise, check the utility output log in the application to verify if all contents have been successfully imported.

37.4.3 Data Migration for Supported Entities

This section describes the migration of the following entities:

37.4.3.1 Custom Resource Bundle

Oracle Identity Manager stores localized versions of text strings that appear in the user interface in resource bundles. In addition to the default resource bundles, the custom resource bundles, which are stored in Oracle Identity Manager database, can be imported and exported by using the horizontal migration utility.

The default packaged resource bundles are available in the following property files:

  • oim.ear/xlWebApp.war/WEB-INF/classes/xlRichClient_*.properties

  • Agent_*.properties for each feature in the deployment

You can customize the default packaged resource bundles to create custom resource bundles.

37.4.3.2 Plug-ins

Plug-ins are stored in Oracle Identity Manager database. The horizontal migration utility migrates the binaries from plug-in database store of one deployment to another.

See Also:

"Developing Plug-ins" for information about defining and using plug-ins

37.4.4 Horizontal Migration Report

After the horizontal migration utility is run, a report is generated that contains the following information:

  • All the entities migrated by using this utility

  • Status of overall export and import of metadata

  • Errors that occurred during the import of metadata

The following is a sample report:

Plugins :
Failed to process element Plugin1".
Exception details are java.io.FileNotFoundException: C:\Plugin1.zip (The system cannot find the path specified) at java.io.FileInputStream.open(Native Method)at java.io.FileInputStream.<init>(Unknown Source)at java.io.FileReader.<init>(Unknown Source)at file.main(file.java:13)

37.5 Best Practices Related to Using the Deployment Manager

The following are some of the suggested practices and pitfalls to avoid while by using Deployment Manager:

37.5.1 Export System Objects Only When Necessary

You should export or import system objects, for example, Request, Xellerate User, and System Administrator, only when it is absolutely necessary. Exporting system objects from the testing and staging environments into production can cause problems. If possible, exclude system objects when exporting or importing data.

You may want to export or import system objects when, for example, you define trusted source reconciliation on Xellerate User resource objects.

Caution:

The Deployment Manager keeps track of imported components and structures, but not of completed imports. After an import is completed, you cannot roll it back to a previous version. A new import is required.

37.5.2 Export Related Groups of Objects

Oracle recommends that you use the Deployment Manager to export sets of related objects. A unit of export should be a collection of logical items that you want to group together.

Avoid exporting everything in the database in one operation, or exporting items one at a time. For example, suppose that you manage an integration between Oracle Identity Manager and a target system that includes processes, resource objects, adapters, IT resource type definitions, IT resource definitions, scheduled tasks, and so on. For this environment, you should create groups of related objects before exporting.

For example, if you use the same e-mail definitions in multiple integrations, you should export the e-mail definitions as one unit, and the integrations as a different unit. This enables you to import changes to e-mail definitions independently of target system integration changes. Or, if multiple resources use the same IT resource type definition, you can export and import the type definition separately from other data.

You can import one or more sets of exported data at a time. For example, you can import a resource object definition, an e-mail definition, and an IT resource type definition in a single operation.

37.5.3 Group Definition Data and Operational Data Separately

You must group and export definition data and operational data separately.

You configure definition data in the testing and staging environment. Definition data includes resource objects, processes, and rules.

You typically configure operational data in the production environment. Operational data includes groups and group permissions. The testing and staging servers usually do not include this data.

By grouping data according to where it is changed, you know what data goes to testing and staging, and what goes to production. For example, if approval processes are changed in production, you should group approval processes and export them with other operational data.

37.5.4 Use Logical Naming Conventions for Versions of a Form

You often revise forms multiple times before exporting them. Avoid generic names, for example, "v23," to differentiate among versions of a form. Create meaningful names, for example, "Before Production" or "After Production Verification." Do not use special characters, including double quotation marks, in version names.

37.5.5 Export Root to Preserve a Complete Organizational Hierarchy

When you export a leaf or an organization in an organizational hierarchy, only one dependency level is exported. To export a complete organizational hierarchy, you must export the root of the hierarchy.

37.5.6 Provide Clear Export Descriptions

The Deployment Manager records some information automatically, for example, the date of the export, who performed the export, and the source database. You must also provide a meaningful description of the content of the export, for example, "resource definition after xxx attributes added in reconciliation." This informs the importer of the file of the contents of the data being imported.

37.5.7 Check All Warnings Before Importing

When importing information to the production environment, check all the warnings before completing the import operation. Treat each warning seriously.

37.5.8 Check Dependencies Before Exporting Data

The wizard in the top right pane shows resources that must be available in the target system.

Consider the following types of dependencies:

  • If the resources are already available in the target system, they do not need to be exported.

  • If the resources are new (not in the target system), they must be exported.

  • If the target system does not include the resources, such as lookups, IT resource definitions, or others that are reused, then record the data and export it in a separate file so it can be imported if necessary.

Note:

When you export a resource, groups with Data Object permissions on that form are not exported with the resource.

37.5.9 Match Scheduled Task Parameters

Scheduled tasks depend on certain parameters to run properly. You can import scheduled task parameters to the production server. Table 37-1 shows the rules for determining how to import scheduled tasks. Note that parameters may be available for tasks that no longer reside on the target system.

Table 37-1 Parameter Import Rules

Parameter Exists in Target System Parameter Exists in the XML File Action Taken

Yes

No

Remove the parameter from the target system.

No

Yes

Add the parameter and current value from the XML file.

Yes

Yes

Use the more recent value of the parameter.


37.5.10 Deployment Manager Actions on Reimported Scheduled Tasks

A scheduled task is one of the objects that you can import by using the Deployment Manager. Typically, you import a scheduled task into your Oracle Identity Manager environment and later change the values of the scheduled attributes to meet your production requirements. However, if you import the same scheduled task a second time into the same Oracle Identity Manager server, the Deployment Manager does not overwrite the attribute values in the database. Instead, the Deployment Manager compares the attribute value of the reimported XML file to any corresponding attribute values in the database.

The following table summarizes the actions performed by the Deployment Manager during a scheduled task reimport:

Does the Scheduled Task have attribute values in the XML file being imported? Are there any corresponding attribute values in the database? Deployment Manager Action
Yes No Store attribute values in the database
No Yes Delete existing attribute values in the database
Yes Yes (Newer attribute values indicated by time stamp) No change in the database
Yes (New attribute values indicated by time stamp) Yes Update the database with the new attribute values

37.5.11 Compile Adapters and Enable Scheduled Tasks

After an import operation, the adapters are set to recompile and the scheduled tasks are disabled. After importing the classes and adjusting the task attributes, manually recompile the adapters and enable the scheduled tasks.

37.5.12 Export Entity Adapters Separately

Entity adapters are modified to bring just the entity adapter, not its usage. If you want to export the usage of an entity adapter, you must separately export each use with a data object by exporting the data object. If you export a data object, all the adapters and event handlers attached to the object along with the permissions on the object are exported. You must pay special attention when exporting data objects. For example, to export a form, you should also add the data object corresponding to the form. This ensures that the associated entity adapters can use the form.

37.5.13 Check Permissions for Roles

When you export roles, the role permissions on different data objects are also exported. However, when you import data, any permissions for missing data objects are ignored. If the role is exported as a way of exporting role permission setup, then check the warnings carefully to ensure that permission requirements are met. For example, if a role has permissions for objects A, B, and C, but the target system only has objects A and B, the permissions for object C are ignored. If object C is added later, the role permissions for C must be added manually, or the role must be imported again.

When you export role that have permissions for viewing certain reports, ensure that the reports exist in the target environment. If the reports are missing, then consider removing the permissions before exporting the role.

37.5.14 Back Up the Database

Before you import data into a production environment, back up the database. This enables you to restore the data if anything goes wrong with the import. Backing up the database is always a good precaution before making significant changes.

Note:

When you import forms and user-defined fields, you add entries to the database. These database entries cannot be rolled back or deleted. Before each import operation, ensure that the correct form version is active.

37.5.15 Import Data When the System Is Quiet

You cannot complete an import operation in a single transaction because it includes schema changes. These changes affect currently running transactions on the system. To limit the effect of an import operation, temporarily disable the Web application for general use and perform the operation when the system has the least activity, for example, overnight.

37.5.16 Migrating Custom Data Objects

The SDK table contains metadata definitions for user-defined data objects. When you import data from an XML file into the SDK table, the values in the SDK_SCHEMA column might be modified with the schema name of the source system where the XML file was created. For this reason, after you import data from an XML file into the SDK table, you must check the schema name in the SDK_SCHEMA column, and if necessary, manually change it to the schema name on the target system where the Oracle Identity Manager database is running. To update the schema name in the SDK_SCHEMA column, run a SQL query similar to the following with SQL*Plus on Oracle Database installations or with SQL Query Analyzer on Microsoft SQL Server installations:

UPDATE SDK SET SDK_SCHEMA='target system schema name'

If you do not update the schema name in the SDK_SCHEMA column, an error similar to the following might be generated when you import other XML files that modify user-defined field (UDF) definitions:

CREATE SEQUENCE UGP_SEQ
java.sql.SQLException: ORA-00955: name is already used by an existing object

37.5.17 Remove Data Object Fields Before Importing Event Handlers as Dependencies

The Deployment Manager does not import event handlers that include data object fields if the event handlers are imported as dependencies. For this reason, you must remove the data object fields from any event handlers that you want to import as dependencies with the Deployment Manager.

37.6 Best Practices for Using the Horizontal Migration Utility (Deprecated)

Note:

In Oracle Identity Manager 11g Release 2 (11.1.2), the Deployment Manager supports migration of all artifacts that are migrated by using the horizontal migration utility in earlier releases of Oracle Identity Manager. Therefore, Oracle recommends using the Deployment Manager for migrating all such artifacts, for example, custom resource bundle and plug-ins.

The following are some of the suggested practices and pitfalls to avoid while by using the horizontal migration utility:

37.7 Migrating the Policies

You can migrate the policies from one Oracle Identity Manager deployment to another, for example, from a test environment to production environment, using the migrateSecurityStore WLST command utility provided by Oracle Platform Security. For example, to migrate all Oracle Identity Manager approval policies from the source to target, run the following migration command in overwrite mode from the WLST prompt:

migrateSecurityStore(type="appPolicies",configFile="<configuration file path>", src="DBsourceContext", dst="DBdestinationContext", srcApp="OIM", dstApp="OIM", overWrite="true")

For information about the various parameters used with the migrateSecurityStore command and the usage options for the utility, see the 'migrateSecurityStore' section in "Infrastructure Security Custom WLST Commands" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for 11g Release 1 (11.1.2).

For information about constructing the configuration file, see "Migrating Policies Manually" in the Oracle Fusion Middleware Application Security Guide for 11g Release 1 (11.1.1).

Note:

While creating the configuration file for migration of Oracle Identity Manager policies, make sure that the following properties are set for the source system as well as the target system, as shown:
<property value="cn=mySourceDomain" name="oracle.security.jps.farm.name"/>
<property value="cn=mySourceRootName" name="oracle.security.jps.ldap.root.name"/>

You can take these values from the jps-config.xml file in your domain at the following directory path:

DOMAIN_HOME/config/fmwconfig/

Search for the property names in the jps-config.xml in your domain home and copy the value to this configuration file.

For the source system values, search in the domain home of the source system, and similarly for the target system.

37.8 Troubleshooting

This section contains the following topics:

37.8.1 Troubleshooting Deployment Manager Issues

While importing data by using the Deployment Manager, the following information is displayed on the UI for an import failure:

  • The entity for which the import failed

  • The type of the entity for which the import failed

  • The specific error message from the exception object

This information is also printed in logs along with the exception trace.

Figure 37-3 shows a sample error message that is displayed when Deployment Manager import fails.

Figure 37-3 Deployment Manager Import Failure

Description of Figure 37-3 follows
Description of "Figure 37-3 Deployment Manager Import Failure"

This helps the user in identifying which entity is causing the failure and why, and the user can try removing that particular entity and importing again if it is not necessary to be imported on the target system. This also helps the support team and developers in identifying the issue if it happens.

Table 37-2 lists the troubleshooting steps that you can perform if you encounter a failure:

Table 37-2 Troubleshooting Deployment Manager

Problem Solution

In Oracle Identity Manager 11g Release 2 (11.1.2), scheduled job has a dependency on scheduled task. Therefore, scheduled task must be imported prior to scheduled job.As a result, if a XML file has scheduled job entries prior to scheduled task entries, then importing the XML file using Deployment Manager fails with the following error message:

[exec] Caused By: oracle.iam.scheduler.exception.SchedulerException: InvalidScheduleTask definition
[exec] com.thortech.xl.ddm.exception.DDMException

Open the XML file and move all scheduled task entries above the scheduled job entries.

Deployment Manager export fails for any object. User is prompted with Export Failed dialog box, and no exception is found in the server log.

When you look at the JRE console, you can see the following:

java.security.AccessControlException: access denied (java.io.FilePermission PATH_AND_NAME_OF_THE_FILE)

Perform the following steps:

  1. Modify your java.policy in the JRE_HOME/lib/security/ directory.

  2. Replace the existing policy file content with the following:

    grant{
    permission java.security.AllPermission;
    };
    
  3. Restart the browser to load the policy again. You can now export the data.

The following error occurs while importing an XML file:

Caused by:
oracle.iam.reconciliation.exception.ConfigException: Profile :Xellerate User InvalidAttributes : 

Perform any one of the following:

  • Remove the attribute on which the error is generated from the XML, and then try importing.

  • Create the missing UDF or other attributes by using configuration service, and then retry the import.

  • Export the UDF shown as missing dependency. Import this UDF first before importing the current XML.

Importing approval policy might result in the following error:

weblogic.kernel.Default (self-tuning)'] [userId: xelsysadm] [ecid:
f9e72ab2a292a346:-188377b2:12f96ae9676:-8000-0000000000000047,0] [APP:
oim#11.1.1.3.0] Exception thrown {0}[[
oracle.iam.platform.entitymgr.ProviderException: USER_NOT_FOUND

An approval policy rule is invalid if it points to an entity (user or organization) that does not exist in Oracle Identity Manager. These invalid approval rules must be corrected to point to a valid entity (user or organization) before the import.


37.8.2 Troubleshooting Migration of Policies

Table 37-3 lists the troubleshooting step that you can perform if you encounter issues related to migration of policies.

Table 37-3 Troubleshooting Migration of Policies

Problem Solution

The following error is displayed:

oracle.security.jps.service.policystore.PolicyStoreIncompatibleVersionException: JPS-06100: Policy Store version 11.0 and Oracle Platform Security Services Version 11.1.1.6.0 are not compatible

Not being able to connect or find the policy store can be the possible causes of this error message. To troubleshoot the problem, check the configuration file for the database connectivity details, root name, and farm name for both source and target.


37.8.3 Enabling Logging for the Deployment Manager

To enable logging for the Deployment Manager:

  1. Add a new logger for the Deployment Manager by editing the logging.xml file, which is located in the following directory path:

    DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/

    For instance, to enable Notification-level logging for Deployment Manager, add the following logger inside the <loggers> section:

    <logger name='XELLERATE.DDM' level='NOTIFICATION:1' />
    
  2. Change the log level defined in the relevent <log_handler>.

    See Also:

    "Configuring Logging" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about logging level and log handlers in Oracle Identity Manager