Thursday Jan 17, 2013

Configuration Migration Assistant Part 4 - Migration Plans

The Configuration Migration Assistant is meta data driven. It uses the Oracle Utilities Application Framework meta data to drive the underlying engine to migrate the data. With the delivery of each product a predefined set of configuration objects are provided preconfigured to be used by sites. It is possible to extend these definitions and this next set of articles will introduce these objects and how to build your own configurations for custom objects.

Before we discuss the configuration objects there is one piece of information that you need to understand. For an object to be migrated using Configuration Migration Assistant it must have two attributes:

  • It must not have a system generated random primary key. These types of keys may vary from environment to environment and attempting to migrate data with these types of keys may result in unintentional results and even corruption. Configuration data tends not to use random system generated keys but Master and Transaction data does. Configuration Migration Assistant cannot be used for Master or Transaction Data. Master data is things like Accounts, Meters, Crews, Persons, Assets etc.. Transaction Data is data like Bills, Payments, Meter Reads, Tasks etc...
  • Fundamentally Configuration Migration Assitant uses Maintenance Objects to process data but each object to be migrated must have a Business Object for configuration purposes. The Business Object can be any valid Business Object definition. More guidelines about this are in Configuration Migration Assistant Overview (Doc Id: 1506830.1).

The first object to configure for Configuration Migration Assistant is the Migration Plan.  This object defines a primary Business Object and any directly related subordinate Business Objects that must be migrated as a single entity. The relationship between the business objects and the sequence of migration is configured in this object.

The following information is configured:

  • Instruction Sequence - The sequence number for the migration instruction. This is used to process the data in the correct order.
  • Instruction Type - This sets the migration instruction type. There are two values: Primary or Subordinate. There can only be one Primary Instruction Type per Migration Plan.
  • Parent Instruction Sequence - If the Instruction Type is Subordinate, then this is the Instruction Sequence for the parent object for this object. Subordinates can be related to other Subordinates to document multi-level structures.
  • Description and Business Object - The Business object for this instruction. The description is a free format field to allow you to document the instruction. Usually this is populated with a short description of the object.
  • Traversal Criteria Type and Traversal Criteria - This is a definition of how the subordinate is related to the parent object. Configuration Migration Assistant allows you to specify Constraints in the meta data, SQL Statements or XPATH statements to document the relationship. The latter is useful for relating complex business object relationships that arte buried in XML definitions. The Criteria Type determine which method you want to use to express the relationship and the Criteria is the statement to express the relationship. The online help contains examples and guidelines for the Criteria formats supported.
  • Next Migration Plan - Configuration Migration Assistant allows you to reuse Migration Plans and this field allows you to link Migration Plans for consistency. We will discuss this feature in future posts.
  • Algorithms - One of the features of the Configuration Migration Assistant is the ability to manipulate the data upon import. This is where the specification of the algorithm is performed. This is typically done on the target environment.

To do this use the Admin --> M --> Migration Plan menu option.

For example:

 Example Migration Plan

Note: Remember, the product ships with a predefined set of Migration Plans for you to use. You may not have to configure this unless you want to copy the provided plans to tailor them or add custom business objects.

Each object to migrate using the Configuration Migration Assistant must exist in at least one Migration Plan.

For more information about this aspect of the Configuration Migration Assistant and other aspects refer to the Configuration Migration Assistant Overview (Doc Id: 1506830.1) whitepaper available from My Oracle Support.  

Wednesday Jan 16, 2013

Configuration Migration Assistant Part 3 - Master Configuration

The first configuration step that must be performed for the Configuration Migration Assistant, as part of Oracle Utilities Application Framework V4., is to setup a Master Configuration Record for the Migration Assistant Configuration. This record sets up the locations of files exported and imported for each environment. It also sets the suffix for the files.

This must be performed once per environment and before any export or import activities are performed.

To setup this record the following process can be used:

  • Logon to the product environment you wish to configure using the browser
  • Navigate to the Admin --> M --> Master Configuration menu item.
  • Find the Migration Assistant Configuration item. If none, exists you can create it using the Add Action (+).
  • Edit the Migration Assistant Configuration Master Configuration Record by clicking on the name or Action field. For example:

Master Configuration

  • Specify the following on the edit dialog:
    • Export Directory - Directory to place export files into for exports initiated from this environment
    • Import Directory - Directory to get import files from for imports reqeusted for this environment
    • File Suffix - The file suffix (including the '.') to attach to the file automatically.The suffix is simply used to be able to denote the file. The choice of file suffix does not affect the format of the contents of the file at any stage.

Migration Configuration

  • Save the Record.

For the Export and Import Directories you can use any valid directory but the directory must be read writeable by the user you will use for the export and readable for the user you will use for the import. Security will be discussed in a later post.

From an implementation point of view these directories can be setup as follows:

  • You can use the same directories for import and export.
  • You can use different directories for import and export.
  • You can use a common directories or seperate directories for each environment. For example, you can specify a global set of directories to share files easily. If you use seperate directories you will have to manually transfer export files across these directories.

For more information about this aspect of the Configuration Migration Assistant and other aspects refer to the Configuration Migration Assistant Overview (Doc Id: 1506830.1) whitepaper available from My Oracle Support. 

Friday Jan 11, 2013

Configuration Migration Assistant Part 2 - Flows

To use the Configuration Migration Assistant facility in Oracle Utilities Application Framework V4. the are two main sets of step that must be performed:

  • Configuration - The Configuration Migration Assistant must be configured at an environment level to determine the locations of data exports and imports as well as definitions of the migration specifications.
  • Execution - Registering the intent to export and import data as well as physically exporting and importing the data. Once the data has been imported performing approval of specific changes and then applying the import data set.

These topics will be individually covered in subsequent entries in this blog to target specific settings. The flow diagrams illustrate a summary of the processes used in the Configuration Migration Assistant.

Configuration Flow

To configure the Configuration Migration Assistant the following must be performed:

Configuration Flow

  • Migration Master Configuration - Define the default location for import and export files generated by the Configuration Migration Assistant. Define the default file suffix for the export/import files. This task only has to be done once per environment and must be performed BEFORE the first export or import task is performed.
  • Define Migration Plans - Define the Business Object definitions and their relationships to migrate the group of Business Objects as a single unit. The sequence and relationship is defined for the associated child objects. The relationship, known as Traversal Criteria, is expressed as Constraint, SQL expression or XPath statement describing the related data.
  • Define Migration Requests - Define the groups of migration plans to migrate as a set including the selection criteria expressed as SQL expression, XPath statement or algorithm.

Execution Flow

Once configuration is complete on the source environment then the execution component of the feature can be used to perform migrations. The following flow summarizes these processes:

Execution Flow

  • Define Migration Export - Register the intent to export the data with the Migration Request to use for the export and the file name to use for the export. The Migration Master Configuration record for the environment is used to set the location and suffix. This process wont actually export the data, hence the word intent, it simply registers the fact that you want to export the data.
  • Export Data - Execute the Migration Monitor batch process to physically export all the active Migration Export requests using the specification on the Migration Export.
  • Define Migration Import - Register the intent to import the data file from the import directory. The migration import directory and file prefix are taken from the Migration Master Configuration record for the environment.
  • Import Data - Execute the Migration Monitor batch process to physically export all the active Migration Import requests using the specification on the Migration Import. At the is time the use of the Approval/Rejection process can be defaulted by change type. At this time a Migration Data Set is created to hold the changes.
  • Approval Process - If there are any manual changes that require approval can be manually approved. Regardless of whether approvals are required, the Migration Data Set must be marked Ready to Apply.
  • Apply Changes - Execute the Migration Monitor batch process to physically apply the changes. The Migration Data Set will display the status of each change at application time. Data is re-validated at the time of application to maximize data integrity.

Each of these processes will be expanded on in future blog entries with guidelines. For more information on this facility refer to Configuration Migration Assistant Overview (Doc Id: 1506830.1).

Oracle Access Manager Integration Landing Sample

In the Oracle Identity Management Suite Integration with Oracle Utilities Application Framework based products (Doc Id: 1375600.1) whitepaper the Oracle Access Manager integration section mentions a custom landing page that can be used to complete the integration.

A sample landing page is now available from My Oracle Support for customers to use as a basis for their own landing pages. It is located within My Oracle Support under Sample Code oamlanding.jsp - refer to the Instructions in Note 1375600.1 (Doc Id 1518856.1).

This is a sample only and should be tested and modified to suit your individual site needs. Refer to Doc Id 1375600.1 for instructions on how to use the landing page.

Configuration Migration Assistant Part 1 - Features

One of the main features of Oracle Utilities Application Framework V4. is the Configuration Migration Assistant. The Configuration Migration Assistant is a new facility to allow customer owned configuration data to be migrated from one environment to another. Customers using Oracle Utilities Customer Care and Billing and Oracle Enterprise Taxation and Policy Management will use this new facility instead of Configuration Lab for versions of those products using the Oracle Utilities Application FrameworkOracle Utilities Application Framework V4. and above.

The features of this new facility are:

  • Meta Data Driven Migration - The Configuration Migration Assistant uses the meta data within the product to understand the data and the relationships. A set of new migration objects have been added to define reuseable data relationships, sequence of migration and groups of data to migrate.
  • Reusability - The Configuration Migration Assistant emphasizes resuablility across migrations by providing reuseable migration plans allowing customers and partners to combine base and custom migration plans into reusable migrations.
  • Simple design - The Configuration Migration Assistant simplifies the specification and exeuction of migrations. No technical setup outside the product is required.
  • Support for different relationship types - Relationships between objects can be expressed using Constraints, SQL statements or XPATH statements. This allows Configuration Migration Assistant to support the wide variety of configuration objects in the products.
  • Export Data to a File - The export process now exports data to a file rather than using database links. This allows the export to be checked in to a code respository to match the code components involved in a configuration. This also allows the exports to be reused and imported across many environments and even be used to rollback configuration changes on a global basis within an environment.
  • Approval/Rejection of Changes - Individual changes can be forced to be approved before they are applied allowing customers fine levels of control over changes in their target environments.
  • Data Manipulation upon Import - Data can be manipulated upon import, using algorithms, to avoid configuration conflicts. For example, when importing Batch Controls the batch run numbers can be manipulated upon import to ensure they are consistent in the target environment.

Over the next few weeks there will be a series of articles on this blog highlighting the Configuration Migration Assistant and its features and configuration. For more details about the facility refer to Configuration Migration Assistant Overview (Doc Id: 1506830.1) available from My Oracle Support.


    Anthony Shorten
    Hi, I am Anthony Shorten, I am the Principal Product Manager for the Oracle Utilities Application Framework. I have been working for over 20+ years in the IT Business and am the author of many a technical whitepaper, manual and training material. I am one of the product managers working on strategy and designs for the next generation of the technology used for the Utilities and Tax markets. This blog is provided to announce new features, document tips and techniques and also outline features of the Oracle Utilities Application Framework based products. These products include Oracle Utilities Customer Care and Billing, Oracle Utilities Meter Data Management, Oracle Utilities Mobile Workforce Management and Oracle Public Service Revenue Management. I am the product manager for the Management Pack for these products.


    « January 2013 »