Configuration Migration Assistant Primer

When should I use CMA?

If a developer has delivered an Algorithm Type or other code elements, the designer or testing business
analyst will create a Migration Request for accompanying configuration such as the related Algorithm or
Characteristic Types, reflecting the final configuration for Production. The best part about CMA is that
the configurator will not (usually) require the assistance of a developer to migrate additional
configuration.

When should I use an SQL?

An SQL is required if we are deleting configuration. If we are merely removing a Characteristic Type from
an SA Type, that will not require an SQL. But if we wanted to delete the Characteristic Type entirely, an
SQL is needed.
Do not use CMA when migrating objects with environment-specific configuration. This may include some
Navigation Keys, Service Task Types, Message Senders and other integration-related objects. Do not use
CMA for migrating Users or User Groups. We do not maintain the latest User configurations in the lower
environments, and more often than not, there will be Application Services attached to some User Groups
that are not yet ready for Production. An SQL will be better able to insert any additions or updates.

Where do I create a CMA Migration Request?

All CMAs should be created in the Configuration environment (formerly known as Prod Dev). Once
exported, the CMA file is uploaded to an online library and can be applied by the DBA to any other
environment, including Production.
To create your CMA, use CC&B’s Admin Menu > M > Migration Request > Add.

If you can find an existing Migration Request listing all of the objects you need, Migration Requests can be changed,
edited and exported multiple times. You can either duplicate an existing Request or simply reuse the original Request if it
represents a previous version of your module (as for a defect). Make sure to add a line to the Detailed Description.

Which Migration Request Business Object should I select?

(1) Criteria-based [Recommended] – references objects and their Migration Plans;
(2) Group – references other Migration Requests;
(3) Entity List – search via Maintenance Object and Primary Keys. This is not recommended as the system
will default the Migration Plan to use.

How do I name my Migration Request?

Use this template for the Migration Request field:
CM-PJ-Description

Spire | Configuration Migration Assistant Primer | 2.0 1

CM - CM (Custom) | ZZ or XX (Temporary) - Use CM for Migration Requests we will eventually use in
Production.
PJ – S1 (SpireOne) | PS (Production Support) - Choose the Project that the configuration belongs to
Description - This can be a description of the grouping of contents in your Migration Request. If your
module has a code or name, use that. Optionally, include a human-readable suffix. (ex. CM-S1-CCB014,
CM-PS-SA450789-RateFix, CM-S1-CN-AL-DistributionCodes)
Fill out the Description and Detailed Description as necessary. A Migration Request can be edited even
after being exported. In order to keep track of these changes, we suggest adding this to the top of the
Detailed Description:
Date Exported, By, File Name
10-26-2020, BMarquez, 56024_S1_CS_B-11544_MyAcctSaStart_001
<Date>, <Your Name>, <File Name used for export (see below for details)>
You can leave the Category field dropdown blank.

Which Migration Plan should I use?

Migration Plans specify the object you are migrating. You can find Migration Plans in the system for most
Admin objects and more than one Migration Plan for the same object in some cases. It is important to
use the Migration Plans that will move the smallest amounts of configuration as possible. The more
objects that the Migration Plans move, the more likely it is that the export will include objects that are
being altered by other modules.
Base Migration Plans which are prefixed with C1 or F1 will also migrate objects that the main object
references. For instance, if you choose the C1-AdjustmentType Migration Plan, you can move the
Adjustment Type along with the Adjustment Type’s Approval Profile, A/P Request Type, Distribution
Code and CIS Division. This is useful if you are migrating a new Adjustment Type that also has a new
Approval Profile or A/P Request Type, etc.
If you choose the C1-AdjustmentType+ Migration Plan, the Plan also includes the Adjustment Type’s
Algorithms and the Currency Code.
If you choose the CM-AdjType-Basic, the Plan only moves the Adjustment Type object and immediate
children such as Adjustment Characteristics. No other objects are moved. The Characteristic Type of the
Adjustment Characteristics will not be included in the extract.
The system has CM versions of some of the base Migration Plans. There should be short descriptions of
why a CM variant was created in the Detailed Description of the Migration Plan. For example:

How can I see what is included in a Migration Plan?

Go to Admin > M > Migration Plan. Generally, each Instruction row is a single Maintenance Object (a
collection of the object and its child tables; see Application Viewer for full Maintenance Object list).

Spire | Configuration Migration Assistant Primer | 2.0 2

How can I change what is included in a Migration Plan?
If none of the available Migration Plans are appropriate (usually because they are exporting too many
additional objects in the validation step, see How do I validate my exported CMA file? below) or a
Migration Plan does not exist for the object you are moving, a developer can assist you in creating new
Migration Plans for your configuration.
Remember to include any new Migration Plans on your Migration Request (use F1-MigrationPlan
Migration Plan).

After I’ve chosen a Migration Plan for the object, which Selection Type should I
choose?
(1) Specific Key [Recommended] – If you are migrating more than one object for the Migration Plan, you
can use the Add button to create more rows (highlighted in red below).

Primary Key 1-5 Fields are used to identify multi-key objects. For instance, an SA Type being moved
would name Primary Key 1 as the CIS Division and Primary Key 2 as SA Type Code. You can check which
Primary Keys are needed via the Application Viewer. The golden keys indicate the necessary Primary
Keys. They are listed in order.

Spire | Configuration Migration Assistant Primer | 2.0 3

Using Specific Keys allows us to search which Migration Requests contain the object we are migrating.

(2) SQL Statement [Recommended when migrating all configurations] – Uses a WHERE clause of an
SQL statement to determine objects to export. Best when exporting every instance of a configuration.

(3) Algorithm – No relevant Algorithms yet.

How many objects can I migrate with my Migration Request?

General rule of thumb: Use one Migration Request per development module or ticket, and don’t try to
include unrelated changes in the same Migration Request.
Migration Requests can contain thousands of objects, but consider breaking large Requests into smaller
Migration Requests so that import failures are easier to track down.
For larger releases, many Migration Request can be grouped into a Group Migration Request. The Group
Migration Request will be exported more often, ensuring configuration mistakes are found quickly.

Do my objects need to be entered in a particular order?

An imported CMA file’s objects are processed in a loop until no objects are valid for application in the
environment. If some objects are still not applied, the CMA will show an Error.
For example, if we exported an SA Type and its new required Characteristic Type, the SA Type would
need the Characteristic Type to exist before it is saved on the next environment. The Migration Import
batch will create the Characteristic Type first and loop back around to create the SA Type.

I have added all my objects to my Migration Request. How do I export the

Request to a file?

Spire | Configuration Migration Assistant Primer | 2.0 4

Use the button in the upper right of the page, Export.

Only fill in the File Name and Export Description. Do not add “.cma” to the end of the File Name field.
Use the File Name as the Export Description when possible.

What file name do I use for the Migration Data Set Export?
Some general guidelines:
1. Do not use spaces in the CMA file name; replace spaces with underscores
2. Do not use punctuation other than underscores and hyphens (not dashes)
3. One Mercury ticket can have more than one CMA file. If more than one CMA file is needed, consider
a Group Migration Request to export all the Migration Requests to one file.
4. Do not add .cma to the filename as this is automatically added

The CMA file name should use this format:

NNNNN_PJ_ZZ_CCBXXX_Descr_VVV
NNNNN – Mercury ticket number (see below on how to get one)
PJ - S1 (SpireOne) | PS (Production Support) | CN (Alabama/Gulf Conversion)
ZZ - DM (Device Management) | CS (Customer Service) | BI (Billing and Rates) | FA (Financial
Accounting) - This is the functional area or subsystem. It helps route the Mercury ticket to the appropriate
approvers on its way to Production. The lookup table is included in the appendix. Use the values from the
first column.
CCBXXX - This is the functional reference for the change. It should be the original design code (ex.
CCB101), QA Complete Defect number (ex. 4504524) or VersionOne Story ID (ex. E-09876), whatever
can help link the change back to documentation and approvals.
Descr - This is a short or abbreviated description (ex. ‘Transportation’ for “Transportation Billing” or
‘FMR’ for “Fast Meter Refund”) that helps humans remember what is inside the file.
VVV - This is the version number. The first time the file is exported, this should be 001. Every time the
Migration Request is re-exported, add one to the last exported file’s version number to keep the name
unique in the file folder.
Example file names:
45992_S1_DM_CCB012_Appliance_001
46829_PS_BI_DollarHelpFix_002
56024_S1_CS_B-11544_MyAcctSaStart_010

Spire | Configuration Migration Assistant Primer | 2.0 5

How do I get a Mercury Ticket number?
A request for Mercury ticket creation can be made to Ram Thundena for SpireOne with the following
information:
Doc ID <VersionOne Story, SysAid ticket, Design Code or QA Complete Defect
Number>
Ex. E-09838
Functional Area <See ZZ section above>
Ex. Customer Service and Experience
Title <Description of change>
Ex. SA-789403 Person Characteristic is Misconfigured
Summary <Summary of change>
Ex. Add new Person Characteristic
CMA filename <Use NNNNN and VVV as placeholders for the Mercury ticket and
versions>
Ex. NNNNN_PS_CS_SA-789403_PS_CS_NewPersonChar_VVV

How do I fill out the Export Description?

Copy the File Name as the Export Description. The Export Description shows up on the Import, so it’s
important that the Mercury Ticket and file version are visible.
After you press Save, your page will have the export information. Hit Refresh until the Status changes
from “Pending” to “Exported”.
If the Status does not change, contact the DBA Team (Krishna and Sridhar) to restart the batch thread
pool workers. Check on the export page again to make sure the CMA exports.

Where is this CMA export file saved?

Exported Migration Plan files end up in Gitlab and also get copied to the Config Envi’s import folder for
CMA validation. Note that this process commonly takes five to ten minutes to complete after the
Migration Export is complete. You will not be able to validate your CMA file until the process has copied
it to the Config Envi’s import folder.

How do I validate my exported CMA file?

Ten minutes after the export process completes, use the Favorite Scripts Search link in the CCB
Dashboard to run “BPA script to import CMA file”.

Spire | Configuration Migration Assistant Primer | 2.0 6

Paste your file name into the text box at the top of the page.

Pressing Continue will bring you to the Migration Data Set Import page. The Status should be Unchanged
if you just exported it since the source system is the same as the target system.

If the Status is Error with a Log message indicating the file does not exist, try the script again in five minutes. If the
problem persists, contact the DBA team.

Expand the Migration Data Set Impacted Object Summary, and click the Filters button to reveal the
Search fields. Change the Status field to “Include Any Status” and hit Search.

Review the objects that appear in the pane, make the appropriate changes, then export your CMA file
again with the next version number if necessary:
Issue Solution
Remove test configurations.

Spire | Configuration Migration Assistant Primer | 2.0 7

 Test objects (prefixed with Change source Migration Plan to one that migrates less objects.
XX or ZZ) are included.
Objects not yet ready for Remove configurations, then add them back after the CMA file exports
Production are included. successfully.
Change source Migration Plan to one that migrates less objects.

How can I request migration of my CMA to a different environment?

Properly fill out the corresponding Mercury ticket:
1. Technical Description – Should include any instructions for the DBA past applying the file you
need. For CMAs, indicate “No restart required.”
2. Change Info Action(s) / Transport(s) – Should list the correct file name of your CMA and
packages. This means that this field needs to be updated if the CMA is re-exported and the
version number changes. You can do this by sending your ticket back to development (use the
“Redevelopment” button.
3. Notes – Add deployment history here. Each note should include the actual file requested to the
DBAs. For example, “Deploy 47046_S1_CS_4611730_Rate4_003.cma to PL UAT”.
4. [Requesting to Production Only] Your Mercury ticket should have the UAT test document
attached in the “Attach Testing Documentation” field.
Use the Complete button for migrations to non-Production environments. Use the Approve button for
migration to Production. See the Appendix for the full process.
Send an email to the DBA Team (Krishna and Sridhar) including the following information:
 CMA File Name
 Target Environment
 Specify that no outage will be needed
Please CC Ram and any developer.

My CMA file failed the import process. What do I need to do?

In the target environment, go to the Migration Data Set Import page via Admin > M > Migration Data
Set Import. Use your file name to find the Data Set.
The status of your Data Set may be “Apply Objects”. If the Migration Objects in Error Zone does not
appear on the page, bring the issue to the DBA’s attention, and they may rerun the CMA or run some
batch processes.
If the Migration Objects in Error Zone is visible, determine the issue using the messages, or consult a
developer like Ravi or Bev for further assistance.

My CMA file says it imported successfully, but I don’t see the changes in the
target environment.
This could be a cache issue. Ask the DBA or a system admin to flush the cache, or check the database to
confirm the changes (or lack of).

Spire | Configuration Migration Assistant Primer | 2.0 8

Summary: How do I create a CMA?
1. Create a Migration Request in the Config Envi.
a. Use naming convention CM-PJ-Description
b. Recommended Migration Request BO: Criteria-based
2. Add your configuration to the Migration Request.
a. Use the Migration Plan that best represents the object you are exporting with the least objects
migrated along with it
b. Recommended Selection Type: Specific Key
3. Request for a Mercury Ticket.
4. Use the Export button to create the CMA file.
a. Use naming convention NNNNN_PJ_ZZ_CCBXXX_Descr_VVV.
b. Keep refreshing the page until Exported.
5. Wait five to ten minutes.
6. Verify your CMA file by reimporting it via BPA Script “BPA script to import CMA file”.
7. Fill out Mercury ticket.
8. Request migration of your CMA file with an email to the DBA team. Include the following:
a. Filename
b. Target environment

Spire | Configuration Migration Assistant Primer | 2.0 9

Appendix A. Functional Areas
ZZ CCB FS Description
DM Premise and Device Management
DE Meter & Device Management
FW Field Work
GD Geographic Data Management
MD Meter Data Management
MR Meter Reading
PM Premise Management
WI Field Activity Integration
CS Customer Service and Experience
AP Appointments
CA Case Management
CD Customer Data Management
OS Outage Management
QT Contract Management
SM Order Entry
TD To Do Worklists
WF Workflow Tools
WS Workflow Scheduling
BI Billing and Rates
BI Billing
MP Multi-Party Billing
RT Rating Engine
FA Financial Accounting
FD Financial Data Management
RP Reports
LO Loans
PY Payment Processing
XC Business Intelligence CRM Extracts
XF Business Intelligent Financial Extracts
CN Conversion (Restricted Use)

Spire | Configuration Migration Assistant Primer | 2.0 10

Appendix B. Environment Landscape
As of 11/1/2021

Spire | Configuration Migration Assistant Primer | 2.0 11

Appendix C. Mercury Ticket Workflow

Mercury Ticket
Development.png

Spire | Configuration Migration Assistant Primer | 2.0 12