Maximo Open Forum

Expand all | Collapse all

Maximo JSON API: An IoT Example

  • 1.  Maximo JSON API: An IoT Example

    Maximo Certified
    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 15 days ago
    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

    Maximo Certified
    Posted 14 days ago
    Can you include the message payload you're using?

    Thanks,

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



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

    Posted 12 days ago
    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 12 days ago
    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 12 days ago
    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

    Maximo Certified
    Posted 8 days ago
    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 8 days ago
    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 14 days ago
    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
    ------------------------------