Maximo SOAP

I’ve been working with an old instance of Maximo recently integrating via SOAP web services.  A number of speed bumps along the way made things rather slow-going but I just got things working.  Time to take some notes.  The requirements are to interface with the NMS to push status changes into a new object in Maximo, create new INCIDENT objects when status changes to bad, and add WORKLOG objects to existing INCIDENTS related to the device that generated the update status.

I started with creating the new object in Maximo under Database Configuration.  We’ll have zero or more NMSSTATUS objects for a given LOCATIONS object.  We’ll have field to store the name of the check, the status, and a timestamp.

  • Setting “Level” to “OrgSite” requires us to add SITEID and ORGID attributes.
  • Make sure you leave “Add Rowstamp?” checked.  Otherwise, we can’t update the objects.
  • Attributes:
    • NMSSTATUSID – Integer, default ID, autonumber, clear Primary Column
    • DESCRIPTION – I removed this after unchecking “Long Description Owner”
    • LOCATION – Same As LOCATIONS.LOCATION, required, Primary Column 1
    • SITEID – Same as SITE.SITEID, required, Primary Column 2
    • ORGID – Same as ORGANIZATIONS.ORGID, required, Primary Column 3
    • CHECK – String, name of the check, Primary Column 4
    • UPDATEDATE – DateTime
    • STATUS – SmallInt, uses our NMSSTATUS domain
  • Indexes
    • NMSSTATUS_IDX – Clustered, Unique on LOCATION, SITEID, ORGID, and CHECK
    • others will be automatically created
  • Apply the database changes

Next, I created some relationships on LOCATIONS:

  • NMSSTATUS connecting NMSSTATUS objects
    • where “location=:location and siteid=:siteid and orgid=:orgid
    • Pretty obvious
  • NMSINCIDENT connecting INCIDENT objects
    • where “historyflag=:no and exists (select 1 from multiassetlocci where recordkey=incident.ticketid and recordclass=incident.class and location=:location and siteid=:siteid and orgid=:orgid)“.
    • This connects to active INCIDENT objects that have the current location listed in any of their MULTIASSETLOCCI records since we want to know about any that are related to the location, not just those that list it as the primary location.

Next, the NMSLOC object structure:

  • LOCATIONS
  • LOCATIONS/NMSSTATUS – using the NMSSTATUS relationship created above
  • LOCATIONS/INCIDENTS – using the NMSINCIDENT relationship created above
  • LOCATIONS/INCIDENTS/WORKLOG

Next, publish the object structure as a web service.

We can now query locations and the related records with a SOAP request like so:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope 
 soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:max="http://www.ibm.com/maximo" 
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soap:Body>
   <max:QueryNMSLOC maxItems="1" rsStart="0" uniqueResult="0">
     <max:NMSLOCQuery>
       <max:LOCATIONS>
         <max:LOCATION operator="=">RTR-123</max:LOCATION>
         <max:SITEID operator="=">HQ</max:SITEID>
         <max:ORGID operator="=">ACME</max:ORGID>
       </max:LOCATIONS>
     </max:NMSLOCQuery>
   </max:QueryNMSLOC>
 </soap:Body>
</soap:Envelope>

We can create or update one of our NMSSTATUS objects like so:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope 
 soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:max="http://www.ibm.com/maximo" 
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soap:Body>
   <max:SyncNMSLOC>
     <max:NMSLOCSet>
       <max:LOCATIONS action="Change">
         <max:LOCATION>RTR-123</max:LOCATION>
         <max:SITEID>HQ</max:SITEID>
         <max:ORGID>ACME</max:ORGID>
         <max:NMSSTATUS>
           <max:LOCATION changed="0">RTR-123</max:LOCATION>
           <max:SITEID changed="0">HQ</max:SITEID>
           <max:ORGID changed="0">ACME</max:ORGID>
           <max:CHECK changed="0">UPTIME</max:SERVICE>
           <max:STATUS>4</max:STATUS>
           <max:UPDATEDATE>2016-10-17T14:35:51Z</max:UPDATEDATE>
         </max:NMSSTATUS>
       </max:LOCATIONS>
     </max:NMSLOCSet>
   </max:SyncNMSLOC>
 </soap:Body>
</soap:Envelope>

This took far too long to figure out but it’s working now.