Maximo JSON API: An IoT Example

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==?lean=1
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==?lean=1

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. The ?lean=1 part of the path allows us to not have to specify namespace prefixes in the body of the request.

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!

Related posts

9 comments

  • Using POSTMAN, I am able to post the data and receive 200. But, the meter readings are not updating as expected. I am bale to update the same meter readings with MXMETERDATA. Any suggestions?

    Thanks-

  • Thanks for this, was playing with python and noticed params needed the ‘spi’ in front? Seems to work now, with API key this way, was unsure if there was a difference. Great trick with the unique identifier!
    ——-
    import config
    import requests
    from requests.packages.urllib3.exceptions import InsecureRequestWarning

    meterread=’100.00′ #your new reading, can put in params to json too
    apikey= ‘apikeyxxxxxxxxxx’

    requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

    host = ‘https:/host_url/maximo’ #dev
    url=’/maximo/oslc/os/mxasset’
    url = host + url #renamed for DEV.Testing

    headers = {
    ‘apikey’: apikey,
    ‘properties’: ‘*’,
    ‘Content-Type’: “application/json”,
    ‘x-method-override’: ‘PATCH’,
    ‘patchtype’: ‘MERGE’
    }
    params = {

    ‘oslc.select’: ‘assetuid’,
    ‘oslc.where’: ‘assetnum=12345’ #return the unique identifier from asset num
    }

    r=requests.get(url, headers=headers, params=params,verify=False)
    x=r.json()
    uniqueid= (x[‘rdfs:member’][0][‘rdf:about’]) #get the unique identifier in the URL string

    url=uniqueid #unique identifier in the URL string.
    params = {

    “spi:assetmeter”: [
    {
    ‘spi:inspector’ : ‘JOEY’,
    ‘spi:newreadingdate’ :’&SYSDATE&’,
    “spi:metername”: “FLOAT”,
    “spi:linearassetmeterid”: 0,
    “spi:newreading”: meterread #from ‘meterread=’100.00′ #your new reading’

    }
    ]
    }
    r=requests.post(url, headers=headers, json=params,verify=False)
    pprint(r.status_code)

    • Alex Walter

      Nice! You can use the lean=1 query parameter to avoid having to include the namespace prefixes.

      In your HTTP GET you can include ‘lean’: ‘1’ in your params object. That should allow you to drop the rdfs: and rdf: prefixes from the initial response. Then you can append a ‘?lean=1’ to the HTTP POST and drop the spi: prefixes from the body of the request.

  • Raphael

    Hello, thank you very much for this!
    Using what you say I’m trying to do a POST to os/mxincident however I’m having troubles just to get a response status = 200.
    I executed this two requests:
    POST: https://host_url//maximo/oslc/os/mxincident/ticketuid I get 400 with the message “oslc#create_on_updateuri”
    POST: https://host_url//maximo/oslc/os/mxincident/ticketid I get 500 with the message “For input string: \”IN41321576\””

    I don’t know what else to try… Do you have an advice to give me, please?

    • Alex Walter

      The issue is the last element in your URL. It needs to be the REST ID of the Incident record you’re trying to update.

      In the article’s example, 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 ASSETNUM + “/” + SITEID and prefixing that string with an underscore (“_”) character.

  • im tryng to post this with postman
    maxrest/oslc/os/mxwomobile/46693?lean=1

    { assetmeter:
    [ { metername: ‘KEBOCORANMINYAK’,
    assetnum: ‘877618’,
    siteid: ‘TND’,
    newreadingdate: ‘2020-08-13T08:43:34’,
    newreading: ‘Bersih’,
    inspector: ‘INSPEKSI.LUWUK’,
    linearassetmeterid: 0 },
    { metername: ‘KONDISIFISIK’,
    assetnum: ‘877618’,
    siteid: ‘TND’,
    newreadingdate: ‘2020-08-13T08:46:30’,
    newreading: ‘Cacat Sirip Major’,
    inspector: ‘INSPEKSI.LUWUK’,
    linearassetmeterid: 0 }]}

    but i get return 400 like this

    {
    “Error”: {
    “reasonCode”: null,
    “message”: “oslc#create_on_updateuri”,
    “statusCode”: “400”
    }
    }

    please help me

    • Alex Walter

      The issue is the last element in your URL. It needs to be the REST ID of the Asset record you’re trying to update.

      In the article’s example, 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 ASSETNUM + “/” + SITEID and prefixing that string with an underscore (“_”) character.

  • mostafa mohamed ragab

    hi
    when i send maximo update through rest api using
    external system,publish channel and end point,
    the json in update be like (contain rowstamp)
    {
    “_id”: “R18867-RAM”,
    “_rowstamp”: “767476799”,
    “description”: “az”,
    “href”: “https:\/\/flsmidth.maximo.com\/maximo\/oslc\/os\/createpr\/_UjE4ODY3L1JBTQ–“,
    “orgid”: “ACC”,
    “pr1”: “QC”,
    “prnum”: “R18867”,
    “siteid”: “RAM”,
    “status”: “NEW”,
    “status_description”: “New PR”
    }

    i need not to add rowstamp, i found proerty called _Urs, but i don’t know how to use till now,
    please help if you know

    • Alex Walter

      For outbound publish channel messages, you should be able to use Maximo’s JSON Mapping application to transform the JSON payload to a format that your external system understands.

Shane

Maximo Analyst

As a recent graduate in computer science and cybersecurity with a CompTIA Sec+ certification, I thrive on learning and embracing emergent challenges head-on. Though new to Maximo, I approach the day to day with determination and enthusiasm. I have been known to be competitive while also being a strong team player. Beyond the realm of technology, I cherish spending time with loved ones, playing video games, doing exercise, and cooking. I am grateful to be where I am and around so many amazing people.

MAS 8

Time to Benefit
Lower Costs
Scalability and Integration
Continuous Upgrades
Easy of Use

Visual Inspection

Accelerate Defect Detection
Flexibility to Train and Deploy
Increase Uptime 24/7 Real Time Monitoring
Better Worker Safety

Monitor

Enterprise Level Data Aggregation
Scaled Operations
AI Deductions
Advanced Root Cause Analysis

Predict

Condition Based Maintenance
Lower Costs
Better Asset Availability
Reduced Risk

Manage

Comprehensive View of Assets
Understand Resource Attributes, Configuration and Relationships
Drill Down View

Health

Improve Reliability
Performance Insight
Better Planning
Clean Data
Optimization – Data, Costs, Risks

Mobility

Boost Productivity
Safer Workplace
Reduce Knowledge Gaps
Avoid Downtime

Digital Twin

Integrate with IoT for Intelligent Asset Management
Measure Health and Performance
Meet Sustainability Goals
Write Your Digital Story – Learn from Data

Dexter

Maximo Analyst

Dexter began his career in the warehouse field. Developing his skills in inventory control, accounts payable, shipping, and receiving, and procurement. While working at Apex he was learning the Maximo system in and out. Eventually learning it so well he taught everyone how to use it. Eventually becoming a system administrator for the Apex site.

A fun fact about Dexter is that he was an Elvis impersonator for 24 years. He enjoys singing, fishing, golf, and playing pool. He's an avid movie buff, most likely you'll find him watching the latest movie.

Chip

Client Relations Specialist

Chip is new to Maximo but has worked for various software companies through his career in both a sales and client relations role. In his spare time, Chip likes to golf, travel and work on projects around the house, especially those with an artistic touch. He is also up for any type of competition whether that be playing cards, board games or recreational sports.

Sarah

Maximo Analyst

Sarah is a recent graduate starting her asset management career. She counts fast learning and determination as key skills that she’s applying to become an Maximo pro! Sarah’s background in IT Services and studies in computer science have strengthened her natural problem-solving skills and desire to help others through technology. In her free time, Sarah enjoys baking, sewing, reading comic books, and building her own video game.

Derrick

Maximo Analyst

Derrick is someone who lives for mental exercise. New challenges spin his problem solving wheels. Defeat is not an option and challenges make him smile. His catch phrase is “I’m an Engineer”. Derrick takes pride in his work. He is a highly self-driven talent when it comes to his interests and programming couldn’t be any higher on this list.

Outside of the office Derricks interests includes cars, motorcycles, and anything generally fast and loud. He stays in the loop on latest in tech, loves gaming and most of all is a die-hard anime fan. Outside of bike night, you are most likely to catch him relaxing in the glow of lights from his PC.

Xavier Galarza

Maximo Analyst

I am a recent graduate who is motivated to learn and develop new skills. I like to challenge myself every day. I want to learn all about Maximo in order to teach others how effective Maximo can be for them. I have a good understanding of the development side and work well with problem solving. I am grateful for the position I am in, I love surrounding myself with great people that are more knowledgeable than me who will help me grow as a person. In my free time I love to play videos games, watch/ play sports and spend time with family. I am a competitive person and believe I am pretty good at all sports.

My other passion is to stream video games I play and connect with others online, I love showing others how to play a certain game or even show them a skill didn’t know existed. I love entertaining others and creating content for others to watch and enjoy.

Courtney LeBlanc

Business Analyst

Courtney is a polished Maximo consultant with over 10 years working in the industry. She has worn many hats including QA Specialist, Trainer, Functional Lead, Project Lead and Business Analyst. A point of great professional pride for Courtney is helping clients meet their needs and realize the power of their investment. Being a part of the process that helps clients learn how to use their system and get the most out of it is a great feeling at the end of the day.

Bob Richardson

Director of Managed Services and Senior Analyst

Bob has led more than 50 (but less than ∞) Maximo projects with top notch client satisfaction – so he must be doing something right. He is a seasoned veteran who heads our operational & managed services team. He is instrumental in developing many of our solutions and holds Maximo certifications in both functional and technical disciplines up to version 7.

Bob might or might not like squirrels. He enjoys traveling with his wife and outdoor activities. He has also been known to spend long hours in his garage contemplating life.

Kelly Nimmo

Director of Products and Senior Analyst

Kelly heads up our product development team and is a senior analyst with more than 11 years EAM/Maximo experience. She is the architect behind our flagship product offering MxMobile. She holds Maximo certifications in both functional and technical disciplines up to Maximo version 7.

In her free time if you don't find her on her boat, fishing and enjoying the beautiful Florida outdoors, then she's probably on the soccer field teaching her nieces and nephews how to do the around the world.

Kim Walter

COO

Kim began her career in Investment Banking in the Biotech and Tech sectors. After leaving banking, she focused on executive strategic development evolving her business building skills. Co-founding A3J Group was a natural fit with the idea of creating a fierce ninja style unit that outperforms all others. In her free time, she is training for her next eventing competition or studying to become a Master of Wine or practicing her tornado kick. She could be with her family hiking or surfing or cooking. But she’s definitely not sitting around doing nothing.

Alex Walter

CIO

Alex brings 18 years of Maximo/EAM consulting experience in Life Sciences, Oil & Gas, Water/Waste Management, Government facilities, and much more. He has been awarded the honor of IBM Champion from 2018-2021, and is the brainchild behind our revolutionary mobile solution MxMobile.

In his free time he buys camping gear, enjoys a good circular saw and spends time with his family hiking, surfing and being outdoors.

Enhancement

• Configuration
• Integration & data loading
• Report improvement
• Screen view & workflow changes

Sustainability

• Report
• Troubleshoot
• Learn
• Teach
• Lead

Change Management

• Advanced systematic improvements
• Tailored procedure implementation
• Script-, report-, and application-level source and document control through Git repository software
• Training on how to document and deploy changes

Monitoring

• Active monitoring of your IBM Maximo system’s heartbeat
• Triggered notifications and support tickets when Maximo is not responding
• Automated Escalations based on the health of various critical background processes.
• Periodic and quarterly scheduled system health checks

System Support & Trouble Shooting

•On Demand Support
•Advanced Troubleshooting
•Access to A3J Group’s Maximo Support Environment to submit trouble tickets
•Directly report bugs, request fixes and enhancements

System Patching & Environment Refreshes

• Tentative, bi-annual feature pack releases from IBM
• Minor patches (defined by the last number in the version model)
,• Quarterly lower environment refreshes

Admin

MxAsk

Create new self-service requests in a wizard-style format, and view the details of their open service requests.

MxApprove

Accept, reject, and reassign assignments, review assigned records, and view your workflow inbox.

MxMobile

A suite of mobile applications designed to integrate with IBM Maximo Asset Management. These apps modernize workflow, expedite inventory processes, reduce time spent on data entry, and more.

Workflow

MxMeter

View and enter meter readings, view trends in graphical format, and create readings while in offline mode.

MxAsset

Scan barcodes and view maintenance facts. Create meter readings, work orders or service requests. Toggle asset downtime.

MxWork

Create new work orders on the go, view existing work orders and attachments, and capture fingertip electronic signatures.
0