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 or change system properties
Add or change Maximo variables
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:
Standalone scripts that you manage and run manually
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:
Create a new directory that is named
Create a new file that uses a .dbc extension, such as
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>
Run the script
> cd tools\maximo\internal > runscriptfile.bat -cbpaaa -fbp_add_cost_to_asset
runscriptfile command takes the following parameters:
-cidentifies a directory under the
-fis the name of the script, without the
.dbcfile 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
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:
Create a product XML file and specify the required information.
Create a scripts directory and add your DBC files.
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
<?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>
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
22.214.171.124 if you prefer.
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.
dbscripts element is a directory, which is located in
tools\maximo\en\, where all your scripts are located.
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.
lastdbversion element must initially start with the script number
-00, such as
lastdbversion element is also used to specify upgrades.
Pay special attention to how script version are specified in the
lastdbversion elements. On the file system, scripts look like
V7600_01.dbc, but when scripts are referenced in the
lastdbversion elements, the
.dbc extension is not used and you must use
- (dash) instead of
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
patch fields in the product XML, followed by an
_ character, followed by the sequential script number, and ending with the
V7600_05.dbc assumes that this script is part of of our
126.96.36.199 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
188.8.131.52 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
updatedbcommand will not rerun scripts. After script
V7600_01.dbcis processed successfully, then the
updatedbcommand will never run that script again.
If there are gaps in your scripts, for example, if you are missing a sequential number, then the
updatedbcommand will fail.
You can add empty scripts. If you find a script gap, you can add an empty script.
While developing, you can continue to add statements to existing
dbcscripts, but the
updatedbcommand will not rerun them, so if you add statements, you must use
runscriptfileto load those changes.
After a set of
dbcscripts are released to a customer, you can never modify those scripts, because those changes will never get run by the
updatedbcommand. After scripts are released, changes need to be put in newly numbered scripts.
Maximo Asset Management cannot be running when you try to run the
After you have a defined product XML file and at least one script in your scripts directory, you can run the
> 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 184.108.40.206 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.
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,
bpccc_product1 and they define the following
extensions respectively in their own
product xml files.
<mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpaaa.pm.CustPMSet</mboset>
<mboset objectname='PM' extends='psdi.app.pm.PMSet'>bpbbb.pm.CustPMSet</mboset>
<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
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
updatedb command starts a script processing engine. Understanding how scripts are processed can reduce problems and help troubleshooting when problems occur.
updatedbcommand will run all scripts in
en\scriptfirst. 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.
updatedbcommand will look at the product add-ons in the product directory and process them in alphabetical order.
If a product XML file has a
dependselement, then the
updatedbcommand will process that product dependency first.
updatedbcommand 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
Please help us improve this DBC documentation by completing this short survey.