IBM Support

Maximo - Adding meter readings using the REST API

Technical Blog Post


Abstract

Maximo - Adding meter readings using the REST API

Body

How do you post meter readings to Maximo using the Rest API?  Which object structure should I use?  Do I need any http headers?

 

There is more than one way to use the Maximo Rest API to update Asset meter readings.  So, what is the correct way?

 

In Maximo 7.6, an out-of-the-box object structure was added to the product for the purpose of updating meter readings.  That object structure is called MXMETERDATA.  You can use this object structure if you wish to add meter readings using the Rest API.  Below you will find an example of an asset, and its meter using maxdemo data.

 

I used ASSET 11450, and assigned the RUNHOURS (continuous) and 0-PRESSURE (gauge) meters to it.  See the image below:

 

image

 

For the examples that follow, I will be adding RUNHOURS meter readings.  From the screen shot above, we can see the date and time of the last meter reading.  Our meter reading data will need to ensure that the new reading date is always ahead of the last reading date.

 

I used Soap UI for testing.  Any rest client should provide the same capabilities.  To do this:

Create a new rest project, and set the URI to point to your MXMETERDATA object structure:

 

e.g.  http://maximohost:port/maximo/oslc/os/mxmeterdata

 

When you review the Request form of this project, you will see that you can add headers, parameters, change the http method, and a body field to add your json data.

 

What headers to you need when you are using this object structure?  Since this object structure is based on non-persistent objects in Maximo, the default default method cannot be used and an x-method-override header is required, with value of SYNC. 

 

e.g. x-method-override=SYNC

 

If the above step is missed, you will receive an error trying to post the meter reading like that shown below:

 

{"Error": {
   "message": "BMXAA1407E - The ASSETMETER object cannot be added because it already exists in the application. An integration message cannot create an object that already exists.",
   "statusCode": "400",
   "reasonCode": "BMXAA1407E",
   "extendedError": {"moreInfo": {"href": "http://maxany-belinda.swg.usma.ibm.com:9080/maximo/oslc/error/messages/…;}}
}}

 

Authentication:

There are three different types of authentication available in Maximo.  Depending on which you are using, you will need to create the appropriate header:

MAXAUTH (native authentication)

BASIC

FORM

 

See here for details:

https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html#_form_authentication

 

Parameters:

In my environment, I am using native authentication.  For simplicity, rather than using MAXAUTH, I used rest parameters to pass the userid and password for testing.  Those parameters are:

_lid=username

_lpwd=password

 

In a production environment, use a MAXAUTH header to prevent the userid and password from being exposed in the URL.

 

The third parameter to add is:

lean=1

 

This parameter removes the namespace requirement from JSON.  If this parameter is missing, a namespace will be required for each attribute in your json body.  It is recommended that you use this parameter for all API requests.

 

Body:

Below is an example of how I will add a meter reading to assetnum 11450:

 

{
"siteid":"BEDFORD",
"assetnum":"11450",
"metername":"RUNHOURS",
"newreading":350,
"newreadingdate":"2019-07-24T11:55:20",
"orgid":"EAGLENA",
"inspector":"WILSON"
}

 

There will be different requirements for different meter types.  Now that I have submitted the request, you can see the result in the following image:

image

 

Note that the response will be HTTP 200, no-content is returned to the client which is the correct response, and the post is successful.

In Maximo, the meter reading history shows my last meter reading for RUNHOURS matches the content in my json body:

image

 

 

Now that this has all be said, you should be able to successfully update your meter readings using this object structure.  Another way to update meter readings for assets (although a bit more complicated), is to use the MXASSET object structure, and send updates to the child ASSETMETER object.

 

See the following for detailed information, chapter 11 - Creating and Updating Resources

https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html

 

An example of what it would look like including the required headers is shown below (where the number 35 represents the ASSETID value stored in the ASSET table for ASSETNUM 11450.

 

POST /oslc/os/mxasset/35
x-method-override: PATCH
patchtype: MERGE
properties:*

{
       “assetmeter”:[
{
                “metername”:”RUNHOURS”,
                “linearassetid”:0,
    “newreading”:”351”,

    "newreadingdate":""2019-07-26T11:55:20"
}
     ]
}

 

In this scenario,  you would first need to know the URI of the asset.  However, I have not been able to successfully use this method.

 

Feel free to try these out.  If you run into any problems, please contact Maximo Support for assistance.

 

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSLKT6","label":"IBM Maximo Asset Management"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

UID

ibm11111389