Maximo Open Forum

 View Only
Expand all | Collapse all

Maximo JSON API: An IoT Example

  • 1.  Maximo JSON API: An IoT Example

    Posted 06-08-2020 16:56

    I’ve had a lot of conversations recently with folks attempting to implement more Condition Monitoring within their organization. The benefits of shifting from time-based maintenance to condition- or use-based maintenance are well documented and very real. However, making that shift involves a fair amount of planning, analysis, and technology. This article will show an example of how to bridge a small portion of the technology gap; specifically, we will focus on creating meter readings in Maximo via the JSON API available in Maximo 7.6.0.2 and higher.

    Meter readings are the heart of how Condition Monitoring is implemented in Maximo. They represent a piece of data at a point in time associated with an asset. This data could be related to the asset’s condition such as temperature, pressure, voltage, etc. This data could also be related to the asset’s usage such as an odometer reading, the number of cycles of the asset, etc. Lastly, the data could be based on a simple value list such as Pass/Fail, Open/Closed, Blowing / Not Blowing, etc.

    To create a new meter reading via Maximo’s JSON API, let’s start with an example:

    POST http://mxapprove.a3jgroup.com/maximo/oslc/os/mxasset/_QkVERk9SRC8xMTQ1MA==
    maxauth: c21pdGg6c21pdGgx
    Content-Type: application/json
    properties: *
    x-method-override: PATCH
    patchtype: MERGE
    {
        "assetmeter": [
            {
                "metername": "O-PRESSUR",
                "linearassetmeterid": 0,
                "newreading": "4900"
            }
        ]
    }

    Let’s look at this part-by-part. First, we start with the HTTP POST itself.

    POST /maximo/oslc/os/mxasset/_QkVERk9SRC8xMTQ1MA==

    This message needs to be an HTTP POST (not HTTP GET). The http://mxapprove.a3jgroup.com/maximo portion of the URL is your Maximo environment’s URL. Substitute that for your own environment’s URL. The /oslc part of the path represents the usage Maximo JSON API. The /os part of the path tells the API that the next part of the path (in our example is /mxasset) will be an Object Structure in Maximo. Finally, the /_QkVERk9SRC8xMTQ1MA== represents a unique identifier for an Asset record that can be referenced in the MXASSET Object Structure. This identifier can be found be querying for the asset using an HTTP GET to the same MXASSET Object Structure, or it can be derived by base64 encoding the asset’s SITEID + “/” + ASSETNUM and prefixing that string with an underscore (“_”) character.

    Next are the various headers.

    maxauth: c21pdGg6c21pdGgx
    Content-Type: application/json
    properties: *
    x-method-override: PATCH
    patchtype: MERGE

    The maxauth header represents the credentials that are being used to broker the transaction. The value is a base64 encoded string of the format USERNAME + “:” PASSWORD. In an LDAP environment, switch the maxauth header to Authorization and prefix the string “Basic ” to the base64 encoded value. The Content-Type header tells the HTTP request that the body of the message will be in JSON format. The properties header tells the request which fields from the MXASSET Object Structure should be sent back in the HTTP response, with the * character representing all fields in the object structure. The x-method-override header with a value of PATCH tells Maximo that this will be an update to the asset record, and the patchtype header with a value of MERGE tells Maximo to add a new record while keeping the other ASSETMETER records. Without that header, the integration will replace all of the ASSETMETER records with the list in the message.

    Next is the body of the message.

    {
        "assetmeter": [
            {
                "metername": "O-PRESSUR",
                "linearassetmeterid": 0,
                "newreading": "4900"
            }
        ]
    }

    Note that we don’t need any identifying information about the asset in the message body, such as the ASSETNUM or SITEID. This is because we are required to specify the unique identifier in the URL string. We specify the assetmeter key as an array of meters associated with the asset. For this example, we are only updating a single meter against the asset (Outlet Pressure). In our object, we specify the Meter Name and New Reading value. The linearassetmeterid key with a value of 0 is necessary due to that field being part of the unique identifier on the ASSETMETER table. Values such as the New Reading Date and Inspector will default based on the current date and the logged in user credentials, but can also be specified explicitly in the message.

    Please feel free to leave questions or comments below. Good luck in your IoT journey!

    See original post


    #Integrations

    ------------------------------
    Alex Walter
    A3J Group LLC
    ------------------------------


  • 2.  RE: Maximo JSON API: An IoT Example

    Posted 09-07-2021 10:59
    Hi Alex,

    I hope you can help me here. I am trying to load item data from SAP system using JSON Mapping app but for some reason, i am getting below error message.  I created ITEM object and use it inJSON mapping application and mapp JSON fields with Item object fields but when i try to post message using POSTMAN, i am getting below error.  I am using MXINTADM account to insert data into ITEM object using POSTMAN. 


    CNTR0020E: EJB threw an unexpected (non-declared) exception during invocation of method "maxSecureProcessExternalDataSync" on bean "BeanId(MAXIMO#mboejb.jar#enterpriseservice, null)". Exception data: javax.ejb.EJBException: nested exception is: psdi.util.MXSystemException: BMXAA4214E - An unknown error has occurred. Please contact your system administrator for assistance. Gather the logs from the <HOME> directory and determine where and why the error occurred.
    null
    Error 500: BMXAA4214E - An unknown error has occurred. Please contact your system administrator for assistance. Gather the logs from the &lt;HOME&gt; directory and determine where and why the error occurred.
    null
    SRVE0293E: [Servlet Error]-[IntegrationMaximoServlet]: com.ibm.ws.webcontainer.webapp.WebAppErrorReport: BMXAA4214E - An unknown error has occurred. Please contact your system administrator for assistance. Gather the logs from the &lt;HOME&gt; directory and determine where and why the error occurred.
    null
    [ERROR] [MXServer] [] Processing failed for XXX_IN_SAPITEM. The object structure is 1. The primary object is ITEM. The key is 000000000006000108~ITEMSET1.null

    Do you know how to resolve this issue? I appreciate any help or guidance you provide to fix this issue.

    Thanks


    ------------------------------
    Hardik PAtel
    ------------------------------



  • 3.  RE: Maximo JSON API: An IoT Example

    Posted 09-08-2021 08:55
    Can you include the message payload you're using?

    Thanks,

    ------------------------------
    Alex Walter
    A3J Group, LLC
    ------------------------------



  • 4.  RE: Maximo JSON API: An IoT Example

    Posted 09-10-2021 11:49
    Alex - I was able to resolve this issue. It was known bug in Maximo 7.6.1.1 version. Here is the link.

    https://www.ibm.com/support/pages/apar/IJ21447

    Now I am able to process item data into following objects - Item, Inventory, INVCost and INVBalances. One issue i am having is Current balance is not updating on INVBLANCES object. I am inserting data into INVBLANCES.CURBAL and INVBALANCES.PHYSCOUNT. Both fields are mapped into JSON Mapping.  Physical count field is updating but not curbal field. 

    OWNERSYSID and SENDERSSYSID are same and   INV collaboration switch is set to 0. I ran following statement to confirm that. 


    select * from mxcollab where pcid ='INV' and got below data.

    EXT             EXT               INV      1
    EXT             THISMX       INV       0
    THISMX      EXT              INV       1

    Can you please help?


    ------------------------------
    Hardik PAtel
    ------------------------------



  • 5.  RE: Maximo JSON API: An IoT Example

    Posted 09-10-2021 16:28
    Actually i enabled logging and found below update statement  

    update invbalances set sendersysid=?,physcntdate=?,lotnum=?,binnum=?,ownersysid=?,reconciled=?,physcnt=?,conditioncode=? where invbalancesid=? and rowstamp=?


    and i dont see invbalances.curbal field eventhough i have mapped SAP quantity field with INVBALANCES.CURBAL field in JSON mapping app.
    Checked object structure and i have not excluded any field from invbalances object.

    ------------------------------
    Hardik PAtel
    ------------------------------



  • 6.  RE: Maximo JSON API: An IoT Example

    Posted 09-10-2021 16:32
    Nevermind... i fixed curbal item field issue too. That field was restricted under inbound setting restrictions in object structure by default.

    ------------------------------
    Hardik PAtel
    ------------------------------



  • 7.  RE: Maximo JSON API: An IoT Example

    Posted 09-14-2021 11:16
    Things that are restricted are typically not intended to be set directly. Doing so might cause critical Maximo logic to not fire which could lead to data integrity issues. For example, adjusting the balance needs to generate a financial transaction as the inventory has either grown or decreased in value.

    When attributes are restricted, they are typically managed by an inbound processing class that will move the value from a field like STATUS or CURBAL and execute the proper logic. For example, the processing class psdi.iface.app.invbalances.MaxInvBalancesProcess provided for MXINVBAL will look to see if CURBAL is set and execute the proper update. I would ensure that your object structure you're using for INVBALANCES references this processing class and make the attribute restricted again and verify it works.

    I recommend looking for an out of the box object structure and duplicating it for your use case to ensure that you have the appropriate processing classes. When one doesn't exist out of the box, I typically try to follow how the Maximo UI does something similar. For example, if you're adjusting the balance you set the NEWCURBAL non-persistent attribute. You probably could include that non-persistent attribute and use that as well to get the balance adjustment you expect.

    ------------------------------
    Steven Shull
    IBM
    ------------------------------



  • 8.  RE: Maximo JSON API: An IoT Example

    Posted 09-14-2021 13:31
    I second Steven's comment. I have done inventory adjustment with CSV files before which is essentially the same if done via RESST API. 

    Current Balance is meant to adjust automatically based on matusetrans or invtrans table. the correct way would be to record/ process these and the current balance gets adjusted automatically. 

    Megha

    ------------------------------
    Megha Tatiya
    ------------------------------



  • 9.  RE: Maximo JSON API: An IoT Example

    Posted 09-08-2021 09:23
    Based on the last error line "~ITEMSET1.null" , it seems itemnum field is missing in your mapping.
    If you may provide the data posted and the mapping you configure in JSON map.

    Regards,


    ------------------------------
    Amir Nadi
    CCC
    ------------------------------



  • 10.  RE: Maximo JSON API: An IoT Example

    Posted 01-12-2022 13:28
    Edited by Prashanth C 01-12-2022 14:07
    Hi,

    I am trying to update the meter readings using above method(MXASSET). The response is successful with 200 OK, but the readings are not updating as expected. For the same meter, I am able to update the readings using MXMETERDATA OS. Any suggestions?

    -Thanks

    ------------------------------
    Prashanth C
    ------------------------------



  • 11.  RE: Maximo JSON API: An IoT Example

    Posted 01-12-2022 13:56
    Make sure that ASSETMETER object is part of the object structure you're using.

    I have to say though that the MXMETERDATA object structure method is perfectly fine and may even be preferable, especially if you're also submitting meter readings for operating locations.

    We can give you more details or thing to try if you include the URL, headers, and message payload that you're using to generate those results.

    Thanks,

    ------------------------------
    Alex Walter
    A3J Group, LLC
    ------------------------------



  • 12.  RE: Maximo JSON API: An IoT Example

    Posted 01-12-2022 14:04
    Edited by Prashanth C 01-12-2022 14:06
    Thanks for quick response.

    Here is the URL: http://testinstance.com/maximo/oslc/os/mxasset/_Uk9XNEFWR0JBL1JPV0FO

    Here are Headers:

    Here is message:


    -Thanks.

    ------------------------------
    Prashanth C
    ------------------------------



  • 13.  RE: Maximo JSON API: An IoT Example

    Posted 01-12-2022 17:44
    All of that looks great. Please confirm that the TEST meter is an active meter on the ROW4AVGBA asset, that the ASSETMETER object is part of the MXASSET object structure, and that you're performing an HTTP POST. Outside of that... I'm not sure what else might be causing this behavior.

    ------------------------------
    Alex Walter
    A3J Group, LLC
    ------------------------------



  • 14.  RE: Maximo JSON API: An IoT Example

    Posted 01-12-2022 18:59
    Edited by Prashanth C 01-12-2022 19:20
    Hi,

    Its an active meter associated with that Asset. I am performing HTTP POST, and the MXASSET object structure has ASSETMETER included.

    ------------------------------
    Prashanth C
    ------------------------------



  • 15.  RE: Maximo JSON API: An IoT Example

    Posted 01-13-2022 08:39
    Can you confirm that you have the ?lean=1 on the end of your URL? Otherwise it'll be using the OSLC structure which is different.

    Also, can you confirm that on MXASSET that the NEWREADING field is included? Because it's a non-persistent attribute, if it's not included in the object structure the API won't throw an error. The REST API ignores attributes that are incorrect or not included.

    ------------------------------
    Steven Shull
    IBM
    ------------------------------



  • 16.  RE: Maximo JSON API: An IoT Example

    Posted 01-13-2022 08:47
    Great point about the lean=1 query string parameter. That should be included in the original article. Most likely, I had used the lean=1 query string parameter on the login call and the setting was retained for future calls in the same session. I'll update the article to include that.

    ------------------------------
    Alex Walter
    A3J Group, LLC
    ------------------------------



  • 17.  RE: Maximo JSON API: An IoT Example

    Posted 01-13-2022 09:28
    Edited by Prashanth C 01-13-2022 11:27
    I found the issue. It works when I use the POST URL with hostname and port number (http://myinstance:<port>/), but it fails to update the readings with DNS name (Cluster URL).

    Any suggestions?

    Regrading your question, MXASSET objects structure includes attribute NEWREADING, and my url also includes lean=1 parameter.

    -Thanks.


    ------------------------------
    Prashanth C
    ------------------------------



  • 18.  RE: Maximo JSON API: An IoT Example

    Posted 01-13-2022 15:57
    Do I need to include any additional Headers/Params to POSTMAN to make it work? Any suggestions?

    -Thanks.

    ------------------------------
    Prashanth C
    ------------------------------



  • 19.  RE: Maximo JSON API: An IoT Example

    Posted 01-13-2022 17:44
    I can't explain why the cluster URL wouldn't work and the JVM would unless the request isn't routing to Maximo. Are you sure that cluster URL is routing to the JVMs you think it is? 

    Change something on the asset description and include the header "properties" with "*" and see what gets returned when you make the request. If it's making it to Maximo you should get a JSON response with the values. 


    In scenarios where you're building an interactive application that pages through (IE follows the next/previous page embedded in a GET request), there is a system property (mxe.oslc.webappurl) that controls those URLs by default. So even if you hit it on localhost, it would use what is in that system property by default. If you wanted the URLs to get generated based on the URL you use you can add &relativeuri=1 as a query parameter and it would utilize the same URL that made the request instead of depending on the system property.

    That query parameter wouldn't matter on WO creation scenarios, just when you're getting additional hrefs that you follow in your code.

    ------------------------------
    Steven Shull
    IBM
    ------------------------------



  • 20.  RE: Maximo JSON API: An IoT Example

    Posted 01-14-2022 11:02
    I included a header property with "*", the response includes 200 OK with all the values of asset in JSON format. But the description of asset was not updated. I even tried with parameter "relativeuri=1", but it did not work either.

    -Thanks.

    ------------------------------
    Prashanth C
    ------------------------------



  • 21.  RE: Maximo JSON API: An IoT Example

    Posted 01-18-2022 08:26
    Cluster url mostly will not work if you have mxe.oslc.webappurl / mxe.oslc.restwebappurl etc are not set to your loadbalancer/cluster url but set to individual jvm or localhost etc check that as well

    ------------------------------
    Prashant Bavane
    CTS
    ------------------------------