1. Overview

Database configuration scripts, or DBC scripts, are XML-formatted instructions for making changes to the Maximo database. DBC scripts allow you to script changes to the Maximo environment in a way that can work with the Maximo updatedb command. These scripts also give you a database-independent way of making some changes that will work with Oracle Database, Microsoft SQL Server, and IBM Db2. In some cases, where you absolutely need to create a change for a specific database platform, you can create scripts that only run on some databases.

The following list shows some things that you can do by using DBC scripts:

  • Add new database tables

  • Add or modify field validations to existing Maximo objects

  • Add or modify fields on existing objects

  • Add, modify, or delete indexes

  • Add security options

  • Add a new application

  • Add Maximo relationships between objects

  • Add or modify domains (lookups)

  • Add menus

  • Add or change system properties

  • Add or change Maximo variables

  • Load data

DBC scripts are typically created manually. Although in some cases, you might be able to use tools that can extract configurations from Maximo and export that information into a DBC file.

2. Getting started with DBC scripts

You have two options when working DBC scripts:

  1. Standalone scripts that you manage and run manually

  2. Scripts that you want package and run as part of an add-on

2.1. Standalone scripts

In some cases, your Maximo extension might be simple enough that you might decide to offer it as a manual update to a customer. You provide the script and the instructions to run it.

For example, if you created a simple script that added a new column, BPAAA_MAINTCOST, to the ASSET table, then the following process might be used to create the script and run it:

  1. Create a new directory that is named bpaaa under tools\maximo\en\.

  2. Create a new file that uses a .dbc extension, such as bp_add_cost_to_asset.dbc.

  3. Add your instructions to the script.

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE script SYSTEM "script.dtd">
 <script author="bpaaa" scriptname="bp_add_cost_to_asset">
     <description>Adds Maintenance Cost to the Asset</description>
     <statements>
         <add_attributes object="ASSET">
             <attrdef
               attribute="BPAAA_MAINTCOST"
               title="Maintenance Cost"
               maxtype="AMOUNT"
               remarks="Maintenance Cost for the Asset"
               persistent="true"
               required="false"/>
         </add_attributes>
     </statements>
 </script>
  1. Run the script

 > cd tools\maximo\internal
 > runscriptfile.bat -cbpaaa -fbp_add_cost_to_asset

The runscriptfile command takes the following parameters:

  • -c identifies a directory under the tools\maximo\en directory.

  • -f is the name of the script, without the .dbc file extension, that you want to run from the specified directory

In the example, you likely noticed that bpaaa was used as the name of the directory, and it was used as a prefix to the name of the field that were adding to the ASSET table. It is customary for a Business Partner to prefix their scripts and additions with a common prefix so that it becomes clear that this extension is not a part of the out-of-the-box Maximo installation.

In this example, bpaaa was simply "Business Partner" shortened to bp and followed by a 3-character identifier, aaa, that was used as the business partner identifier.

After you run the script, if it was successful, you see the following output: `bash Log file: MXServer_RUNSCRIPT_bp_add_cost_to_asset.log RunScript complete: Successful Checking for columns missing from E-Audit tables. Found no columns missing. `

If the script failed, you can look in the tools\maximo\log\MXServer_RUNSCRIPT_bp_add_cost_to_asset.log file to determine what went wrong.

2.2. Add-on scripts

Your Maximo enhancement might include multiple scripts, and those scripts are likely created, iteratively over your development cycle. Each script contains instructions on the changes that you need to make to the Maximo environment. Each script is numbered sequentially, and they are processed in order. The main reason to use the add-on script process is so that your scripts can be processed and run as part of the Maximo updatedb command.

The add-on process is a little stricter than the standalone scripting process. It requires that you provide a product XML file that contains information about your add-on. This information is used by the updatedb command to determine from where to run your scripts and which scripts need to be run.

Creating an add-on is not a complex process. It involves the following steps:

  1. Create a product XML file and specify the required information.

  2. Create a scripts directory and add your DBC files.

  3. At the end of a development release cycle, update your product XML file with information about your scripts.

2.2.1. The product XML file

The product xml file is a uniquely-named XML file in the applications/maximo/properties/product/ directory. For example, you might name your file bpaaa_product1.xml.

<?xml version="1.0" encoding="UTF-8"?>
<product>
	<name>MyCompany Inc. Cool Product</name>
	<version>
		<major>7</major>
		<minor>6</minor>
		<modlevel>0</modlevel>
		<patch>0</patch>
		<build>20171131-1200</build>
	</version>
	<dbmaxvarname>BPAAAP1</dbmaxvarname>
	<dbscripts>bpaaa_product1</dbscripts>
	<dbversion>V7600-01</dbversion>
	<lastdbversion>V7600-00</lastdbversion>
</product>

The version element can be any version you want. Although it is recommended that start your version at the Maximo version that you are targeting. This version numbering is not validated, it just serves as reminder of the lowest version of Maximo Asset Management that your add-on supports. You can start your version at 1.0.0.0 if you prefer.

The dbmaxvarname element is a MAXVAR id that will be created to store the last script number that was processed for your add-on. The updatedb command uses this information to determine the next script to run.

The dbscripts element is a directory, which is located in tools\maximo\en\, where all your scripts are located.

The dbversion element specifies the last script in your script directory. In this example, the most current script in the tools\maximo\en\bpaaa_product1 directory is V7600_01.dbc, which implicitly shows that the add-on has only one script, because script numbering starts at 1.

The lastdbversion element must initially start with the script number -00, such as V7600-00. The lastdbversion element is also used to specify upgrades.

Pay special attention to how script version are specified in the dbversion and lastdbversion elements. On the file system, scripts look like V7600_01.dbc, but when scripts are referenced in the dbversion and lastdbversion elements, the .dbc extension is not used and you must use - (dash) instead of _ (underscore).

After you have a product XML file, you can continue to the next step and start adding scripts.

2.2.2. Adding scripts

Scripts are sequential. Script names also must start with the letter V, in uppercase, followed by the values that are specified in the major,minor,modlevel, and patch fields in the product XML, followed by an _ character, followed by the sequential script number, and ending with the .dbc extension.

For example, V7600_05.dbc assumes that this script is part of of our 7.6.0.0 release and that four other scripts precede this one.

The first script in every new version is numbered as 01, so the first script in 7.6.0.0 is named`V7600_01.dbc`

After you have a script in your scripts directory, and you updated your product XML to reflect that script, you can run the updatedb command, and your script will be processed.

Some things to understand about the updatedb command:

  1. The updatedb command will not rerun scripts. After script V7600_01.dbc is processed successfully, then the updatedb command will never run that script again.

  2. If there are gaps in your scripts, for example, if you are missing a sequential number, then the updatedb command will fail.

  3. You can add empty scripts. If you find a script gap, you can add an empty script.

  4. While developing, you can continue to add statements to existing dbc scripts, but the updatedb command will not rerun them, so if you add statements, you must use runscriptfile to load those changes.

  5. After a set of dbc scripts are released to a customer, you can never modify those scripts, because those changes will never get run by the updatedb command. After scripts are released, changes need to be put in newly numbered scripts.

  6. Maximo Asset Management cannot be running when you try to run the updatedb command.

After you have a defined product XML file and at least one script in your scripts directory, you can run the updatedb command.

> cd tools\maximo
> updatedb.bat

If you look in the output, you’ll see references to your scripts being processed.

Product: MyCompany Inc. Cool Product updatedb process starts ...
BPAAAP1: V7600-0, Current release DB build: V7600-01, Last release DB build: V7600-00
Database script  update in progress, please wait..........
Current version :V7600-0
Updating To     :V7600-01
Script Update complete: Successful
Product: MyCompany Inc. Cool Product extension update  starts...
Product: MyCompany Inc. Cool Product updatedb process ends...

If you run the updatedb command a second time, without adding new scripts and without updating the dbversion element in your product XML file, then, nothing will happen, and the output will reflect that.

Product: MyCompany Inc. Cool Product updatedb process starts ...
BPAAAP1: V7600-1, Current release DB build: V7600-01, Last release DB build: V7600-00
Product: MyCompany Inc. Cool Product extension update  starts...
Product: MyCompany Inc. Cool Product updatedb process ends...

For testing and development, you can bypass running the updatedb command and simply run and rerun your script by using the runscriptfile command. For example, to run or rerun script 01, use the following commands:

> cd tools\maximo\internal
> runscriptfile.bat -cbpaaa_product1 -fV7600_01

When you add new scripts to your product directory, you need to update the dbversion element in the product XML file to match the most current scripts in your directory. If you add new scripts and you do not update dbversion, and you run the updatedb command, then those newly-added scripts are not processed. For this reason, it is recommended that as a matter of process, when you add a new script, you also update the your product XML file at the same time.

After running the updatedb command, you can check the Maximo System Information, and you will see your product listed there, and you will see the last script that was processed by your product. For example, the following information is shown if you ran the scripts that are included here.

MyCompany Inc. Cool Product 7.6.0.0 Build 20171131-1200 DB Build V7600-01

In that line, from the system information, you can see your product’s name, version, build date, and last script, all of which comes from your product XML file.

2.2.3. Extending Base Maximo Objects

There are cases where an add-on will need to extend a base Maximo object to inject its own business logic into an object. While in most cases, for a simple add-on we encourage you to use Automation Scripting to achieve this, there are times when you may not achieve what you want, and you will need to write your logic in Java.

The updatedb process, along with your product.xml allows for these cases. You specify your extensions directly in the product.xml.

For example, your product.xml could include the following:

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <name>MyCompany Inc. Cool Product</name>
    <version>
        <major>7</major>
        <minor>6</minor>
        <modlevel>0</modlevel>
        <patch>0</patch>
        <build>20171131-1200</build>
    </version>
    <dbmaxvarname>BPAAAP1</dbmaxvarname>
    <dbscripts>bpaaa_product1</dbscripts>
    <dbversion>V7600-01</dbversion>
    <lastdbversion>V7600-00</lastdbversion>
    <extensions>
        <mbo objectname='PM' extends='psdi.app.pm.PM'>bpaaa.pm.CustPM</mbo>
        <class extends='psdi.app.pm.PMRemote'>bpaaa.pm.CustPMRemote</class>
        <mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpaaa.pm.CustPMSet</mboset>
        <class extends='psdi.app.pm.PMSetRemote'>bpaaa.pm.CustPMSetRemote</class>
        <field objectname='PM' attributename='JPNUM' extends='psdi.app.pm.FldPMJpnum'>bpaaa.pm.CustFldPMJpnum</field>
        <service servicename='PM' extends='psdi.app.pm.PMService'>bpaaa.pm.CustPMService</service>
        <bean presentation='PM' controlid='pm_table' extends='psdi.webclient.beans.pm.PMAppBean'>psdi.webclient.beans.bpaaa.pm.CustPMAppBean</bean>
    </extensions>
</product>

In each of these extensions, you are extending a base Maximo object with your own logic. It is extremely important to understand what is happening here, so that you can get predictable results with your extensions.

While you are extending a core object, so can other products. You cannot do multiple inheritance with Java, so, in Maximo, changes are made to the classes to ensure that all product add-ons end up being used. It is also important to note that the order in which your code will be run, will depend directly on the order that your product.xml is processed, which is discussed in more detail in the Understanding the updatedb lifecycle section.

To help clarify this, consider that there are 3 add-ons, bpaaa_product1, bpbbb_product1, bpccc_product1 and they define the following extensions respectively in their own product xml files.

bpaa_product1.xml

<mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpaaa.pm.CustPMSet</mboset>

bpbbb_product1.xml

<mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpbbb.pm.CustPMSet</mboset>

bpccc_product1.xml

<mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpccc.pm.CustPMSet</mboset>

updatedb will process each file, and in the end, each file will be modified such that

 bpaaa.pm.CustPMSet extends psdi.app.pm.PMSet
 bpbbb.pm.CustPMSet extends bpaaa.pm.CustPMSet
 bpccc.pm.CustPMSet extends bpbbb.pm.CustPMSet

And, updatedb will update the metadata for PM so that when it is loaded, it will use bpccc.pm.CustPMSet as its primary implementation class.

This process is the same for all extension objects. i.e., The classes are modified in a predicable order, and the Maximo metadata is updated to ensure that the last class extended is used as the primary implementation, which ensures that all extension code is processed.

2.2.4. Script best practices

  • Group structural changes together in the same script.

  • Update the version and build date with each release.

  • Don’t modify a script after it is released to a customer.

2.2.5. Understanding the updatedb lifecycle

The updatedb command starts a script processing engine. Understanding how scripts are processed can reduce problems and help troubleshooting when problems occur.

  1. The updatedb command will run all scripts in en\script first. These scripts are for Maximo Asset Management, and all these scripts run for ALL versions of Maximo Asset Management before any add-on scripts are processed.

  2. The updatedb command will look at the product add-ons in the product directory and process them in alphabetical order.

  3. If a product XML file has a depends element, then the updatedb command will process that product dependency first.

  4. When the updatedb command processes a product directory, all scripts are processed in that directory, for all versions, before the command moves on to the next product.

3. DBC Technical Reference

4. Feedback

Please help us improve this DBC documentation by completing this short survey.