MANAGEMENT OF DEVELOPMENTS AND CONFIGURATIONS

1.1      Introduction

This document describes the methodology and procedures for maintaining the various Maximo environments that will be used in the development and application of the Enterprise Work Management Solution.

The goal of these procedures is to ensure that all developments created by EMA or the City, are controlled and deployed in a systematic and reproducible pattern. This methodology was designed to limit the risk of inconsistent Maximo system behavior when multiple development phases are occurring simultaneously (overlapping work packages).

1.2      Assumptions

·        EMA will not have access to the PROD system.

·        EMA will be allowed to perform database backups in the DEV and SIT environments. The City will perform database restores for EMA on an ‘as-requested’ basis. Ideally, the response time by the City should be within one hour.

1.3      Methodology

Typically, Maximo configuration and application change work is divided into two separate groups: the Functional Team and the Development Team.

The Functional Team will be responsible for creating 'designs,' but not actually making the changes to the DEV development system. 

In DEV, the Development Team will be solely responsible for making all system modifications and configurations, data changes and creation of the related migration packages and ‘Packets.’ 

The goal of this approach is to ensure that every change to the system is included in a ‘Packet.’ In this way, the Environment Manager (EM) will be able to control the movement of ‘Packets’ between the various Maximo environments. ‘Packets’ will typically be moved from DEV to SIT. Once, the functionality is tested, the same Packets can be moved to QA, TRN and PROD. This methodology provides an extra layer of validation for any changes to the Maximo systems.

The Functional Team will typically have access to a Maximo instance (‘sandbox’ or virtual machine) where they will be able to prototype their solutions. The Functional Team will then document all the required changes and deliver it to the Development Team in the form of a Functional System Specification (FSS) document. The Development Team will then make the changes in DEV. The nature of this procedure will help ensure that any system changes are well documented and that the ‘Design’ document will be reviewed by the Development Team.

The Functional Team will:

·        Understand the specific task requirements

·        Create a design

·        Possibly implement the design or screen change in a Development environment

·        Document the design with enough detail that the Development Team can implement it in DEV

·        Once developed and unit tested by the Development Team, the Functional Team will perform functional testing on the implementation of the design in the DEV system and document any issues discovered

·        Test the implementation of the design in any system to which the package is migrated

The Development Team will perform the following tasks:

·        Review of functional system specification

·        Implementation and unit testing of functional system specification in DEV

·        Update the Requirements Traceability Matrix to document unit test results

·        Fix issues found from Functional team testing in DEV and retest

·        Creation of Packet after all issues have been resolved and functional testing is completed

·        Update the Packet Log document

·        Notify Environment Manager that a Packet is pending

 The Environment Manager will perform the following tasks:

·        Applying Packet(s) to the SIT system

·        Ensure successful migration of Packet(s). If unsuccessful, the EM will work with the developer responsible for the Packet to make the required modifications to the Packet. The EM will then migrate the modified Packet.

·        Update Packet Log document, PacketLog.xlsx

The DEV system will be the ‘source’ for all migration.

1.3.1     General Notes about Migration

The installation of some Packets will require that the Maximo Database Configuration process be run. Typically, any changes to MaxObjects, MaxAttributes, Indexes, Domains or updating of attribute default values will require a DBConfig operation to be initiated. This requirement should be documented in the Packet.

Before applying some Packets, the Maximo system may need to be placed into ‘Admin’ mode.

1.3.2     Typical Order for Configuration Migration

Table 2‑1: Typical Order for Configuration Migration

1.3.3     Migration Manager

This section describes which objects are typically migrated using the Maximo Migration Manager application. It also attempts to document any known issues with the application.

Table 2‑2: Object Typically Migrated using Maximo Navigation Manager Packages

1.3.4     MxLoader Procedures

Objects that can be migrated using MxLoader:

Typically objects that contain xml data cannot be easily migrated using MxLoader. For example, Presentations.

Table 2‑3: Procedures for Objects that can be migrated using MxLoader

1.3.5     Manual Loading

The following objects require some manual intervention in order to load:

Table 2‑4: Objects that require manual intervention to load

1.3.6     Application Screen Modifications

Typically, application screens are exported from the DEV system and then imported into the other systems as part of the Packet. However, there may be simultaneous development by different Developers occurring on a particular screen. For example, one Developer is adding a new attribute to the Work Order screen specifically for SWMS, and another Developer is adding an attribute required by TW to the same screen. The SWMS Developer may have completed their change, but the TW Developer may be only partially complete. If the SWMS Developer creates a new Packet that contains the entire screen, but the TW functionality is not yet working, there will be issues when the screen is imported into the QA system. In this case, the following procedures can be used.

IBM provides two Screen Upgrade Tools to identify and apply application changes. The Developer will use the MXDiff Tool to generate an mxs file that will identify the differences between the original presentation XML and the updated XML. The Developer must ensure that the updated XML file only contains the changes that are ready to be migrated. The EM will use the MXApply Tool to apply the changes in the mxs files to the other systems.

Screen changes can be encapsulated as ‘xml snippets’ in the mxs files that can be applied to a different environment. The ‘xml snippet’ will only contain the portion of the screen that is particular to the new attribute. During the migration of the Packet, the EM will use the MXApply Tool.

1.4      Packets

With many Developers working on different aspects of this project, the key challenge is to ensure that the various developments/configurations created by EMA are migrated to the various Maximo environments in complete, tested packages. In addition, we need to ensure that the process of creating a ‘CoT configured’ Maximo system is repeatable.

The word Packet is used to describe all the required components of a particular ‘development’ or functional requirement. This could include Maximo Migration Packages, XML screens, SQL scripts, etc. A Packet could be a large or small grouping of components. The only criteria being that the migration of a single Packet must not cause any inconsistencies in the Maximo system. 

The goal is to be able to recreate any version of any system by starting with a base Maximo instance and migrating the Packets in a precise order.

An Excel spreadsheet, PacketLog.xlsx, will be used to track the ‘progress’ of the migration of the ‘Packets’ in various Maximo environments.

When a Developer has a unit of development ready to be deployed, they will create a Packet that includes all of the new components for that unit of the development. Typically, the components would include migration packages (zip files), xml files (or xml snippets) and a mandatory ‘Installation’ text file (Installation.txt). 

The installation text file will contain:

·        the list of components included in the Packet;

·        which objects in Maximo are affected; and

·        installation instructions for the Packet. Instructions assume the user is experienced in the use of Migration Manager, MxLoader and other supporting Maximo tools.

1.4.1     Sample Packet Folder

Packets

└───p00XX

    ├───Installation.txt

    ├───Migration Manager Packages

    ├───MxLoader Files

    ├───classes (if java class customizations are required)

    │   └───applications

    │       └───maximo

    │           ├───businessobjects

    │           │   └───classes

    │           │       └───cot

    │           │           └───app

    │           └───maximouiweb

    │               └───webmodule

    │                   └───WEB-INF

    │                       └───classes

    │                           └───cot

    │                               └───webclient

    │                                   └───beans

    ├───dbc_scripts

    ├───migration

    └───presentations

└───p00YY

    ├─── ...

See Appendix for a sample Installation.txt file.

The Developer will then access the Packet Log spreadsheet (PacketLog.xlsx) from an EMA MS Teams folder. 

Example file: PacketLogTemplate.xlsx

Open

Figure 2‑1: Example Packet Log Template file

The Developer will add a new row to the spreadsheet and create the next available Packet Number by incrementing the previous number by one (e.g., p00078). In addition, they will update the ‘Developer’ column with their name to indicate that the number is reserved for them.  Developers must ensure that they create the Packet before obtaining a new Packet Number. This will prevent the issue of another Developer adding a Packet between the time the number is reserved and the time the Packet is uploaded. Remember that the order of Packets could be significant.

The Developer will move their Packet to a shared folder for the system: Packets/ReadyToBeInstalled

https://emainc4.sharepoint.com/:f:/s/TorontoEWMSProgram347/EngiV8LXCjFKlbfIgpxVaIMB1rr8n6iJM_WB9VGqYTbYAA?e=9npA8f  

Toronto EWMS Program > Migration Packets > Packets > ReadyToBeInstalled.

Note that this folder is NOT available to COT.

Then the Developer will notify the Environment Manager that a new Packet is ready to be installed.

The EM will move the Packet to a working folder: Packets/SIT/Installing.

The EM will:

·        Perform a DB backup in SIT. For other environments, a DB backup request will be sent to the City for the environment to which the Packet is being migrated. (Post Go-Live, a different procedure may be implemented).

·        If any Java Class changes are listed in the Packet, make a backup of affected Class folders.

·        If any application updates are listed in the Packet, make a backup of the affected applications or System XML. Presentation XML files will be exported and saved in the ‘Presentation XML Files’ folder before any application changes are made.

·        Document any manual steps involved (Installation.txt). For example, modify an existing screen by exporting the current version of the screen and make a backup of the xml file.

Next, the EM would migrate the Packet.

If there were any errors:

·        Notify the Developer of the error

·        Restore the system to its previous state (e.g., restore database, or import backup application XML)

·        Move the Packet to the Packets/Failed Folder.

If Successful:

·        Move the Packet to the Packets/SIT/InstalledPackets folder (this will have security so that only EM will have write access).

·        Update the ‘Packet Log’ to show the date that it was installed in the system.

·        Notify Developer and Functional Lead that the Packet has been applied to a system (e.g., QA).

At certain points in the development cycle, the EM may choose to consolidate all of the Packets to date in a new database/system backup. This would provide a ‘snapshot’ of the system which could be used as a ‘restore’ point. Then a system could then be restored starting with the ‘snapshot,’ applying only the Packets that were created after the ‘snapshot’ was made. This process would be much faster than starting from a new Maximo install and applying all Packets in order.

Once a Packet has been verified for completeness in SIT by both the Developer and the Functional Lead, the Packet is ready for the QA environment. After the development has been validated in QA it can be moved to the TRN and/or PROD environments.

1.4.2     Packet Flow

Figure 2‑2 : Packet Flow diagram

Open

Often after functionality has been reviewed in QA (or TRN), there may be a need to modify the functionality. If changes to the functionality are required after a Packet has been applied, then a new Packet must be made. Note: Once a Packet has been migrated it will never be modified. The EM will be responsible for ‘locking’ a Packet once it has been applied to a system. The EM will change the status of the Migration Package definition in the system to LOCKED so no new packages can be created and distributed. There may even be cases when a new Packet needs to be created to reverse the effects of a previous Packet. However, this additional step is necessary to ensure that any system can be re-created by applying the Packets in order.

1.5      Data Migration

Any data that needs to exist in all Maximo environments will not be entered manually in Maximo. It will be imported using MxLoader, Maximo Integration Framework (MIF) files or populated automatically from an integration.

MxLoader or MIF formatted spreadsheets will be created for data elements to be imported into Maximo. Packets will be created that contain the import spreadsheets and the instructions to import the data.

Please refer to the Data Load Guide for details.

https://emainc4.sharepoint.com/:w:/s/TorontoEWMSProgram347/ETeiGVgK0f1GvFTbzsy7jCEBzSxFO5ny71sUly07pPCjRg?e=cJ3H22

City of Toronto Collaboration > WP SWMS > System Design > As-Builts

1.6      Priority Fix

There may be certain situations when an issue is reported that needs to be addressed as soon as possible. However, due to a development being underway in SIT (i.e., in the middle of making a configuration for one Division and it isn’t complete or ready to migrate), it may not be possible to create a Packet that encapsulates only the required fix as it overlaps other development still in progress. In this case, it may be necessary to create a ‘Priority Fix.’ A ‘Priority Fix’ is a special type of Packet that is intended as a ‘temporary fix.’ The ‘Priority Fix’ will be applied to the required environments to address the issue immediately. The functionality contained in the ‘Priority Fix’ will be incorporated into a Packet once the development effort is complete that contains the developed functionality and the priority fix, that will be applied at a future date eliminating the need to carry the ‘Priority Fix’ forward to future installs.

1.7      COT Changes During EMA Development

Once a Division has gone into production, enhancement requests for one or more Divisions may be addressed by the COT Sustainment Team while development for one or more other Divisions is underway by EMA. COT development in this situation will be based on protocols agreed to by both parties. See Appendix E, Flow Charts, for COT protocols relating to Change Coordination, Change Implementation, Packet Application and Testing & Release.