Introduction

Migrating screen changes in Maximo tends to be an all or nothing proposition. If you want to move a screen from one environment to another, typically you export the presentation.xml and then import it in the target environment. This works well enough in environments with a single developer and a linear promotion path, where changes go from development, to test to production. However, what happens when you have more than one development environment or more than one developer working on a feature? What happens if you have two features being developed for a single application, do you wait until both are complete or do you try to migrate them separately through a manual process?

Avoiding conflicts and overwriting previous changes requires manual coordination and often lengthy migration instructions to ensure that individual changes are applied correctly. Fortunately Maximo provides the mxexport, mxdiff and mxapply tools to extract, define transactional screen changes and apply changes to a target environment.

In this post we will discuss how to use these three tools to define granular screen changes that allow for better collaboration and a safer migration strategy.

MXExport

The mxexport tool is located the [SMP_HOME]/maximo/tools/maximo/screen-upgrade directory and is used to export Maximo presentation XML to the admin work station. To export a presentation XML, invoke the mxexport.sh (Linux) or mxexport.bat (Windows) with the -a flag, followed immediately and without spaces by the name of the Maximo application presentation XML to export.

For example, to export the WOTRACK application presentation XML, execute the following command. This will export the WOTRACK XML to a file named WOTRACK.xml in the current directory.

Linux

Copy
./mxexport.sh -aWOTRACK

Windows

Copy
mxexport.bat -aWOTRACK

MXDiff

The mxdiff tool is located the [SMP_HOME]/maximo/tools/maximo/screen-upgrade directory and compares two export files, a baseline and a modified presentation XML, and generates a third transaction file that describes the actions needed to apply the modified changes to the baseline. You can use the mxexport tool to export the presentation XML from the baseline or target instance and the instances that contains the modifications to apply. Then you invoke the mxdiff.sh (Linux) or mxdiff.bat (Windows) with the -b flag followed immediately by the name of the baseline export file, the -m flag followed immediately by the name of the modified export file and finally the -t flag for the desired name of the output transaction file.

For example, if we have a baseline WOTRACK presentation XML named wotrack.xml and a modified WOTRACK presentation xml named wotrack_mod.xml and want to produce a transaction file named wotrack.mxs, execute the following command.

Linux

Copy
./mxdiff.sh -bwotrack.xml -mwotrack_mod.xml -twotrack.mxs

Windows

Copy
mxdiff.bat -bwotrack.xml -mwotrack_mod.xml -twotrack.mxs

In our example, all the files are in the current working directory and are referenced by name, a fully qualified path can be provided if desired.

mxdiff.sh

For those of you on Linux, you may have noticed that a mxdiff.sh is not provided by IBM. We have adapted the mxdiff.bat as a bash shell script and provided it here.

You can download the file and copy it to the [SMP_HOME]/maximo/tools/maximo/screen-upgrade directory. Then change the file flag to executable with the following command.

Copy
chmod ugo+x mxdiff.sh

Note that changes to the System XML, such as LIBRARY, LOOKUP and MENUS, can be exported and compared in the same way as application presentation XML files.

MXDiff Transaction File

The transaction file that is created is a plain text XML file that can be edited and modified. This is helpful as it can be read to understand the changes that will be applied and also allows for fine tuning of the changes that will be made.

Below is a sample transaction file that adds a print button to the Item Master storeroom entries.

Copy
<?xml version="1.0" encoding="UTF-8"?>
<updatescript version="7.1.0.0">
    <app apptype="webclient" id="item">
        <add after="storeroom_inventorytable_tablebody_10" container="storeroom_inventorytable_tablebody" control="tablecol">
            <set property="id" value="1647719182972"/>
            <set property="mxevent" value="printevent"/>
            <set property="mxevent_desc" value="Print"/>
            <set property="mxevent_icon" value="nav_icon_print.gif"/>
            <set property="type" value="event"/>
        </add>
    </app>
</updatescript>

Note the mxdiff tool transforms all values to lowercase. If you are exporting configurations that contain bean class names that are case sensitive, you will need to manually edit the file to restore the values to their proper case.

MXDiff Transaction DTD Schema

Unlike DBC scripts, which IBM provides the script.dtd to describe the valid layouts of the DBC files, the screen transaction files are not documented. We have analyzed the output of the mxdiff tool and created a updatescript.dtd that can be used to assist with manually editing and validating screen transactions files. You can download the dtd file here.

The DTD schema was created by analysis of sample transaction files and may have missed some less common uses. If you find any issues with our DTD, please let us know at [email protected] and we will update our DTD with your findings.

MXApply

The mxapply tool is located the [SMP_HOME]/maximo/tools/maximo/screen-upgrade directory and applies the transaction file to a target system. To apply the changes, copy the transaction file to target system and then execute the mxapply.sh (Linux) or mxapply.bat (Windows) with the -t flag followed immediately by the name of the transaction file if it is in the same directory or the full path to the transaction file if it is located somewhere else.

For example, to apply the WOTRACK changes from our previously example execute the following command.

Linux

Copy
./mxapply.sh -twotrack.mxs

Windows

Copy
mxapply.bat -twotrack.mxs

Note that transaction files can also be applied using the same runscriptfile tool that applies DBC scripts, where the name of the dbc file is replaced with the name of the transaction file, for example runscriptfile.sh –fwotrack.mxs.

Conclusion

In this post we demonstrated using the mxexport, mxdiff and mxapply tools to export application presentation XML, create a transaction file and finally apply that transaction file to a target environment. In combination these tools allow for fine grain control when migrating and managing screen changes between environments that far surpasses simply exporting and import presentation XML files from one environment to the next.

If you have any questions or comments please reach out to us at [email protected]