ConfigLab - Design Guidelines

ConfigLab Design Guidelines
Tax and Utilities Global Business Unit March 2008
NOTE:
The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle's products remains at the sole discretion of Oracle.
Page 2
Note:.................................................................................................................... 2 Introduction ....................................................................................................... 5 Sample implementation................................................................................ 5 What is ConfigLab?........................................................................................... 7 Features .......................................................................................................... 8 ConfigLab configuration process Overview ................................................. 8 Phase 1: Setting Up Environments............................................................... 10 Step 1.1: Decide the environments .......................................................... 10 Sample Implementation Environment List .................................... 13 Development Environment use of ConfigLab.................................. 14 Release Environment use of ConfigLab............................................. 15 Limiting the number of Test Environments...................................... 15 Conversion environments and the use of ConfigLab....................... 16 Step 1.2: Decide the relationships between the environments............. 16 Sample Implementation Relationships ............................................ 17 Step 1.3: Decide the Supporting/Supported Environments................ 18 Sample Implementation Supported/Supporting............................ 19 Step 1.4: Decide the role of the supporting environment .................... 20 Sample Implementation Roles .......................................................... 21 Warning about the ConfigLab Role .................................................... 22 Design Patterns....................................................................................... 22 Step 1.5: Register the Environments........................................................ 24 Database links (ORACLE) ................................................................... 24 The Registration utility: EnvSetup.exe................................................ 25 When do I Re-register the environment? ........................................... 27 Automating the registration process.................................................... 28 Phase 2: Deciding what to transfer (the "what) .......................................... 28 What are DB Processes? ............................................................................ 28 Base Supplied DB Processes ................................................................ 29 Step 2.1: Review Custom Tables and Fields (Optional)........................ 30 Step 2.2: Review Custom Maintenance Objects (Optional) ................. 31 Guidelines for Custom Maintenance Objects.................................... 31 Step 2.3: Setup and Maintain DB Processes ........................................... 32 Consideration of Privacy....................................................................... 34 Phase 3: Executing ConfigLab ...................................................................... 35 ConfigLab Operations ............................................................................... 35 Step 3.1: Execute ConfigLab Jobs............................................................ 36
Page 3
Compare Source submission ................................................................ 36 Synchronize submission ........................................................................ 37 Defaulting parameters on Batch Controls.......................................... 38 Step 3.2 Approval Process......................................................................... 38 Step 3.3 Apply Changes Process............................................................... 41 Undesirable behavior in Apply Changes............................................. 41 Carried over changes.............................................................................. 42 Errors in Apply Changes....................................................................... 43 Common Design and Execution Problems in ConfigLab ........................ 43 Expected data is not copied ...................................................................... 43 Installation record not copied................................................................... 44 ConfigLab is running slow ........................................................................ 44 Appendices ....................................................................................................... 47 Cheat Sheets................................................................................................. 47 Cheat Sheet: Setting up a Compare Source relationship .................. 47 Cheat Sheet: Setting up a Synch Target relationship......................... 49 Cheat Sheet: Setting up a ConfigLab relationship............................. 51 Cheat Sheet: Priming an environment. ............................................... 53 Cheat Sheet: Rebuilding key tables ...................................................... 54 Alternative Development Solutions......................................................... 55 Transferring between offsite and onsite ............................................. 55 Use of ConfigLab role at Hartwell Energy......................................... 55 Hub and Spoke at Hartwell Energy..................................................... 56
Page 4
INTRODUCTION
White papers look best with at least one sidebar placed on each page so readers can scan important information.
With the release of Oracle Utilities Customer Care and Billing (CC&B) and Enterprise Taxation Management (ETM) a new facility called "ConfigLab" was released. This facility allows a site to copy data from one environment to another whilst maintaining data integrity. For this to be used, the facility must be configured to define the environments participating in the copy (the "who") and the data types to copy (the "what"). Whilst the facility seems complicated to setup and use, there is a simple way of configuring and using ConfigLab in your implementation. This document attempts to walk through a simple method of configuration of ConfigLab and point out some design guidelines to be considered when designing a ConfigLab solution for your site. Note: This whitepaper covers Customer Care And Billing/Enterprise Tax Management Version 2.x and above only.
Note: This whitepaper only covers the ORACLE database platforms. Refer to the Utilities documentation for the platform to cover DB2 and SQL Server platforms.
Note: This document does not cover how ConfigLab works to the depth of the base product documentation. If further detail is present for a particular section of this document, the relevant section of the base product documentation will be indicated. Refer to Chapter 81 Utilities Configuration Lab for an in-depth review of ConfigLab.
Sample implementation
During the course of this document a simulated sample implementation will be used to illustrate the design concepts outlined in the document. The sample implementation is an attempt to represent a "typical" implementation and show the many possibilities available in ConfigLab. The following scenario to be used: Oracle Utilities Customer Care and Billing (CC&B) has been selected by fictional utility called Hartwell Energy, a public utility offering gas, electric, water and waste water services to a
Page 5
community of around 700,000 accounts. The customizations of the implementation will be largely developed by an external development center with a small number of interfaces developed locally. As part of the Oracle Utilities Customer Care And Billing implementation the project team has decided they want to setup a number of environments to support the implementation activities. The environments the have decided to implement are: Release - This is where the data and programs from SPL Manila and locally developed will be applied and packaged. Playpen - A training and play area for all Hartwell Energy staff. Control - This is where the configuration data for the implementation is input centrally. All control data settings are placed in here and controlled by a configuration team. No other members of the implementation, apart from this team will access this environment to maintain integrity of the data. System Test - This is where the whole implementation for the site (including interfaces, configuration data and customization) are initially tested. User Acceptance Test - This is where the Hartwell Energy testing team will verify the software works according to their specifications in terms of technology as well as functionality. Maintenance - This is where any faults will be investigated fixed after implementation. Production - This is the end game. This is where the business will operate. Additionally the following information is applicable to this implementation: Each environment has an owner who controls data and functionality flow from other environments. Approval from the owner must be obtained to perform migration activities. A person in each environment is allocated to approve the migrations with the exception of the Maintenance environment who want to get regular updates from Production without the necessity of approvals. The following pieces of data need to be transferred across environments: Control Data - The Control environment is the source of this data. Meta Data - The Release environment is the source of this data. Only customizations need to be transferred. Account Data - A subset of the Production Data is the source of this data. Subset of Production - A subset of Production must be available in Maintenance for production fixes. The customer Project Director, Mr. Mark Brazil, wants your assistance in designing and configuring the Configuration Lab component of Customer Care And Billing to assist in migrations across the various environments to ensure data consistency and help make the implementation meet its commitments for pre and post implementation.
Page 6
Note: The solutions and design concepts related to this sample implementation are but one of many design solutions available using ConfigLab. Where possible, alternatives will be discussed to give a fuller spectrum of what may be valid for the sample implementation. Do not limit yourself to the examples in this document; they are a subset of what is possible.
WHAT IS CONFIGLAB?
ConfigLab is a copy facility between two environments that guarantee's data integrity.
Several years ago, one of the Customer Care And Billing customers wanted to be able to transfer their rates from one environment to another. This customer had very complex rates and to implement the rate in production, at that time, meant manually entering the rate. As the rate was so complex, the risk of human error in data entry may cause the rate to incorrectly bill. Therefore, they asked the Product Development group to add a rate copy that could copy the rate but also guarantee integrity of the production environment. In other words, not only copy the rate but guarantee that the copy process will not corrupt the production environment. After detailed analysis, the design was approved but the designers soon realized that a copy facility that would guarantee data integrity, would be useful for other migrations of data including: Copying configuration data from environment to environment to implement a common set of configuration settings and reference data. Typically this is performed from a Control configuration environment. Problematic customers and bills can be transferred to a "playpen" environment where the system's transactions are used to experiment with potential corrections without affecting production. Getting a copy of a subset of accounts from Production on a regular basis to test configuration changes against. Customer Care And Billing ships with a demonstration database with configuration data already loaded. Most implementations copy data from this demonstration database to start their configuration tasks. Copying rates from a test environment after they have been verified into Production to avoid data entry mistakes. Historical bills are transferred to a "revenue analysis" environment where the revenue team can perform what-if analysis to determine the impact of rate changes on future revenue. Business process scripts developed in a "development" environment can be promoted to a "QA" environment where they can be tested thoroughly before being promoted to production. And many more. The scope of ConfigLab was born.
Page 7
Features
ConfigLab does not only copy. ConfigLab can also manipulate the data in transit and filter the data according to criteria set up by administrators.
Given the new scope of the enhancement the feature list of ConfigLab had to expand to allow additional functionality required by other migrations. This included: Ability to filter data The data that is copied can be filtered using "SQL-like" statements as well allow for complex criteria via algorithms. For example, you can use an algorithm to perform complex checking and verification to decide if the copy is valid. Ability to manipulate data in transit If ConfigLab is going to touch any sensitive data, such as credit card numbers, SSN, driver licenses, names, addresses, phone numbers etc, then you may need to "jumble" the data to conform to local privacy laws. Copies data whilst maintaining integrity - Data copied is verified using business objects as part of the copy process so that any business rules are checked prior to the data being copied. Allows for approval and rejection of changes - It is possible to disallow types of changes (e.g. Deletes) as well as individual changes at the object level. Allows tracking of changes - ConfigLab has a query to show you the differences before approval and after approval has been found.
CONFIGLAB CONFIGURATION PROCESS OVERVIEW
Using ConfigLab involves setup of the environments and configuration of "what" is to be migrated.
To use the ConfigLab facility you must be perform the following: You must verify that it has been installed. This can be checked on the Installation Record use the Admin Menu I Installation Record Framework Accessible Modules menu option (see example below):
Note: From Oracle Utilities Customer Care And Billing/Enterprise Taxation Management V2.0.5 onwards, all modules are accessible. It must be configured correctly. This is the purpose of this whitepaper. To configure the ConfigLab facility a three-phase process is required. The diagram below illustrates the phases and steps involved in configuring ConfigLab:
Page 8
Phase 1: Environment Management Step 1.1 -Step 1.1 Decide Decide environments environments Step 1.2 -Step 1.2 Decide Decide relationships between relationships between environments environments Step 1.3 -Step 1.3 Decide supporting Decide supporting and supported and supported environments environments Step 1.4 -Step 1.4 Decide Decide environment roles environment roles Step 1.5 -Step 1.5 Register Register environments environments
Phase 2: ConfigLab Configuration Step 2.1 -Step 2.1 Review custom tables Review custom tables and fields and fields (optional) (optional) Step 2.2 -Step 2.2 Create custom Create custom maintenance objects maintenance objects (optional) (optional) Step 2.3 -Step 2.3 Setup and Setup and maintain DB processes maintain DB processes (optional) (optional)
Phase 3: ConfigLab Execution
Step 3.1 -Step 3.1 Execute Execute Compare Process Compare Process
Step 3.2 -Step 3.2 Approval Process Approval Process (optional) (optional)
Step 3.3 -Step 3.3 Execute Execute Apply Changes Apply Changes
Phase 1: Environment Management Setting up your environments for use with ConfigLab involves the following steps. Step 1.1 Deciding the environments This is deciding what environments will be setup and maintained to support the activities of your implementation. Step 1.2 Deciding the relationships between the environments Decide the data flows between environments (not the direction YET!!!). Step 1.3 Decide the supporting and supported environment Decide the nature of the relationship between the environments for each relationship identified in Step 1.2. Step 1.4 Decide the role of the environment For each relationship decided in Step 2 decide the direction of the flow of information. Step 1.5 Register the environments Register the supporting environments and associated roles in the supported environments. Phase 2: Configuration Lab Configuration Specifying the data that will drive the ConfigLab facility for your site, which involves the following steps. Step 2.1 Review Custom Tables and Fields (Optional) Maintenance of any definitions of custom table and fields for use by ConfigLab. Step 2.2 Create Custom Maintenance Objects (Optional) Maintenance of any definitions of custom maintenance objects (i.e. groups of tables and fields) for use by ConfigLab. Step 2.3 Create and maintain custom DB Processes (Optional) Definition and maintenance of groupings of maintenance objects to
Page 9
implement copying of related and non-related data including rules and filters. Phase 3: ConfigLab Execution - Once configuration is complete then ConfigLab is ready to use to migrate data between environments, which involves the following steps: Step 3.1 Execute Compare Process Execute the DB process that you defined to compare the two environments and highlight the differences. Step 3.2 Perform Approval Process (Optional) Manually Approve or Reject changes that have been highlighted. Step 3.3 Apply Approved changes Execute the Apply Changes process to implement the approved changes.
The first step to using ConfigLab is to setup the environments so that they can use ConfigLab.
PHASE 1: SETTING UP ENVIRONMENTS
The first part of designing a ConfigLab solution is to setup the environment and register them for use with ConfigLab.
Step 1.1: Decide the environments
Deciding what environments are going to be needed at your site and what environments are going to use ConfigLab is critical.
One of the first activities, in designing and implementing a ConfigLab solution, is to decide what environments are going to be created and used within an implementation. The number of environments that needs to be created needs to match the requirements of the implementation but do not go overboard. Remember each environment that is created needs to be maintained (e.g. upgraded) and takes up resources (i.e. person hours in support, disk space, CPU etc) on the machine it resides. Coming up with the right number of environments is crucial to the success of an implementation. In any implementation the number of environments varies greatly but a common set of environments are almost always present: Development A development environment exists as specified in the Oracle Utilities Development Suite documentation. This is where the developers will code and test their code for delivery to your site. Typically, in terms of ConfigLab the development environment may contain control data from your site. This is still under debate. Refer to "Development Environment use of ConfigLab" for a discussion of this point. Typically, if Oracle is commissioned to do this work then the Development environment is located on the Oracle Development Center premises and is not managed directly by the implementation. If an onsite development environment exists then it will be located on dedicated Windows based hardware. For more details of exactly what is available in this environment refer to the Oracle Utilities Software Development Kit
Page 10
documentation. For the purposes of this document we will assume a development environment is located somewhere for your implementation. Release (a.k.a. Packaging) If the Oracle Utilities Software Development Kit is used then an environment is required to compile the code on the target machine from the Development environment. This is because Oracle Utilities Customer Care And Billing and Enterprise Taxation Management are developed on the Windows platform and must be recompiled on the target platform to take advantage of any operating system specific performance facilities. From a ConfigLab perspective, the Release environment usually is NOT included in the ConfigLab solution but may be under certain circumstances. See "Release Environment use of ConfigLab" for a discussion on this subject. Control Typically most implementations want a Control environment where all the control and configuration data is entered. This is so that the data entry is controlled by a select number of authorized users and all other environments will source their control and configuration data from this environment. Testing Typically there will be a number of test environments to support the various testing activities performed in the implementation. The following testing activities may be performed in an implementation and require a separate testing environment: Unit Testing This is testing performed by the developers. Typically this is included in the Development environment but in some cases you may want to create an environment where the developers can do some testing onsite before release. Note: Check with your developers BEFORE creating this environment, as it may not be needed. System Testing/Functional Acceptance Testing This is testing that is performed by the System Integrator before actual delivery to the other testing environments. It is typically there to make sure the code works before doing rigorous testing. Note: Check with your System Integrator BEFORE creating this environment, as it may not be needed. Integration Testing/Interface Testing If there are a lot of interfaces or complex interfaces then there may be a need to perform separate testing of those interfaces prior to delivery to other environments. In this case an environment, which includes the interface applications, is setup. Typically, most implementations combine Integration or Interface Testing into either System Testing or User Acceptance Testing.
Page 11
Note: Check with your System Integrator BEFORE creating this environment, as it may not be needed. User Acceptance Testing/Site Acceptance Testing This is the environment where the site's testers perform acceptance testing on the system. This environment is a certainty to exist in your implementation. Market Acceptance Testing In implementation where deregulation or market participation is a component then a separate environment is sometimes created so that the site can participate in industry wide testing with other market participants. In less complex markets this type of testing is included in User Acceptance testing. Note: Check with your System Integrator BEFORE creating this environment, as it may not be needed. Performance Testing/Stress Testing One of the activities the IT component of the project MAY want to perform is a full volume performance and stress test to verify the configuration of the software and hardware. Typically this type of testing is very intense in terms of preparation (i.e. data preparation, volume simulation etc) and typically most implementations do not perform rigorous testing in this area. Note: Check with your System Integrator BEFORE creating this environment, as it may not be needed. These may represent single or multiple environments per type of testing. Typically the number of testing environments needs to be minimized. Advice on this subject is contained in "Limiting the number of Test Environments". Conversion Typically a set of environments to develop, test and execute conversion against are required. These environments use a special additional installation to denote them as conversion environments. From a ConfigLab conversion environments may be included, as data needs to be populated in these environments to support correct conversion of data. Training/Playpen During the implementation end user training is conducted within a training environment. Typically this is a subset of production with real or manufactured transaction data. The number of training environments will depend on the training schedule, number of users trained simultaneously and the type of training conducted. Before go-live typically sites create a playpen environment to allow site staff to "play" with the system after training and before go line to "hone" their skills. Production Obviously the production environment needs to be created, as it is the "end game".
Page 12
The above environments are only the typical environments to be considered for an implementation.
Sample Implementation Environment List
For Hartwell Energy the requirements outlined in "Sample implementation" the requested environments are: Development This will be located in a Development Center. While typically, this is not part of a ConfigLab solution at a site, we will include it for this example. We will assume that any issues outlined in "Development Environment use of ConfigLab" have been resolved for this site. Release This is where the code from SPL Manila will be delivered into and compiled. It will be then used for creating custom releases as outlined in the "Configuration Management Series Release Management" document. While typically, this is not part of a ConfigLab solution at a site, we will include it for this example. We will assume that any issues outlined in "Release Environment use of ConfigLab" have been resolved for this site. Testing System Test and User Acceptance Test are performed during the implementation so individual test environments have been created. Control A configuration Control environment is needed to centralize ALL configuration and control data changes. Only staff that is responsible for this activity will have access to this environment. Playpen This is established for playing wit the system and training staff. Maintenance After go-live maintenance and problem solving will be performed in a maintenance environment. This environment will not be created to close or after go-live. Production This is the end game. The diagram below outlines the above environments and associated environment identifiers.
Page 13
Hartwell Energy Environment List

Release Release (REL) (REL) Acceptance Acceptance (UAT) (UAT)
Env Id: 908444 Env Id: 908444
Env Id: 889653 Env Id: 889653
Development Development (DEV) (DEV)

Env Id: 701799 Env Id: 701799
System Test System Test (SYS) (SYS)

Env Id: 196503 Env Id: 196503
Env Id: 619100 Env Id: 619100
Production Production (PROD) (PROD)
Env Id: 568570 Env Id: 568570
Control Control (CTL) (CTL)
Maintenance Maintenance (MNT) (MNT)

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
Playpen Playpen (PLAY) (PLAY)
Typically, development environments are not included in a ConfigLab solution, as developers only require minimal configuration information, but it can be included in your solution, if necessary.
Development Environment use of ConfigLab
The inclusion of the Development environment(s) in a ConfigLab solution is under much debate. While Developers would benefit from having access to configuration and control data from other environments, there are three major issues with inclusion of the Development Environment in a ConfigLab solution: 1. If the Development environment is offsite, it may not be technically possible, permissible or practical to connect an off site resource (i.e. Development) with an onsite resource (i.e. other environments). If the site has strict access standards then you will not be able to define a DB link across sites or firewalls. The timing of Development with other activities may negate the possibility of using ConfigLab, at least in the initial stages. The Development environment is one of the first environments created so developers can start as soon as possible. Other environments may not be created yet to transfer data to Development. Typically Development is executed on a lesser-powered machine than non-Development resulting in potential performance issues with any ConfigLab process executed to and from Development. This also results on network issues as larger amounts of data are being transferred across the WAN rather than between UNIX machines (which does not usually go across a WAN).
2.
3.
If any of the above issues is applicable to your site then Development should not be included in your ConfigLab solution. If transferring data to Development is
Page 14
important, all is not lost, as there are alternative solutions that may suffice. These will be discussed in "Alternative Development Solutions".
Typically, release environments are not included in a ConfigLab solution, as the SDK installer is used to migrate meta-data, but it is possible to include it in your solution.
Release Environment use of ConfigLab
Typically the Release environment is only used to redeploy code from the development platform to the target platform. The Release environment may be included or excluded in a ConfigLab solution, depending on whether meta-data is to be sourced from the Release environment or not. Meta-data changes from the development environment are typically delivered in a form of an SQL script generated from the Oracle Utilities Software Development Kit. The scripts can be applied to the Release environment as part of the release process. If this is done, then the Release environment becomes the Control for the meta-data and must be included in your ConfigLab solution. Ideally, if this is the case, it is recommended that changes be then pulled into the Control environment for migration to other environments. If the Release environment is to be used only for compilation, it is recommended that all meta-data changes be applied directly to the Control environment for migration purposes. In this case, it is recommended that the Release environment not be part of the ConfigLab solution. It is difficult to determine which of the solutions (to include the Release environment in the ConfigLab solution or exclude it), is appropriate for your site. To aid in the decision making processing consider the following: If you include the Release environment in the ConfigLab solution, you will need another database instance to house the data. This means that this instance will only used for meta-data but will need to be maintained/upgraded. Usually most sites do not setup a dedicated database for the Release environment, as they want to reduce maintenance effort. Therefore most sites do not include the release environment in their ConfigLab solution. If you include the Release environment in the ConfigLab solution, then you need only migrate meta-data changes to the Control environment to reduce complexity.
Typically, sites will create a number of environments to support testing activities. It is possible to create too many environments than is typically required. There are techniques to minimizing the number of test environments.
Limiting the number of Test Environments
One of the areas of environment blowout is the number of test environments required by the site. Typically most groups want their own test environments but typically in larger implementations (or even a few small ones) this can lead to many environments to maintain and migrate to. Remember each environment must be backed up, upgraded and maintained so the more environments the more effort is required. Try and minimize the number of active testing environments in your implementation using these guidelines:
Page 15
Try to see if groups will share environments. If the testing is not complex and can be done on a single environment using other techniques (such as account ranges) to separate testing activities on a single environment. Try to determine end dates of testing activities and see if environments can be reused when they are to be retired. This may save time. Only give distinct test environments where testing cannot be shared for any reason or the activity needs to be separated as it involves external parties (such as market testing) or different types of testing (e.g. online performance testing against interface testing is not a good share).
Typically, conversion environments can provide a pre-go-live copy of production transaction and master data that is handy for testing Customer Care And Billing. Conversion environments are typically sources of this data migrated by ConfigLab.
Conversion environments and the use of ConfigLab
If the conversion toolkit is used on your implementation, then the conversion environments need to be considered as part of the ConfigLab solution. Conversion environments participate in ConfigLab solutions in the following ways: Conversion environments need to receive meta-data and configuration data from the Control environments. Typically you might want to consider synchronize jobs to override conversion control data rather than Compares. Conversion environments may want to distribute subsets of converted data from practice conversions for various activities including user acceptance testing and interface testing. This is another way to verify the system that has been successfully used at other sites. In this case you could consider setting the conversion environment up as a supporting environment to provide a source of data that can be pulled into downstream supported environments.
Step 1.2: Decide the relationships between the environments
Once the environments have been decided, the next step is to determine what relationships between environments are needed to migrate data across.
Once the number of environments has been decided for your implementation the next step in coming up with a ConfigLab is to decide the relationships between the environments. The relationship between two environments represents that you are exchanging data between these environments. The relationship should also signify the direction of the data flow. If the flow is bidirectional between the environments then use two separate lines, one for each direction. The following guidelines can assist in decision process: Consider each environment in turn and define the relations from that environment to other environments. Consider the implied or explicit hierarchy of the environments in relation to the project plan when considering relationships. For example, it may be useful to migrate data from System Test to User Acceptance Test if that is
Page 16
appropriate, as User Acceptance Test activities exist later than System Test activities in your plan. If an environment can alter data in an uncontrolled way or not ideal for other environments, do not consider it as a good relationship as source of any data. Many implementations choose to migrate meta-data and configuration data solely from the Control environment as it is more controlled than other environments. For example, if a configuration is altered as a part of a "what if" test then the data may not be eligible to be migrated to other environments. This must be considered when deciding relationships.
Sample Implementation Relationships
For Hartwell Energy the requirements outlined in "Sample implementation" the relationships between the environments are as follows: Development Release We assume that technically it is possible to link the two environments. This transfer will enable meta-data generated, from the development platform, to be transported for release purposes to the release environment. Typically this is not done but in this case we will assume it is all possible and practical. Release Control - After applying the meta-data from the development to the Release environment it needs to be migrated. Under this arrangement it will be possible to track changes to the Control environment and prevent corruption of the Control data. Control System Test The Control configuration and meta-data needs to be migrated to system tests to support the testing activities. System Test User Acceptance Test The configuration and meta data needs to be migrated to user Acceptance Test to support testing activities. We are assuming that the system test configuration and meta-data has not been tampered with (or at least any changes have been reflected back in the Control environment). This approach is handy if you want to verify configuration data as part of the system testing activities, otherwise it may be more useful to migrate from the Control User Acceptance Test. For the purposes of this solution we will assume that configuration and meta-data is to be migrated from System Test to User Acceptance Test as System Test will partially verify the "appropriateness" of the configuration and meta-data. User Acceptance Test Production Once User Acceptance Testing, including verification of the configuration and meta-data, has been completed the current configuration and meta-data is migrated to Production. Production Playpen As part of training, pre-production and post production activities a subset of Production data and all the configuration and meta data is migrated to a playpen. This is useful for training and post training "play" for end users. You might need to manipulate Production transaction data to address privacy concerns. We will discuss this later under "Consideration of Privacy".
Page 17
Production Maintenance Once Production has started problems may be need to be investigated on a subset of production. Configuration, meta-data and transaction data may be needed to be migrated. The diagram below illustrates the above relationships.
Hartwell Energy Relationships
Env Id: 908444 Env Id: 908444
Env Id: 889653 Env Id: 889653

Env Id: 701799 Env Id: 701799

Env Id: 196503 Env Id: 196503
Env Id: 619100 Env Id: 619100
Env Id: 568570 Env Id: 568570

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
Once the relationships between environments have been decided, the next step is to determine what environment will initiate the migration and contain the definitions of the migrations for each relationship.
Step 1.3: Decide the Supporting/Supported Environments
Once the environments have been decided and the relationships have been decided the significance of each environment in each relationship is to be decided. This basically means you need to decide which the "Supporting" is and which is the "Supported" environment for each of the relationships. Environments support other environments in an implementation. For example, test environments are "Supporting" the Production environment. When deciding the "Supported" and "Supporting" environments in each relationship consider the following guidelines: Consider the lifecycle or hierarchy of the environment. "Higher" environments (also known as "later" environments) in the value chain tend to be "Supported" environments to "lower" environments (also known as "earlier" environments). This is not always the case (this will be discussed later) but is a generally accepted rule. All migrations are initiated from the "Supported" environment perspective. If you want to control the migration from a certain environments perspective then it should be the "Supported" environment in the relationship. Production should ALWAYS be a "Supported" environment as it is desirable to control Production access from Production only.
Page 18
If approval of any changes is required as part of the migration the target in a relationship must be the "Supported" environment.
Sample Implementation Supported/Supporting
For Hartwell Energy the requirements outlined in "Sample implementation" the significance of the environments in each relationship are as follows: Development Release They want the Release environment to control migrations so it is the "Supported" environment in this relationship. This basically leaves the developer to populate the data and inform the Hartwell it is ready to migrate. Release Control Approvals of any changes in the Control environment are mandatory as only members of that environment can accept changes. Therefore the Control environment is the "Supported" environment in this relationship. Control System Test The requirements state that the owners of the test environments want approval of all changes so therefore the System Test environment must be the "Supported" environment. System Test User Acceptance Test The requirements state that the owners of the test environments want approval of all changes so therefore the User Acceptance Test environment must be the "Supported" environment. User Acceptance Test Production Production is always the "Supported Environment". Production Maintenance Production is always the "Supported Environment". Production Playpen - Production is always the "Supported Environment". The diagram below illustrates the above.
Hartwell Energy Supported/Supporting
Supported
Supporting
Env Id: 908444 Env Id: 908444 Supporting
Env Id: 889653 Env Id: 889653 Supported
Supporting

Env Id: 701799 Env Id: 701799

Supported Supporting Supported
Supported
Supporting Supporting Supporting
Env Id: 568570 Env Id: 568570

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
Page 19
Step 1.4: Decide the role of the supporting environment

Once the supported environment has been decided for each relationship, the next step is to determine the direction of the migration (i.e. push or pull).
One the relationships and the Supported/Supporting environments have been decided the role of the Supporting environment to the Supported environment needs to be agreed to define the direction of the data flow. The following types of roles are available in ConfigLab: Compare Source Data is pulled from the "Supporting" environment to the "Supported" environment. Approval/rejection of individual changes, as viewed by the Root Object/Data Differences Query, is required for compare source before applying the changes.
ENV1 ENV1
Supporting Compare (Pull)
ENV2 ENV2
Supported
Synchronize Target Data is pushed to the "Supporting" environment from the "Supported" environment. No approval is performed as the data changes overwrite the data in "Supporting" environment.
ENV1 ENV1
Supporting Synchronize (Push)
ENV2 ENV2
Supported
Note: The Synchronize functionality will be deprecated in a future release. ConfigLab Data is pushed to the "Supporting" environment from the "Supported" environment and data can pulled from the "Supporting" environment to the "Supported" environment. Approval of changes into the "Supported" is required. Consider the ConfigLab role to a combination "Compare Source" and "Synchronize" role with some extra facilities (See "ConfigLab Role Considerations" for a detailed discussion of the merits and dangers associated with the ConfigLab role).
ConfigLab (Push/Pull)
ENV1 ENV1
Supporting
ENV2 ENV2
Supported
For each relationship you must decide the role for the relationship using the following guidelines: For transfers from the "Supporting" environment to the "Supported" environment the role is Compare Source. For transfers to the "Supporting" environment from the "Supported" environment the role is Synchronization.
Page 20
For transfers to and from the "Supporting"/"Supported" environments the role is a ConfigLab. If approval or a record of all changes is required to be kept in the "target" environment then consider the Compare Source or ConfigLab role only. If the approval or record keeping is critical and you may need to switch the "Supported" and "Supporting" environments in the relationship to achieve this. Do not get "hung up" on the words "Supporting" and "Supported", they are just tags. You may need to change them to suit your needs. If no approval is required AND no record of changes is required then consider the Synchronize role as it basically allows overwriting of the "Supporting" environment from the "Supported" environment. This role is useful for extracts of Production on various environments.
Sample Implementation Roles
According to the requirements, environment owners want approvals to be performed before committing changes so then the Compare Source role is to be used universally except for the following: Production Playpen - As Production is always the "Supported" environment, it is logical that extracts from Production are pushed to the Playpen on a regular basis to serve as a post training "play" area. Production Maintenance - As Production is always the "Supported" environment, it is logical that extracts of problem accounts or data to investigate from Production are pushed to the Maintenance on a regular basis to problem solve. The diagram below illustrates the above roles outlined.
Hartwell Energy Roles
Supported
Supporting
Env Id: 908444 Env Id: 908444

Compare Source

Compare Source
Supporting
Compare Source
Supporting
Compare Source

Env Id: 701799 Env Id: 701799

Synchronize Compare Source
Synchronize
Supported
Env Id: 568570 Env Id: 568570

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
Page 21
Warning about the ConfigLab Role

While the ConfigLab role seems to be reasonable, it has some hidden dangers that should be considered before use.
One of the areas of contention is the use of the ConfigLab role in implementations. It has a few advantages that may be useful in your implementation: Data can be transported between both environments on a regular basis. It may be useful that if you make a change in System Test to configuration as a result of a test to be able to migrate that back to Control. Only one link is required between each environment. If you wanted to use a Synchronize AND Compare Source role on the relationship then you would technically need two links. So why not use it for your implementation? Well, you can BUT it can have disadvantages that may not be appropriate for your implementation such as: The keys in the environments are shared (known as the "key space") so adding a new record in the "Supporting" environment requires a check on the "Supported" environment when allocating keys. This can be a performance hit on the "Supporting" and "Supported" environment. The environments are now physically coupled. That means the "Supported" environment dictates the availability of the "Supporting" environment. Physically it is now possible to update the "Supported" environment from the "Supporting" environment. The above two issues are exacerbated if the environments are "daisy-chained" using the ConfigLab role. For example if a number of environments are "daisy-chained" together (see "Design Patterns" for a discussion of this pattern), each environment will check all the other environments when adding a record (a potential performance disaster) and also all environments will be coupled together meaning that environments later in the "daisy chain" must be up for a particular environment to be useable. These are more than likely undesirable conditions. Note: It is HIGHLY recommended that no ConfigLab roles be used with Production as this allows other environments to access Production and may allow updating of Production from other environments. For example while it is acceptable to pull configuration data back into product it is NOT recommended that accounts be pulled back into Production. This is not a technical issue more of a principle where Production TRANSACTION data is not altered anywhere for Production use except in Production itself.
When planning a ConfigLab solution, a number of common design patterns emerge.
Design Patterns
The design outlined in the sample implementation is only one possible solution. Most ConfigLab solution designs follow a set of common design patterns such as: Daisy Chain (a.k.a. "Waterfall") Each environment is linked in a "chain" according to the lifecycle of the implementation. This means that data is verified and transferred to the next environment for further levels
Page 22
of verification. This is handy for implementations where environments and groups have distinct responsibilities and the chain of events for the implementation is clear. Typically the use of Compare Source roles are used between environments as data transfers either require approval and/or records kept of all changes is required. This is also used where configuration and meta-data is NOT altered in any environment but simply used for testing purposes. Any changes to this data must be fed back through the Control environment and re-migrated. The only downside to this pattern is where the solution uses the ConfigLab role rather than the Compare Source role as the environments become hard coupled and the availability or unavailability of another environment can adversely affect other environments. Hub And Spoke This pattern is where the implementation wants to transfer configuration data from the Control environment to other environments exclusively. This sounds counter productive but if the other environments allow alteration to the configuration data as part of their activities it may cause problems in later environments. In this pattern, the configuration and meta-data are kept "pure" and can be restored other environments as necessary. This pattern is useful for implementations where there is overlap in activities or unclear activities as one test environment does not depend on other environments. As per the Daisy Chain pattern, the use of Compare Source roles is common but one variation on this is that it is possible to push data using a Synchronize process from Control to the other environments. This variation is useful where no approval or record of changes is required. Hybrid Of course there is a possibility that you can combine the above patterns into many variations depending on your needs and verification requirements. The below diagram illustrates the above patterns.
Page 23
Development Development
Release Release
Control Control
System Test System Test
Acceptance Acceptance
Production Production
Daisy Chain or Waterfall Pattern
System Test System Test Development Development Release Release Control Control Production Production
Hub And Spoke Pattern
System Test System Test Development Development Release Release Control Control
Production Production
Hybrid Pattern
Once an environment setup has been agreed, the next step is to register all "Supporting" environments in the relevant "Supported" environments.
Step 1.5: Register the Environments
Now that the ConfigLab solution has been designed it is important to register the environments for use with ConfigLab. This is essentially a technical process performed by the DBA's for your implementation but this section outlines the information that needs to be provided to your DBA's and a some advice for your DBA's on how to implement it.
Database links (ORACLE)
On ORACLE platforms, before registering a "supporting" environment in a "supported" environment your site DBA must create database links for ConfigLab to use.
Note: Since ConfigLab requires the use Database Links (even within the same database) then the Database MUST use the TNS listener not IPC communications (a.k.a. BEQUEATH). Attempting to use IPC will result in failure of the ConfigLab processes. For ORACLE implementation the site DBA's must create database links between the "Supporting" environment and the "Supported" environment within the "Supported" environment. The table below summarizes the Database links to be created: Relationship Type Compare Source Sync Target ConfigLab Link in Supported Database Supported Userid Supporting Userid CISUSER CISREAD CISUSER CISUSER CISUSER CISUSER Link in Supporting Database Supporting Userid Supported Userid Not Applicable Not Applicable CISUSER CISUSER
Page 24
The owner of the DB Link should be CISUSER. The DB Link name should not contain "_". Note: CISUSER needs CREATE DATABASE LINK and CREATE PUBLIC DATABASE LINK permission. Note: CISUSER and CISREAD are the default product database users. The values may vary at your site. For publishing purposes the default values will be used. The name of the database link should reflect your site standards. If you do not have a standard then the database name or $SPLENVIRON (%SPLENVIRON% for Windows) of the "Supporting"/"Supported" should be considered. The following SQL (or similar) may be used to create the database links: CREATE DATABASE LINK <dblinkname> CONNECT TO <user> IDENTIFIED BY <password> USING '<supporting db>'; CREATE DATABASE LINK <dblinkname> CONNECT TO <user> IDENTIFIED BY <password> USING '<supported db>'; Where
<dblinkname> <supporting db> <supported db> <userid> <password>
Name of the database link Database name of the "Supporting" environment Database name of the "Supporting" environment Userid connected in the database link Password for the userid connected in the database link
Note: If at any time the passwords for ANY of the Customer Care And Billing/Enterprise Taxation Management users are changed then these database links will need to be dropped and recreated.
In the database installation directories there is a utility that can perform the registration process.
The Registration utility: EnvSetup.exe
Once database links have been created the following steps can be executed to complete the registration process: You need to decide on a prefix for each relationship in the "Supported" environment. The prefix is an alphabetic character (other than 'C', 'F' or 'S') that is unique to that environment. If possible try not to reuse the prefix in other environments (just in case you change your ConfigLab setup in the future). Note: 'C', 'F' and 'S' are prefixes already used by the base product. With the use of numbers as prefixes, there is a potential to have 33 supporting environments per supported environment.
Page 25
For each "Supported" environment the links need to be named and role provided to the DBA to use in the registration. This is used for an Environment Reference on the "Supported" environment. It should be obvious so that when the ConfigLab processes are run there will be no mistakes. If you do not have a local standard the following alternatives are suggested: Name Example SYSTEST Comments Name of Supporting environment (SPLENVIRON environment variable) Name of relationship with "Supported" environment and "Supporting" environment Ids (SPLENVIRON environment variable). Name of relationship with "Supported" environment id (SPLENVIRON environment variable). "Supporting" environment Ids (SPLENVIRON environment variable) and role (CS Compare Source, SY Synchronize, CL ConfigLab).
<Supporting>
<Supported><Supporting>
CONTROL-SYSTEST
<Supported><Supporting> -<role>
CONTROLSYSTEST-CS
The latter is useful if you have a number of links between the same environments. You will need to note down the userids and passwords for the supporting and supported environments: The product schema owner (typically CISADM). The read-write userid used by the product (typically CISUSER). The read-only userid used by the product (typically CISREAD). This is not used for DB2/UDB and SQL Server sites.
Page 26
The system administration userid and password (typically SYSTEM). Your site DBA will know this. Typically they will NOT divulge this information as it is like "giving the keys away". Ensure that both the supporting environment and supported environment are identical in the following circumstances prior to registration or reregistration: The release of Customer Care And Billing and Framework as expressed in RELEASE_ID/BUILD_NBR/PATCH_NBR on the Installation Record (CI_INSTALL_PROD) must be identical across the supported and supporting environments. This includes implementation of any rollup that changes this value. The Customization release as expressed in RELEASE_ID/BUILD_NBR/PATCH_NBR on the Installation Record (CI_INSTALL_PROD) must be identical across supported and supporting environments. The character set used by the supported and supporting environments must be identical. Note: These settings are only checked at environment registration/re-registration time. Ensure that the windows machine you executing the utility has the appropriate database client installed and can access both environments natively Refer to "How To Register a ConfigLab Environment" in Chapter 81 Configuration Lab documentation for details of the EnvSetup.exe command.
If a change in the base product or customization introduces a database change then the environments must be reregistered to reflect that change in ConfigLab.
When do I Re-register the environment?
When an environment is registered during the configuration of the ConfigLab utility it is necessary to re-register the environment under the following conditions: If an upgrade is performed on the Product where there any table changes. This includes any single fix, rollup (service pack/patchset) and upgrade to the product. If a customization release includes any table changes.
This is important to guarantee data integrity as part of the migration. Failure to reregister the environment may result in inconsistent behavior from ConfigLab.
Page 27
Automating the registration process

One of the best practices in the registration process is that a command file be built containing all the EnvSetup.exe commands for your site. This file can be used to quickly reregister environments during an upgrade.
It is possible to automate the registration process by creating a DOS batch command. This will save time in reregistering the environments after each upgrade. Refer to the sample batch file oracle-compare-source.bat located in the "Configuration Lab" subdirectory on the database component of the installation. Note: Before each execution of EnvSetup.exe is performed it will ask you to confirm the settings. Press Y to confirm. Note: Remember to include the u parameter when using EnvSetup.exe as it will run the commands against the database. Excluding the u parameter generates the log files and verifies the input parameters only, it does not execute the commands. After the environment setup has been completed it can be verified using the following techniques: Use the Environment Reference query on the "Supported" environment. The "Supporting" environments should be defined there. Check view for views that are owned by CISUSER (or equivalent) are prefixed by the prefix that was set for the link rather than the base "C", "F" or "S".
After registration has been complete, the next step is to decide "what" to migrate.
PHASE 2: DECIDING WHAT TO TRANSFER (THE "WHAT)
Given that the environment setup has been complete the next set of steps are designed to help design WHAT to transfer in the form of DB Processes.
What are DB Processes?
DB Processes instruct the ConfigLab what to migrate, in what order and what filters and manipulations to apply.
One of the main features of ConfigLab is the ability to copy data from environment to environment while maintaining data integrity. To maintain data integrity ConfigLab must understand the data structures and the relationships between data items to ensure data and related data is copied correctly. This information is stored within the product in a number of locations: Tables/Fields There are meta-data tables within the product that hold a definition of each table and the fields. All the base tables and fields are documented there for use for auditing, development suite, XAI, ConfigLab and AppViewer. Tables and Views may be maintained using the Development Suite or using the maintenance screens using the product BUI. If you have any custom tables then they will be defined there as well. Maintenance Objects Groups of related tables and the nature of their relationship are contained in Maintenance Objects. Think of Maintenance Objects as defining the "objects" in the system that is used by the maintenance pages in the system (also the XAI Incoming Services). The
Page 28
base set of Maintenance objects are supplied with the product. You may add your own Maintenance object for any custom tables if necessary. The above meta-data defines the data and their relationships, the next step is to group Maintenance Objects (that are related and not related) into logical groups so that migrations can occur. Such groupings of Maintenance Objects are known as DB (Database) Processes. DB Processes define the group of Maintenance Objects, their relationship to each other (if there is a relationship) and any filters or rules to identify the subset of data to transfer. The type of DB Process is dictated by the type of role the "Supporting" environment has. In other words there are Synchronize (Push) DB Processes and Compare (Pull) DB Processes for Synchronize and Compare Source roles respectively. The distinction between the two types of DB Processes is to do with the execution of the DB Process within ConfigLab. This will be discussed later.
The demonstration database supplies a number of predefined DB process that can be used at your site as-is or customized.
Base Supplied DB Processes
Below is a table of base supplied DB Processes for use in your implementation: DB Process CI_COCNT CI_COCTS Description Compare Control Data Sync control table data Comment This is a commonly used DB process. This is similar to CI_SYCNT but is also a synchronize version of CI_COCNT. This is a compare version of CI_SYACT. Typically "One off" to populate blanks database Typically "One off" to populate blanks database Typically "One off" to populate blanks database Typically "One off" to populate blanks database Typically "One off" to populate blanks database Typically "One off" to populate blanks database This may be used if reporting is used
CI_COPAC CI_COPAD CI_COPAP CI_COPBI CI_COPD1 CI_COPIN CI_COPPY CI_COPRP
Copy accounts Compare Adjustment FT Algorithms Compare Automatic Payment Algorithms Compare Algorithms Compare Algorithms DOC Billing 1
Compare Installation Record's Algorithms Compare Algorithms Compare Definitions Payment Report
Page 29
DB Process CI_COPRS CI_COPSC CI_COPUG CI_COPWF CI_SYACT CI_SYCNT
Description Compare Rate Schedules Compare Scripts Copy user groups Copy workflow process templates Synchronize Data Account
Comment This will be used to transport rate changes only. This may be used if BPA is used This is used to copy security definitions. This is used if Workflows are used. This will be used for extracts from Production This will be used for extracts from Production
Synchronize Control Data
In most cases you will use the base processes for the majority of your work but you want to customize them to suit your installation. Refer to "Guidelines for Custom Maintenance Objects" for more information in this area.
If your site has custom tables, they need to be defined in the meta-data to be included in a ConfigLab setup.
Step 2.1: Review Custom Tables and Fields (Optional)
Note: If your site does NOT have any custom tables or the custom tables you have, are NOT to be migrated using ConfigLab skip this section. During the development process the Oracle Utilities Software Development Kit allows the developers to define custom tables and fields to the product meta-data tables to allow custom code to be generated for maintenance of that data. This information is used for screen definitions and related code generation by the tools within the SDK. Typically this information is maintained by the Developers and transferred to the site as part of the initial code installation (and subsequent deliveries) using a tool called OraSDBp.exe under the DB_packaging directory. This tool basically generates SQL INSERT, UPDATE and DELETE statements against the metatables (as defined in extract_cmsystbls.lst) to maintain the necessary meta-data (including Tables and Fields) for your customizations. To maintain or view that information you can use the following methods: Use the Table and/or Field maintenance page from the product BUI from the Administration T Table menu item. If documentation in the AppViewer is generated for the implementation by the Oracle Utilities Software Development Kit, the appViewer can display this information after running the appViewer F1-AVTBL background process.
Page 30
Documentation on how to maintain the Tables and Fields in the product is contained in the Utilities Guide - Chapter 01.
If your site has custom tables, they may be defined to be included in a custom Maintenance object so that they can be included in a custom DB process for ConfigLab to use.
Step 2.2: Review Custom Maintenance Objects (Optional)
Note: If your site does NOT have any custom tables or the custom tables you have, are NOT to be migrated using ConfigLab skip this section. During the development process the developers may populate the custom Maintenance objects used for the custom tables and fields. This is an optional activity and must be requested of the developers. Typically this information is maintained by the Developers and transferred to the site as part of the initial code installation (and subsequent deliveries) using a tool called OraSDBp.exe under the DB_packaging directory. This tool basically generates SQL INSERT, UPDATE and DELETE statements against the metadata tables (as defined in extract_cmsystbls.lst) to maintain the necessary meta-data (including Maintenance Objects) for your customizations. To maintain or view that information you can use the following methods: Use the Maintenance Object maintenance page from the product browser interface from the Administration Maintenance Object menu item. If documentation in the appViewer is generated for the implementation by the Oracle Utilities Software Development Kit, the appViewer can display this information after running the F1-AVMO background process. Documentation on how to maintain the Maintenance Objects in Customer Care And Billing is contained in the Utilities Guide - Chapter 81 ConfigLab.
If you create custom Maintenance Objects, ensure that they are setup so that the upgrade process can retain them.
Guidelines for Custom Maintenance Objects
It is possible to create custom maintenance objects outside the development kit using the maintenance function available from the Utilities menu. If this is performed consider the following: Name the Maintenance Object so that it is representative of the data it contains. Look at the base provided Maintenance Objects for guidance. Do not include any base tables in your Maintenance Object. Relationships between custom objects and base objects are defined in the DB Processes. Use any custom maintenance screen as a guidance of what the Maintenance Object should contain. For example, tabs on a page typically are additional tables. Do not forget the language tables (i.e. tables suffixed with "_L").
Page 31
Step 2.3: Setup and Maintain DB Processes

To define what to copy specifically for your site, you should create custom DB processes.
To define WHAT data needs to be transferred using ConfigLab is about setting up the set of DB Processes that define the collection of Maintenance Objects (and related tables), filters and type of transfer for your site. When designing your DB Processes consider the following: Name the DB Process to reflect the contents of the DB process. Remember to prefix any custom DB Processes with CM to avoid overwriting during upgrades. You might want to use the CO or SY additional prefix (see the base DB Processes for examples of this) to distinguish between Compares and Synchronizes. Remember to add the Batch Control record FIRST before adding the DB Process. Ensure all the relationships are covered in the DB Process between Maintenance Objects. The Sequence field dictates the sequence of the processing. You can use this to your advantage. You can make the more important maintenance objects (for your implementation) become copied early. A set of Product supplied DB process are listed in "Base DB Processes". These assume worst case scenarios, therefore include all the maintenance objects that could possibly be needed within each migration. These will need to be customized to suit your sites needs, as the defaults will not be optimal. As a minimum you might want to filter custom data from base provided data to minimize run times. Additionally the following DB processes may need to be setup to perform other common migrations: Meta Data Migrations - Meta data for the customization may wish to be migrated. Security Definitions - Consider adding User Group and other maintenance objects to migrate. For example:
XAI Migrations - The configuration of XAI may need to be migrated.
Page 32
If you manipulate any of the base provided DB Process you must copy them first and prefix the copy with CM. For example a copy of CI_SYACT and CI_COCNT could be CM_SYACT and CI_COCNT. This is due to the fact that during an upgrade you may find that CI_SYACT or CI_COCNT has been changed. You will have to manually reflect any changes in the base DB processes in any customized copied DB processes. Remember DB Processes need to be defined in your "Supported" environments. You could include that information in a control Data migration or create a DB Process migrate job to migrate DB Processes. Typically Control environments will need to be migrated. Review CI_SYACT and CI_COCNT, take a copy of it and remove the control data maintenance objects you do not use in your implementation. You may want to also add Table Rules to the primary objects to subset the necessary data to reduce the run times. Use "Synchronize" processes for migrations unless approval is necessary (then use "Compare" Processes). Note: Synchronize processes will be deprecated in a future release of Customer Care And Billing. Consider placing your sites DB Processes in the Control environment so that they are migrated to other environments as well. This means you will have a set that you can reuse. Remember the more data you migrate the longer it takes. Filter as much as practical. Table rules should be restricted to the primary table in a maintenance object and the table name must prefix each field in the WHERE clause. Each Table in the SQL MUST be prefixed by '#'. Aliases may be used but must not be reserved words. If the filter is complex use a criteria algorithm. While this sounds like work in the long term it will benefit migrations. Table Rules MUST result in valid SQL statements. Check your SQL in "Show SQL". Test your Table rules by copying the contents of the "Show SQL" into SQL*Plus and see if it has the desired results. An example is shown below:
Page 33
When copying data from production, you might need to hide critical private information according to privacy laws of your country.
Consideration of Privacy
One of the concerns of implementations is privacy. Most governments have privacy laws that basically restrict the use of live Production data for nonProduction use (for example testing). The law is to protect customers information from being wrongfully used or distributed. The privacy laws of most countries deals with both demographical and identification information that must be protected. Note: The extent data is protected is up to the policies of the individual client and the local laws of the jurisdiction in which the client resides or does business. Typically the following information needs to be protected: Names (including Aliases) Addresses (ALL Addresses) Identifiers such as Social Security Numbers, Drivers Licenses, Security Questions Credit ratings, Credit Cards etc. Web Self Service Questions and passwords. Other identifiers such as Account numbers may be affected but addressing the above usually removes the need for other changes. Note: For Oracle Utilities Customer Care And Billing/Enterprise Taxation Management V2.1, Server Side scripts can be used to manipulate data. To achieve this, a processing Algorithm needs to be created that will somehow alter the above data so that it is not recognizable as the original. A sample one for Social Security is provided in the base package that can be used as a basis for any other algorithm. Common techniques to alter the data include: Jumbling text strings or characters.
Page 34
Substitution from a Control list of data (this is a technique that has been used in benchmarks to generate test data). The technique used will vary according to your sites needs, privacy laws and the actual needs of the non-production environment where you need the data.
Once the environment registration and configuration of ConfigLab is completed, the last steps are to execute the migrations.
PHASE 3: EXECUTING CONFIGLAB
Once the Environments have been registered, DB Processes have been setup in Batch Control and DB Process maintenance screen it is now possible to perform migrations. This section outlines the job flow as well the common methods of execution of the processes.
ConfigLab Operations
When ConfigLab executes, it creates root objects and uses the synchronize engine to recognize differences in the root objects and act accordingly.
Before discussing how to submit ConfigLab jobs, it is important to understand what ConfigLab does internally in a Compare and Synchronize DB Processes. In summary form ConfigLab does the following: The background processes use the DB Links defined via the Environment Reference passed as a parameter in the process to compare the Primary Maintenance Objects in the DB Process across the two environments. When it finds a difference (or it is candidate for further scrutiny), it registers that difference as a Primary Root Object. This information is stored in the Root Object tables. If filters (table rules) and algorithms are specified they are applied to determine whether the record should be migrated or not. This is known as "Creating Primary Root Objects". This is performed for both Compares and Synchronize. For each Primary Root Object, the associated Child Maintenance objects are compared to see if any data difference is detected. If there is a change then the Child Maintenance Object is registered as a Child Root Object. This information is stored in the Root Object tables. If filters (table rules) and algorithms are specified they are applied to determine whether the record should be migrated or not. This is known as "Creating Child Root Objects". This is performed for both Compares and Synchronize. For each change (Primary and Child) the system examines the rows field by field and determines the recommended action on the record (INSERT, UPDATE or DELETE) depending on the change, existence or nonexistence of the data. This is known as "Assigning Root Actions". This is performed for both Compares and Synchronize. For Synchronizes, the data difference is resolved according to the root actions on the Primary and/or Child Root Objects. After this is done the Root Objects are removed from the system. This means no record of the change is kept and there Synchronizes should be considered "overwrites". This is known as "Resolving Data Differences".
Page 35
For Compares, there is a manual process involved as individual changes need to be approved or rejected using the Data Difference Query by the owners (or their delegates). It is possible to default the Approve or Reject action using the parameters on the Background Process for INSERT, DELETE and/or UPDATE actions. Once the Data Differences are approved then the "Apply Changes" process (CL-APPCH) must be executed to reflect the approved changes. The Approved Data Differences are updated with Complete and retained for future reference. Therefore, to complete the Synchronize process you must execute one DB Process but for the Compare Process you must run two (the Compare Process itself and the Apply Changes after the manual approval/reject stage). The diagram below illustrates the differences between the Synchronize and Compare processes:
Synchronize Create Primary Create Primary Root Objects Root Objects Create Child Create Child Root Objects Root Objects Assign Root Assign Root Actions Actions Resolve Resolve Differences Differences
Compare Create Primary Create Primary Root Objects Root Objects Create Child Create Child Root Objects Root Objects Assign Root Assign Root Actions Actions Approval Approval Process Process
Apply Changes Apply Apply Changes Changes
To run ConfigLab, a number of batch processes are run using the preferred method used on site.
Step 3.1: Execute ConfigLab Jobs
The first part of the execution process is to submit the ConfigLab background processes registered with the batch controls. Submission of the background process is as per any other background process within the product.
Compare Source submission
To execute a compare source, you must execute the batch control attached to the compare DB process with the source environment code and default approval statuses as parameters.
For the Compare Source processes, submit the Compare DB process using the relevant batch control, setup in the previous steps, from the Supported environment specifying the following parameters: Parameter ENV-CODE STATUS-ON-ADD Comment Supporting Environment Reference to pull the data from. The default status to assign any changes that are additions to the Supported environment. Valid values are: APP Approved (default) REJ - Rejected
Page 36
Parameter STATUS-ON-CHANGE
Comment The default status to assign any changes that are changes to the Supported environment. Valid values are: APP Approved (default) REJ Rejected
STATUS-ON-DELETE
The default status to assign any changes that are deletions to the Supported environment. Valid values are: APP Approved (default) REJ - Rejected
MAX-ERRORS
The number of objects that need to fail before the job is considered a failure. A value of zero (0), which is the default, disables this feature.
Note: STATUS-ON-ADD, STATUS-ON-CHANGE and STATUS-ON-DELETE can be overridden on individual changes during the Approval process. The screen below illustrates the online submission parameters for Compare Source processes:
To execute a synchronize target, you must execute the batch control attached to the synchronize DB process with the source environment code as a parameter.
Synchronize submission
For the Synchronize processes, submit the Synchronize DB process using the relevant batch control, setup in the previous steps, from the Supported environment specifying the following parameters: Parameter ENV-CODE MAX-ERRORS Comment Supporting Environment Reference to push the data to. The number of objects that need to fail before the job is considered a failure. A value of zero (0), which is the default, disables this feature.
Page 37
The screen below illustrates the online submission parameters for Synchronize Target processes:
A valid technique is to create a batch control per migration and place the defaults on the batch control.
Defaulting parameters on Batch Controls
One of the features of the product is the ability to specify defaults on the Batch Control so that the online submission can pre-fill parameters. If you want to enforce specific policies on specific jobs through setting parameters than you should alter the Batch Control for the Compare and Synchronize processes and specify the relevant parameter values. This may also save time in submission.
Step 3.2 Approval Process
Users of the Compare Source process can manually approve or reject object changes. Customer Care And Billing/Enterprise Taxation Management provides a number of screens to assist in the decision process.
Note: This step is not applicable to a Synchronize Target process. Once the Compare Source process has completed the next step is to manually review the changes and approve or reject changes appropriately. This step is optional as the status of the changes is defaulted as specified by the parameters on the execution of the Compare background process. It is possible to review and change the status of an individual change using navigating within the Customer Care And Billing/Enterprise Taxation Management user interface to the Administration D Data Differences query. The parameters for this query are the Batch Control used to run the Compare process and the Run number (you will be presented a list of past runs on entering the query). For example:
The top level of the query outlines the following: Maintenance Objects of records that have been identified as changes. The nature of the change (Add, Change or Delete). Note: If you delete a record from a child table it is listed as a change NOT a delete. The current status of the change (Approved or Rejected). If another status is displayed such as Pending or Error then the record is in progress of being applied or has been rejected.
Page 38
The number of root objects that have that status, maintenance object and change type. In the example above, there has been one (1) change and two (2) Deletes. To find out more information about the individual changes select the "go to" button ( ) next to the desired row. For example selecting the change row:
The "PK Info" outlines the key that has been identified as the object that has changed. In the above diagram the "SPL" user has been changed. At this level it is possible to "Approve" and "Reject" object changes. Note: It is not possible to "Approve" and "Reject" at lower levels than this. This can cause misconceptions. For example, if two users made a change to the same object then both users changes will be displayed as a "Change" to the object. You cannot separately "Approve" or "Reject" individual users changes. See example below.
Page 39
Most users in the "Approval" process will not venture past the summary level of detail to make the decision whether to apply the change or not. If the user requires further levels to make the decision then selecting the "go to" button ( ) for individual objects to view the root object data and SQL that is to be executed to make the change. The screen samples below illustrate the types of information available at these lower levels:
The above screen is a summary of the root object used for processing. At this point it is possible to also approve the object. The individual data differences are listed by table and change and includes the SQL that is to be executed:
Page 40
As with most of the product, it is possible to view the same data in a tree view to assist in the decision making process for "Approvals" and "Rejections":
After the approval process, the last step is to run a background process to apply all approved changes.
Step 3.3 Apply Changes Process
Note: This step is not applicable to a Synchronize Target process. After the manual approvals and/or rejections have been completed by the relevant parties then submit CL-APPCH with the Batch Control from the previous step with the relevant Supporting Environment Reference. The screen below illustrates the online submission parameters for "Apply Changes" process:
This will apply all "Approved" changes from that Batch Control/Environment Reference combination and mark completed changes as "Complete". For example:
Make sure you run an "Apply Changes" process prior to running another "Compare" to avoid potential "undesirable" behavior.
Undesirable behavior in Apply Changes
There is a potential for "undesirable behavior" if there is an "inappropriate" timing of the Compare/Approval/Apply Changes process. The "Apply Change" process applies all Approved Changes for a Batch Control/Environment Reference combination. There is no Batch Number in the parameters. This means that if an
Page 41
"Apply Changes" process is not run before another "Compare" Process is started, you might find inappropriate "Approved" or "Rejected" changes processed. For example, if a change is approved in one "Approval" process and "Rejected" in another "Approval" process, and no intervening "Apply Changes" has been run then, the eventual "Apply Changes" Process that is run will apply the change. The diagram below illustrates this point with two "Compares" of the same type executed against the same Environment Reference, but only one "Apply Change" executed.
Compare Compare
Time
Approval Approval
Compare Compare
Apply Apply Changes Changes
Time
Approval Approval
In this example, the "Apply Changes" will apply any "Approved" changes from both Compares. This may be undesirable behavior. The correct mode of operation is to execute the "Apply Changes" process prior to another "Compare" executing. The diagram below illustrates this practice.
Compare Compare Apply Apply Changes Changes
Time
Approval Approval
Compare Compare
Apply Apply Changes Changes
Time
Approval Approval
The above practice ensures the changes from each corresponding "Compare" are applied as intended. Best practice is to keep the Approval process as short as practical to avoid problems.
When you reject a change to an object, it will reappear in subsequent compare processes until it is approved and applied.
Carried over changes
Whenever a change is rejected it will continue appear in subsequent executions of the "Compare" process as a change until it is eventually approved and applied. This is called a "carried" over change as it is still detected as a change whenever a "Compare" is executed and the rejected makes it "carry over" to subsequent "Compare" processes.
Page 42
This may seem unintentional behavior but in fact it is desirable as a change can be deferred over any number of compares until the target environment is ready for it. For example, if a rate is tested in configuration but the production environment is not ready for it, then it can be continually rejected (in most cases manually) until the approver is ready for that change.
If a change is marked as "Error", then the change failed a validation or integrity rule in the target environment. The error message will be indicated on the root object.
Errors in Apply Changes
At the time of the Apply Changes processing, the change is validated by the validation objects indicated on the Maintenance object. If the routine indicates the change would contravene some integrity or business rule, the object is placed in "Error" status and the error message attached to the root object. The error message will be the same error message that an online or XAI user would receive if they tried to perform the same action. This is expected behavior from ConfigLab as one of the goals of the utility is to protect data integrity. The presence of "Error" records does not indicate a problem with ConfigLab but will point to one of the following: Related data has not been copied for a reason. This may be contained in another DB process, which has not been run yet. For example, running the compare accounts will not also copy configuration data for those accounts, that is a separate DB process. The change has already been made manually or via another ConfigLab execution. For example, a previous "Apply Changes" made the change but your "Compare" data was "stale". There is some configuration in the target preventing the change. To re-address the problem, after the cause of the problem has been resolved, manually change the status of the root object in the Data Difference query from "Error" to "Approved" to reprocess the change.
If you encounter unexplained conditions in ConfigLab there may be a common cause and solution.
COMMON DESIGN AND EXECUTION PROBLEMS IN CONFIGLAB
Now that ConfigLab has been configured and is executed there may be some perceived issues with its execution. This section outlines common issues and advice on how to resolve them.
Expected data is not copied
If the expected data is not copied then check your filters, incomplete DB processes or for any error records to process.
One of the criticisms with ConfigLab is that it does not copy the expected data fully. ConfigLab will only copy records that have changed according to the specification of the DB processes. To resolve this problem investigate the following: Check for filters Check that none of the Maintenance Objects in your DB process have Table Rules or algorithms that would have excluded the
Page 43
missing data. This is a common mistake. To resolve the problem either alter or remove the filters from the Maintenance objects and rerun. Check for incorrect or incomplete relationships Check that your DB Process is sound by comparing the relationships with the appViewer data for your site. If you miss a relationship then it will not copy all of the related data. Check that all related DB processes are executed Some of the DB processes depend on other DB processes to be run especially the base ones. For example to use the system you not only have to copy the control data but the algorithms for the system to be complete. Check for no "Pending" records If the Root Object statuses after a compare background process has completed are set to "Pending" then the compare process did not finish successfully, even it is indicated as so. The "Pending" status is an internal status used by ConfigLab and should not be seen for a completed process (compares/synchronize process in progress are a different matter). This is usually caused by an incorrect or incomplete DBD and DBI installation in Perl. Verify that the DBD and DBI have been installed within Perl and have been tested, using the scripts provided by the DBD and DBI providers, BEFORE running ConfigLab.
The Installation record is not usually copied by the base DB processes as it contains the Environment identifier.
Installation record not copied
One record that is not in any base DB process is the product Installation record. This can cause issues if you start with a blank database and copy all the algorithms and control data but find the product does not work. The Installation record needs to be manually manipulated as it contains the licensing information and the unique Environment Id assigned at installation time. This is usually a once off exercise.
ConfigLab is running slow
If the ConfigLab background processes are running slow, then it can be remedied a number of ways.
As with any part of a product, the ConfigLab facility can experience performance problems with compares and synchronization. Common areas to consider in resolving this issue are: Regularly analyze the databases in the supporting and supported environments ConfigLab deposits records in its own tables (Root Objects and Data Differences) as well affecting other tables in the database. Maintenance of the statistics on that database will ensure SQL is as efficient as possible. The ConfigLab tables are especially important to analyze regularly, as growth factors for those tables can be large. With Compare Source the results of each execution is recorded in the Root Object and Data Difference objects for reference purposes. These remain there, unless they are archived. Having data stored in those tables that is not used is inefficient and can cause performance process as inputs take longer and the key allocation process for object ids takes longer. If the
Regularly update the statistics of the ConfigLab tables.
Page 44
change information is not needed or the process of manual Approval/Rejection is not required, then it is recommended that Synchronize processes be used instead of Compare Sources. Synchronize only use the Root Object and Data Difference tables as temporary storage and delete the records as part of the process, thus avoiding wasted space. The following tables are candidates for regular "analyzes": Object Root Object Tables CI_ROOT_OBJ CI_ROOT_INSTR CI_ROOT_OBJ_EXC CI_ROOT_OBJ_EXP CI_ROOT_OBJ_PK Data Difference CI_DATA_DIFF CI_DATA_DIFF_PK CI_ROOT_DIFF Note: If the migration is a compare that will potentially have lots of changes then an analyze BETWEEN the compare background process and the apply background process may be required.
Regularly archive/purge data not needed in the ConfigLab tables.
The existing records in the Data Difference and Root Object tables in each Supported environment needs to be archived on a regular basis. The following process should be used: The criteria for archiving needs to be decided. The options available are to archive by DB Process ID, Environment Reference (source of data), Maintenance Object, Batch Code, Batch Number and any combination of these. The Table rule on the CI_ROOT_OBJ Maintenance Object in the CI_PURO DB process, in the Supported Environment, must be altered to reflect that criteria. The base provided table rule is NOT appropriate as it is a sample only. The Archive process for the CI_PURO must be run as follows: The CI_PURO job is executed in the Supported Environment with TEST-MODE = N. The AR-CRCHR job is executed in the Supported Environment with ENV-CODE not specified and DB-PROC-CODE = CI_PURO.
Page 45
The AR-PRFK job is executed in the Supported Environment with ENV-CODE not specified and DB-PROC-CODE = CI_PURO. The AR-DCDT job is executed in the Supported Environment with ENV-CODE not specified and DB-PROC-CODE = CI_PURO.
Regularly check the performance of the DB Links.
If the database links in the registration process span across more than one machine then examine network links between the machines. Compares and synchronizations across machines will be slower than within a single machine but a badly performing network link can make the task even slower. Examine the Maintenance objects in the DB processes you are using and only transfer the objects you need. This reduces the job time by reducing the work done by the DB process to what is absolutely required. For example, the CI_COCNT job used for the Compare Source compares and copies EVERY configuration table (all 642 of them) that is used in the system. This level of comparison is rarely needed at any site. To optimize the processing it is generally recommended that the CI_COCNT job be copied (with prefix CM and a new batch code assigned) and the irrelevant maintenance objects removed from the definition. The following table lists the number of tables per Batch Code (as at Oracle Utilities Customer Care And Billing V2.1.0): Batch Code CI_COCNT CI_COCTS CI_COPAC CI_COPAD CI_COPAP CI_COPBI CI_COPD1 CI_COPIN CI_COPPY CI_COPRP CI_COPRS Description Copy control table data Sync control table data Copy accounts Copy the adjustment FT algorithms Copy automatic payment algorithms Copy the billing algorithms Copy the Doc 1 algorithms Copy the installation record's formatting algorithms Copy the payment algorithms Copy report definitions Copy rate schedules Count 642 755 671 4 4 4 4 4 4 21 531
Consider removing any unnecessary maintenance objects.
Page 46
Batch Code CI_COPSC CI_COPUG CI_COPWF CI_SYACT CI_SYCNT
Description Copy scripts Copy user groups Copy workflow process templates Sync accounts Sync control table data
Count 42 6 10 616 756
Note: Once this is done any changes to the base CI_COCNT DB process must be manually reflected in the custom definition (if appropriate).
APPENDICES
The following sections contain "cheat sheets" for common tasks in ConfigLab.
Cheat Sheets
The following sections summarize the key processes to implement specific situations in ConfigLab. They are in a form commonly called "Cheat Sheets" which should not imply that you are cheating but give you a sense of the correct steps.
Cheat Sheet: Setting up a Compare Source relationship
This "cheat sheet" is provided to assist in the setup a Compare Source relationship also known as to "PULL" data from another environment.
To pull data from one environment to another utilizes a compare source relationship defined between the environments. This section will outline how to set up this relationship. To setup a compare source to pull data from ENV1 to ENV2 (as illustrated below) then the following tasks must be performed:
ENV1 ENV1
Supporting Compare (Pull)
ENV2 ENV2
Supported
Ensure that you know the technical details of each environment such as database identifier, system account password, owner of the schema (usually CISADM), user used by Oracle Utilities Customer Care And Billing to access the database for read-write (usually CISUSER) and the read-only user for the database (usually CISREAD). Ensure that the environment identifiers for both environments are different. This can be checked using the following database query on each environment: Select env_id from f1_installation;
Page 47
If they are the same then one of the environments will have to be altered so that ENV_ID is set to another value (see "Tip: Randomly reassigning ENV_IDS" for a technique) and the key tables regenerated (see "Cheat Sheet: Rebuilding key tables"). Create a database link on ENV2 to ENV1 that uses the read-only user (usually CISREAD) from ENV1. As you are PULLING data from ENV1 you only need to read it. Remember to name the database link appropriate to your site standards. See "Database links" for details of the commands. Run the EnvSetup.exe utility to register the environment in the following format: EnvSetup.exe -s
<ENV2db>,<ENV2password>,<ENV2dbowner>,<ENV2dbus er>,<ENV2dbread> -r <ENV1db>,<ENV1password>,<ENV1dbowner>,<ENV1dbus er>,<ENV1dbread> -a I -t CMPS -e <ENVIDENT> -n <PREFIX> -d "<DESC>" -x <DBLINK> -c <DBCHAR> -u o C1 -l <LOG>
Where:
<ENV2db> <ENV2password> <ENV2dbowner> <ENV2dbuser> <ENV2dbread> <ENV1db> <ENV1password> <ENV1dbowner> <ENV1dbuser> <ENV1dbread> <ENVIDENT> <DESC>
Database identifier for ENV2 System user password for ENV2 Product database schema owner for ENV2 (usually CISADM) Product database read-write user for ENV2 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) Database identifier for ENV1 System user password for ENV1 Product database schema owner for ENV1 (usually CISADM) Product database read-write user for ENV1 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) ConfigLab Environment identifier used for background processes. A Description for the Environment
Page 48
Identifier.
<PREFIX>
Single character view prefix to be used for the synonyms. Must be unique within the Supported environment. You cannot use 'C', 'F' or 'S' as they are reserved. The Database link created earlier. Oracle character WE8ISO8859P15) set (UTF8 or
<DBLINK> <DBCHAR> <LOG>
Name of the log file to write the registration information. Check this log for any errors.
This "cheat sheet" is provided to assist in the setup a Synchronize Target relationship also known as to "PUSH" data to another environment.
Cheat Sheet: Setting up a Synch Target relationship
Note: This relationship type will be deprecated in a future release. Use "Compare Target" instead. To push data from one environment to another utilizes a "synch target" relationship defined between the environments. This section will outline how to set up this relationship. To setup a compare source to push data from ENV2 to ENV1 (as illustrated below) then the following tasks must be performed:
ENV1 ENV1
Supporting Synchronize (Push)
ENV2 ENV2
Supported
Ensure that you know the technical details of each environment such as database identifier, system account password, owner of the schema (usually CISADM), user used by Oracle Utilities Customer Care And Billing to access the database for read-write (usually CISUSER) and the read-only user for the database (usually CISREAD). Ensure that the environment identifiers for both environments are different. This can be checked using the following database query on each environment: Select env_id from f1_installation; If they are the same then one of the environments will have to be altered so that ENV_ID is set to another value (see "Tip: Randomly reassigning ENV_IDS" for a technique) and the key tables regenerated (see "Cheat Sheet: Rebuilding key tables").
Create a database link on ENV2 to ENV1 that uses the read-write user (usually CISUSER) from ENV1. Remember to name the database link appropriate to your site standards. See "Database links" for details of the commands.
Page 49
Create a database link on ENV1 to ENV2 that uses the read-write user (usually CISUSER) from ENV2. Remember to name the database link appropriate to your site standards. See "Database links" for details of the commands. Run the EnvSetup.exe utility to register the environment in the following format: EnvSetup.exe -s
<ENV2db>,<ENV2password>,<ENV2dbowner>,<ENV2dbus er>,<ENV2dbread> -r <ENV1db>,<ENV1password>,<ENV1dbowner>,<ENV1dbus er>,<ENV1dbread> -a I -t CLAB -e <ENVIDENT> -n <PREFIX> -d "<DESC>" -x <sDBLINK> -y <rDBLINK> -c <DBCHAR> -u o C1 -l <LOG>
Where:
<ENV2db> <ENV2password> <ENV2dbowner> <ENV2dbuser> <ENV2dbread> <ENV1db> <ENV1password> <ENV1dbowner> <ENV1dbuser> <ENV1dbread> <ENVIDENT> <DESC> <PREFIX>
Database identifier for ENV2 System user password for ENV2 Product database schema owner for ENV2 (usually CISADM) Product database read-write user for ENV2 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) Database identifier for ENV1 System user password for ENV1 Product database schema owner for ENV1 (usually CISADM) Product database read-write user for ENV1 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) ConfigLab Environment identifier used for background processes. A Description Identifier. for the Environment
Single character view prefix to be used for the synonyms. Must be unique within the Supported environment. You cannot use 'C',
Page 50
'F' or 'S' as they are reserved.
<sDBLINK> <rDBLINK> <DBCHAR> <LOG>
The Database link created earlier on ENV2. The Database link created earlier on ENV1. Oracle character WE8ISO8859P15) set (UTF8 or
Name of the log file to write the registration information. Check this log for any errors.
This "cheat sheet" is provided to assist in the setup a ConfigLab relationship also known as to "PUSH and PULL" relationship.
Cheat Sheet: Setting up a ConfigLab relationship
Note: Please read "ConfigLab Role Considerations" prior to defining this relationship. To push AND pull data from one environment to another utilizes a "ConfigLab" relationship defined between the environments. This section will outline how to set up this relationship. To setup a ConfigLab relationship to push and pull data from ENV2 to ENV1 (as illustrated below) then the following tasks must be performed:
ConfigLab (Push/Pull)
ENV1 ENV1
Supporting
ENV2 ENV2
Supported
Ensure that you know the technical details of each environment such as database identifier, system account password, owner of the schema (usually CISADM), user used by Oracle Utilities Customer Care And Billing to access the database for read-write (usually CISUSER) and the read-only user for the database (usually CISREAD). Ensure that the environment identifiers for both environments are different. This can be checked using the following database query on each environment: Select env_id from f1_installation; If they are the same then one of the environments will have to be altered so that ENV_ID is set to another value (see "Tip: Randomly reassigning ENV_IDS" for a technique) and the key tables regenerated (see "Cheat Sheet: Rebuilding key tables").
Create a database link on ENV2 to ENV1 that uses the read-write user (usually CISUSER) from ENV1. As you are PUSHING data to ENV1 you only need to have update access. Remember to name the database link appropriate to your site standards. See "Database links" for details of the commands.
Page 51
Run the EnvSetup.exe utility to register the environment in the following format: EnvSetup.exe -s <ENV2db>,<ENV2password>,<ENV2dbowner>,<ENV2dbus er>,<ENV2dbread> -r <ENV1db>,<ENV1password>,<ENV1dbowner>,<ENV1dbus er>,<ENV1dbread> -a I -t SYNT -e <ENVIDENT> -n <PREFIX> -d <DESC> -x <DBLINK> -c <DBCHAR> -u o C1 -l <LOG> Where: <ENV2db> <ENV2password> <ENV2dbowner> <ENV2dbuser> <ENV2dbread> <ENV1db> <ENV1password> <ENV1dbowner> <ENV1dbuser> <ENV1dbread> <ENVIDENT> <DESC> <PREFIX> Database identifier for ENV2 System user password for ENV2 Product database schema owner for ENV2 (usually CISADM) Product database read-write user for ENV2 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) Database identifier for ENV1 System user password for ENV1 Product database schema owner for ENV1 (usually CISADM) Product database read-write user for ENV1 (usually CISUSER) Product database read-only user for ENV2 (usually CISREAD) ConfigLab Environment identifier used for background processes. A Description for the Environment Identifier. Single character view prefix to be used for the synonyms. Must be unique within the Supported environment. You cannot use 'C', 'F' or 'S' as they are reserved. The Database link created earlier. Oracle character set (UTF8 or
<DBLINK> <DBCHAR>
Page 52
WE8ISO8859P15) <LOG> Name of the log file to write the registration information. Check this log for any errors.
This "cheat sheet" is provided to assist in the setup of ConfigLab and your configuration environment AFTER an initial installation.
Cheat Sheet: Priming an environment.
Once an environment has been registered to Configlab it may need to be "primed". If the environment is in an "initial" state, with basic meta-data only and no site configuration data, then the environment has to be loaded with this data so that it can be used. This process can be performed using ConfigLab. This process has assumed that the "target" environment has been defined as Compare Source as the base setup is provided for this. To prime the environment the following jobs need to be executed: Ensure that you have setup a Compare Source relationship with an environment that contains the DB processes, Maintenance objects and other data that you need. Verify that the CI_DB_PROC and CI_MD_MO tables do not contain all the data required. A full copy of CI_DB_PROC should contain around 25 rows and CI_MD_MO should contain around 310 rows (as at V2.1.0). If they have data of this magnitude then skip the next task in this list. Execute the CI_COPDB (compare) background process to pull the DB processes and Maintenance objects into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPDB as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COPAD (compare) background process to pull the Adjustment FT Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPAD as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COPAP (compare) background process to pull the Automatic Payment Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPAP as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COPBI (compare) background process to pull the Billing Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes
Check source environment has required data.
Copy DB Processes and Maintenance Objects.
Copy Adjustment FT Algorithms.
Copy Auto Pay Algorithms.
Copy Bill Algorithms.
Page 53
execute CL-APPCH (apply) background process with CI_COPBI as the DB process parameter and the environment reference of the Compare Source relationship you setup.
Copy DOC1 Algorithms.
Execute the CI_COPD1 (compare) background process to pull the DOC1 Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPD1 as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COPIN (compare) background process to pull the Installation Record's Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPIN as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COPPY (compare) background process to pull the Payment Algorithms into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COPPY as the DB process parameter and the environment reference of the Compare Source relationship you setup. Execute the CI_COCNT (compare) background process to pull the configuration into your environment specifying the environment reference of the Compare Source relationship you setup. After that completes execute CL-APPCH (apply) background process with CI_COCNT as the DB process parameter and the environment reference of the Compare Source relationship you setup. The environment is now primed.
Copy Installation Algorithms.
Copy Payment Algorithms.
Copy Admin Tables.
This "cheat sheet" is provided to assist in changing the environment identifier for an environment.
Cheat Sheet: Rebuilding key tables
If you change the Environment Identifier on the installation record for an environment the key tables for that environment need to be rebuilt. For ORACLE implementations use the following SQL to generate the necessary update statements: select 'UPDATE ' || table_name || ' SET ENV_ID = xxxxxx' from user_tab_columns where column_name = 'ENV_ID'; where xxxxxx is the number to be allocated to the environment number. Note: Do not forget to commit the updates. If you want to generate a random number use the following SQL:
Page 54
select round(dbms_random.value(1,999999)) from dual;

Using ConfigLab with Development can be a challenge, but there are a number of alternatives.
Alternative Development Solutions
This section outlines some example alternative solutions to consider for your ConfigLab solution.
Transferring between offsite and onsite
If ConfigLab cannot be used then an alternative is to provide an export to the office developers.
If ConfigLab cannot be used between an offsite development center and the site, for whatever reason, then what alternatives are available if data is to be transferred between the sites? An alternative that has been used successfully is to provide a database export on a regular basis to the development center. This export is loaded into a dedicated schema/database at the development center and then transferred to the active Development database using ConfigLab as needed. It is possible load the export directly into the Development database but it may overwrite important data delaying development. This solution is documented in the Software Configuration Management Series Release Management document.
It is possible to use the ConfigLab role in the sample solution but it is not without risk.
Use of ConfigLab role at Hartwell Energy
It is possible to daisy chain the solution for Hartwell energy as outlined in the diagram below:
Hartwell Energy An alternative ConfigLab Solution (ConfigLab)
Supported
Supporting
Env Id: 908444 Env Id: 908444

Compare Source

Compare Source
Supporting
ConfigLab
Supporting
Compare Source

Env Id: 701799 Env Id: 701799

Synchronize ConfigLab
Synchronize
Supported
Env Id: 568570 Env Id: 568570

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
This would allow any data changes to be reflected back into other environments but has the side effects outlined in "Warning about the ConfigLab Role".
Page 55
Advantages Ability to migrate changes back from testing environments to the Control environment
Disadvantages UAT is now coupled with System Test and Control. All the environments must be active (databases at least) for any record to be added to UAT and System Test. This is to maintain the "Key Space". Performance will take a hit in UAT as it checks the key space in System Test and Control before adding the object. Performance will take a hit in System Test as it checks the key space in Control before adding the object.
It is possible to use a Hub-Spoke solution at Hartwell Energy.
Hub and Spoke at Hartwell Energy
One of the design patterns is to transfer data from the Control environment to other environments. This is useful where the owners of the other environments simply want the data and are not interested in approval/rejection or tracking changes in their environments. This solution is outlined in the diagram below:
Hartwell Energy An alternative ConfigLab Solution (Hub/Spoke)
Supported
Supporting
Env Id: 908444 Env Id: 908444

Compare Source
Synchronize
Supporting
Env Id: 889653 Env Id: 889653

Compare Source
Supporting
Supporting
Compare Source

Env Id: 701799 Env Id: 701799

Env Id: 196503 Env Id: 196503 Supported Supporting
Synchronize Synchronize
Supported

Synchronize
Supported
Supporting Supporting Supported
Env Id: 568570 Env Id: 568570

Env Id: 400809 Env Id: 400809
Env Id: 312415 Env Id: 312415
Note: In the above diagram Production is still taking data from UAT. This is to enforce the rule that Production is always a Supported environment and will want verified configuration data from UAT only. Advantages Disadvantages
Page 56
Advantages Control Data will overwrite Acceptance test and System Test configuration data.
Disadvantages There is no scope for Approval or Rejection of changes for configuration data for System Test or UAT. The users of the Control environment initiate the job to overwrite the data in System Test and UAT. In other words, they control the migration. There is no record of the migration of configuration data to System Test or UAT to remedy errors or check what was changed.
Page 57
ConfigLab Design Guidelines March 2008 Author: Anthony Shorten, Principal Product Manager, Tax and Utilities Global Business Unit Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com Copyright 2007, Oracle. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

ConfigLab - Design Guidelines

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ConfigLab - Design Guidelines

Uploaded by

Copyright:

Available Formats

ConfigLab Design Guidelines

Tax and Utilities Global Business Unit March 2008