Migration Behavior

The migration function creates, updates and deletes configuration. To do this, the migration function has to recognize the same configuration item across environments. Finding the existing counterpart of a configuration item in the migration payload is referred to as matching.

Matching top level items is a two-pass process. The first pass attempts to match the universally unique identifier (UUID) of the item in the migration set to an existing item on the target environment. The UUID is a system generated key, that is assigned to each configuration item upon creation, unless created through a migration. If the item is created through a migration the UUID of the item in the migration payload is adopted. This ensures that the UUID for the same configuration item is the same across all environments, as long as the migration function is the only means of creating new configuration items on target environments. If the function succeeds in finding an existing configuration item with the same UUID, then that item is updated or deleted.

If the UUID match fails, the second pass attempts to match on a functional key, that is, a user defined key. For most configuration items the "Code" field is the functional key. This means that if the item in the migration payload has the same code as an item in target environment then it is considered a match. Some configuration items have a more elaborate functional key because they do not have a code, for example, an exchange property. For these items the secondary match is based on a combination of functional attributes.

The reason for the two-pass approach is that neither UUID matching, nor functional key is foolproof; matching on UUID breaks in the scenario where the configuration is already existent on the target environment (through means other than migration), matching on the functional key breaks when a key field is updated on the source environment. The combination of both leverages the merits of both patterns; robustness against updates of key fields and the ability to identify the same configuration items across environments.

Some functional keys comprise language dependent fields. The functional keys in the migration set are the keys in context of the default language on the source environment. Upon import, language dependent functional keys are interpreted in context of the default language of the target environment.

If neither the UUID nor the functional key matches, the migration function inserts the configuration item on the target environment. If either match succeeds, then all functional attributes of the existing item are updated with the value provided in the migration payload. Any existing detail matched with a detail in the migration set is updated. Any existing detail not matched is deleted. Details in the migration payload that do not exist on the target environment are inserted.

Because most of the details are matched on UUID alone, updates details that have not been created by a prior migration follow a replacement pattern (that is, as opposed to an 'update' pattern). If an item (top level or detail) is matched on functional key then the existing item adopts the UUID in the migration payload.

Items Matched on UUID and Functional Key

The following items are matched on both UUID and functional key

Access restriction Access role Agent configuration Boilerplate text

Destination Dynamic logic Exchange property Message

Floorplan Floorplan Tag Detail Integration Integration parameter Integration step Subflow User sequence

Most top level items have a single attribute that is the designated functional key, that is, the code, name or start date of the item.

The following items are also matched on both their UUID and functional key, but are exceptional in that they use a set of attributes serving as a composite functional key, rather than a single attribute.

Item	Functional Key
Exchange Property	Property name and datatype
Floorplan Tag Detail	Tag and Floorplan
Integration	code, type and version

Items Matched on UUID Alone

The following objects are always integral to another object and cannot exist standalone. These are typically intersection objects without a functional key - they are matched only on UUID.

Access restriction grant Agent configuration integration

Items Matched on Functional Key Alone

The following items cannot be added to a migration set but may be referenced by items that can be. These items never match on UUID because they are seeded or loaded through integration points for reference data, implying that there will be different UUIDs across environments.

Language Signature

Delete by Omission

The following configuration items depend on top level items - they cannot exist by themselves. The configuration import function treats these just like other attributes on the top level item; if not present in the payload, that means these items have been removed on the source environment and therefore can be deleted in the target environment as well.

Access restriction grant Agent configuration integration Integration parameter Integration step Floorplan tag detail

Switching Off Delete by Omission

The ‘delete by omission’ behavior is enabled by default. The user can override this behavior either when creating a new migration set in the source environment or when importing a migration set in the target environment. This behavior applies across all entities in the migration set; either all dependent items are deleted by omission or none of them are.

If the user overrides the behavior upon generation of the migration set, then the payload is marked so that the target system knows not to delete by omission. If the user specifies the desired delete behavior upon importing a migration set, then the import ignores the whatever instructions are included in the payload.

To clarify this feature, consider the image above. The default system behavior removes item 7870 but if the user disables the ‘delete by omission’ feature then item 7870 remains unaffected.

Multiple Languages

It is possible to install an Oracle Health Insurance application with multiple languages. A configuration item will have a representation for each of the installed languages. When creating a migration set, each of those representations is automatically included; there are no options to exclude a particular language.

In the scenario where the source and target environment do not have the same languages installed, the following happens upon importing the migration set: the configuration item representations of any language that is not installed on the target environment are ignored; the existing configuration items representations of a language that is not in the migration set is left untouched.

For example, suppose the target environment supports both Spanish and English and the source environment supports only English. In this scenario, only the English language specific fields will be updated on the target environment.

Business Rules

Business rules protect the configuration consistency and remain active during migration. When a piece of configuration is updated, it will automatically be re-validated against its business rules. Because some business rules are controlled by set-up, it is possible for configuration to be out of sync with its governing business rules. In other words, changing a business rule does not automatically re-validate existing data. If a source environment has such inconsistencies, a migration may lead to unexpected business rule violations.

For example, consider the scenario where - on the source environment - a new mandatory dynamic text field is added to the messages table (OHI_MESSAGES). When this new field is set up, none of the existing messages will have a value; the existing messages are in conflict with the new set-up. It is only when to update an existing message or add a new message that the system requires the user to enter a value for the mandatory dynamic field. When the existing messages are migrated, they will run into that same violation on the target environment. Because all data comes from a validated source no validation errors will occur when doing a full migration. If referred elements however are "carved out" of the payload and the referred data does not exist in the target environment, validation errors may occur. For this reason validation business rules will not be switched off in the target environment during the load of the data-set.

System Specific Configuration

System specific configuration is seeded configuration that cannot be removed or inserted by the users of the application. It is possible to update specific fields on system specific configuration, so for that reason system specific configuration can be included in the migration payload. The migration import function never inserts or deletes system specific configuration. Messages are the primary example of system specific configuration.