Migrating configuration changes in ObjectManager

You can use the ObjectManager tool to migrate configuration changes from one environment to another.

The source and target environments must have the same version and patch level of OpenPages®.

Multiple environments

If you have a multiple environment where changes to the IBM OpenPages application are tested and validated prior to implementation, you can use ObjectManager, a command line interface (CLI) tool, to migrate configuration changes from one deployment environment to another.

For example, Company 1 might use the following deployments:

Development - Configuration changes are made to the user interface and tested to validate that the changes are applied correctly. The OpenPages repository used in this environment might contain fewer objects (partial instance data) than the Production environment.
Test - Configuration changes from the Development environment are imported (to avoid error) and validated through the ObjectManager tool and tested. The OpenPages repository used in this environment generally mirrors the instance data in the Production environment.
Production - The tested configuration changes from the Test environment are imported (to avoid error) and validated through the ObjectManager tool, and then made available to end users (Live Production).

In contrast, Company 2 might, for example, combine Development and Test into a single Test environment. In this case, the configuration changes in the Test environment are migrated the Production environment.

The ObjectManager migration process

Using the ObjectManager tool, you can migrate configuration changes from one environment to another.

You can migrate the following configuration items:

Field Groups
Object Types
Filters
Field Dependencies
Dependent Picklists
Object Type Relationships
Profiles
Application Text
Object Text
Settings (excludes server-specific settings in the IBM OpenPages repository)
Rules (from the Rules Engine)
Workflow definitions in GRC Workflow
Jobs in the Scheduler
Calculations (from GRC Calculations)
Solution visualizations

You can also export and import security rules. However, any existing security rules are overwritten by the import. If you want to migrate security rules, export the security rules from the target environment, modify the exported file to add or modify the security rules, and then import the updated file into the target environment.

To limit the scope of the configuration items that are exported, you can use the settings in the ObjectManager.properties file. For more information, see Modifying ObjectManager settings.

Table 1 outlines the process that you can follow if you want to migrate configuration changes, for example, from a Test environment to a Production environment.

Note: If you also have a Development environment, you can use the tasks that are outlined in Table 1 to do an initial export of the configuration data from the Development environment to the Test environment.

Table 1. Tasks for migrating configuration changes
Use this deployment...	To do this task...	Related topic...
Test	1. Modify settings in the ObjectManager.properties file to limit the scope of the export data to only configuration items.	See Modifying ObjectManager settings.
Test	2. Export the configuration changes to a file.	See Exporting configuration changes.
Production	3. Compare the configuration changes from the source environment (Test) against the target environment (Production).	See Validating configuration changes.
Production	4. Import the configuration changes (from task 3) into the target environment.	See Importing configuration changes.
Production	5. Review the log file. Look for any errors.

Modifying ObjectManager settings

Before you begin migrating configuration changes from one environment to another, you can configure ObjectManager to include only configuration items in the migration process and exclude additional object data, such as Resource or Job Type data, from the migration metadata and changes.

You can also configure ObjectManager to include settings from the export.

Limiting the export of changes to configuration objects

By default, the ability to export metadata changes is set to include all objects. To export changes made only to configuration objects, modify some of the settings in the ObjectManager.properties file.

Procedure

In a text editor of your choice, open the ObjectManager.properties file (see Modifying the ObjectManager properties file).
Navigate to the following setting in the file:

configuration.manager.migrate.configuration.objects=false
Change the value of this setting from false (default) to true (export only configuration object changes).

configuration.manager.migrate.configuration.objects=true
Save your changes to the file.
If you want to modify IBM OpenPages repository settings that are excluded, by default, from the migration process, follow the instructions in Modifying excluded settings from export.

Modifying excluded settings from export

If the value of some IBM OpenPages settings were changed to reflect a particular environment, you can optionally exclude these settings when you export.

For example, if WalkMe is enabled in the Development environment but not in the Test environment, you can exclude the WalkMe Enabled setting from the export of configuration metadata and changes.

You exclude settings from export by modifying the ObjectManager.properties file. A statement that excludes a setting from export has the following syntax:

configuration.manager.migrate.configuration.exclude.registry.entry.<n>=<setting>

Where:

<n> is a sequential number.
<setting> is the full path and name of the setting you want to exclude. The path must begin with /OpenPages. For example:
```
configuration.manager.migrate.configuration.exclude.registry.entry.23=/OpenPages/Applications/WalkMe/WalkMe Enabled
```

By default, OpenPages excludes certain configuration settings from the export process. These settings are listed in the ObjectManager.properties file along with their full path and name. For example:

configuration.manager.migrate.configuration.exclude.registry.entry.1=/OpenPages/Applications/Common/Email/Mail Server

You can add additional settings to the list for exclusion or remove an existing setting from the list to include it in the export.

Procedure

Open the ObjectManager.properties file (see Modifying the ObjectManager properties file).
Locate the following setting in the file. Use this property as the basis for specifying additional settings for exclusion:
```
configuration.manager.migrate.configuration.exclude.registry.entry.
1=/OpenPages/Applications/Common/Email/Mail Server
```
To exclude additional settings from export, copy the line of code in Step 2 and do the following:
1. Paste the code at the end of the list (for example, after 22).
2. Increment the number (for example, 22).
3. Specify a full setting path and name. Use a single line.
  For example:
```
configuration.manager.migrate.configuration.exclude.registry.entry.23=/OpenPages/Applications/WalkMe/WalkMe Enabled
```
Save your changes to the properties file.
Use the ObjectManager dump command to export the data. See Dump command syntax. Not all items in the exclude list will be in the XML dump file.

Note: Changes to ObjectManager.properties are ignored when you use Environment Migration.
To export a configuration setting that is on the excluded list, remove the line of code for that setting from the ObjectManager.properties file.

Disabling triggers when migrating environments

When extracting and restoring environments by using ObjectManager, you might need to disable any triggers that are checking data validity. This setting is normally applied automatically, but you can disable triggers if the need arises. This procedure disables all triggers in the system.

Procedure

Access the Settings page (see Viewing the Configuration and Settings page).
Go to the Applications > GRCM > Disable Triggers setting.
In the Value field, type true.
Click Done.

Migrating configuration changes

After you modify settings in the ObjectManager.properties file, you can begin the migration process.

Migrating configuration changes from one environment to another involves exporting, validating, and importing the changes.

Note: The source and target environments must have the same version and patch level of OpenPages.

Exporting configuration changes

Exported data represents a snapshot of the configuration objects in the IBM OpenPages repository for a particular deployment.

When you export configuration changes, you specify a file path and prefix for the file name in the command line. When the data is exported, the ObjectManager tool automatically appends -op-config.xml to the file name prefix to complete the file name.

For example, if you specify the myconfig prefix in the command line for the file name, it results in this file name: myconfig-op-config.xml.

Procedure

Verify that the OpenPages application is running.
Open a command or shell window.
Go to the directory where ObjectManager is installed.
Run the ObjectManager dump command on a single line.
To compare the exported configuration data against the configuration data in the OpenPages repository of the next deployment environment, see Validating configuration changes.

Validating configuration changes

By default, ObjectManager validates loader files when you run load commands. You can also validate loader files by using the validate command.

About this task

By default, validation is enabled in the ObjectManager.properties file:

configuration.manager.validation=true

The validation process does the following checks:

Checks that the loader file is a valid ObjectManager XML loader file.
Verifies that the configuration items in the loader file exist in the environment.

When you run the validate command, the output is displayed in the following locations:

On the screen during the validation process
If you want to review the results at a later time, you can re-direct the screen output to a file.
In the ObjectManager.log file
This log file is located in the bin/logs directory by default.

Procedure

Open a command or shell window.
Go to the directory where ObjectManager is installed.
Run the ObjectManager validate command on the file that you want to validate.
Review the output for any errors.

Validation errors indicate a problem with the loader data. Correct the errors before you import the configuration changes into the target environment.

The following sample validation error indicates that the name field in the export file has an empty value.

VALIDATION ERROR (Line: 104481 Column: 57): Attribute 'name' is either empty or not provided.

Errors can also occur when a configuration item does not exist in the target environment. In this example, the application string iam.create.computedlinks does not exist in the target environment:Processing 'applicationString', Attribute: 'name', Value: 'iam.create.computedlinks' is either not defined or associated correctly. Make sure it exists in the migration package or in the target system!
To import the configuration changes to the target environment, see Importing configuration changes.

Importing configuration changes

After comparing and validating the configuration metadata and changes, you can migrate the changes to the current deployment environment or system.

When you import the configuration changes from the previous deployment, the configuration objects in the IBM OpenPages repository of the current deployment are updated with those changes.

Note: The source and target environments must have the same version and patch level of OpenPages.

An alternative to using the command-line interface (CLI) tool in ObjectManager is to use Open Administration menu > System Migration > Import Configuration to import the XML file. For information, see Importing a migration file.

Procedure

Verify that the OpenPages application is running.
Open a command or shell window and change to the <OP_HOME>/bin directory of your OpenPages installation.
From the command or shell window, run an ObjectManager command on a single line:
1. On a computer running a Microsoft Windows operating system:
```
ObjectManager load config <admin-user> <password> <config-folder-path> <prefix>
```
2. On a computer running a Linux® operating system:
```
./ObjectManager.sh load config <admin-user><password> <config-folder-path> <prefix>
```
Where:
- <admin-user> is the user name of the Super Administrator account (for example, OpenPagesAdministrator).
- <password> is the password of the Super Administrator account.
- <config-folder-path> is the file path to the folder where the exported file will reside. If the folder does not already exist, ObjectManager will create it.
- <prefix> is the prefix for the file name that will be used by ObjectManager.
For example, on a Windows operating system:
```
ObjectManager load config OpenPagesAdministrator password c:\temp myconfig
```
To see the configuration changes in the application, stop and then restart the OpenPages application services.
To validate that the newly updated OpenPages repository matches the configuration changes from the export file, see the topic Validating configuration changes.
To export the configuration data to a file, see the topic Exporting configuration changes.

What to do next

If you loaded profiles, update the reporting schema. For more information, see Updating the reporting schema.

Reconfigure integrations that require passwords or API keys. These integrations include, for example, NeuralSeek, Wolters Kluwer, Thomson Reuters, and WalkMe.