Querying Maximo using the REST and JSON APIs

In a recent exchange on the IBM developerWorks forum for Maximo, it was discussed how best to query Maximo through the Integration Framework that is configured for LDAP. Getting data from an LDAP-based Maximo is similar to an environment that is configured to use native authentication, with a few subtle differences. This article will demonstrate how to query for data using the REST API that is found in Maximo 7.5.0.3 and higher, and the JSON API that is found in Maximo 7.6.0.2 and higher.

The information detailed below is available in an IBM article (available as a PDF or as a web page) titled “Maximo NextGen REST API”. Based on questions I have received from our customers and other Maximo professionals, there seems to be some confusion on how to use this information.

There are many tools available that will facilitate communication to and from Maximo using the REST and JSON APIs. This article uses the Postman application which can be downloaded for free here.

Before we dive into the “How” we should discuss the “Why”. What are some reasons for wanting to use these Maximo APIs? Here are a few:

  • Creating new records
  • Modifying existing records
  • Querying Maximo data from an external application
  • Performing calculations on Maximo data such as averaging a cost, finding maximum cost or summing a budget from an external application
  • Creating lists based on Maximo data
  • Querying related records from an external application such as retrieving a list of work orders for a given asset
  • Deleting data
  • Replacing data

Querying Maximo Data with Native Authentication

Let’s start off with a simple scenario: show me all Person records that start with the string ‘CAR’. Note that we are using the Maximo demonstration data for these examples.

To start, we need two pieces of information to complete a successful API call:

  1. Maximo API URL
  2. Maximo Username and Password

However, just having the Maximo Username and Password is not good enough to make an API call. We’ll need to encode those credentials before calling the API.

The credentials will need to be Base64 encoded using the username:password format. For example, if your credentials were maxadmin:maxadmin, your Base64 encoded credentials would be bWF4YWRtaW46bWF4YWRtaW4=. You can use this online utility to perform a successful encode. Place your username:password in the first box and click the > ENCODE < button. Your Base64 encoded string will appear in the box below.

Now we can fire up our Postman application to perform the calls to Maximo.

JSON API

For the JSON API, our Maximo URL will look like this:

http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"

Substitute your Maximo host name for the maximo_host, and include a port number if necessary.

Next, we’ll need to supply the credentials as an HTTP Header. The header key for Native Maximo Authentication is maxauth. The header value will be your Base64 encoded credentials. Finally, we’ll use the HTTP Method of GET. It comes together like this:

GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"
maxauth: bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

Maximo will perform a wildcard search so all person records that contain the string CAR will be returned. In the case of the sample or demonstration data, that is one record.

The result will be something similar to this:

{
  "member": [
    {
      "href": "http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O"
    }
  ],
  "responseInfo": {
    "href": "http://maximo_host/maximo/oslc/os/mxperson?lean=1&oslc.where=personid=%22CAR%25%22"
  },
  "href": "http://maximo_host/maximo/oslc/os/mxperson"
}

When using the JSON API you will get a URI back. This URI is especially useful as you can use this URL to query, perform updates, or perform a delete action on a specific record. In this case you can take the URL and place that back into Postman to perform a GET action. You will receive all of the pertinent record information for that specific record.

http://maximo_host/maximo/oslc/os/mxperson/_Q0FSU09O

REST API

For the REST API, our Maximo URL will look slightly different; however, the concept of authentication remains the same. Substitute your Maximo host name for the maximo_host, and include a port number if necessary:

http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%

It comes together like this:

GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
maxauth: bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

The results are:

{
  "QueryMXPERSONResponse": {
    "rsStart": 0,
    "rsCount": 1,
    "MXPERSONSet": {
      "PERSON": [
        {
          "rowstamp": "[0 0 0 0 0 106 -81 -98]",
          "ACCEPTINGWFMAIL": true,
          "ADDRESSLINE1": "62 Winthrop Street",
          "BIRTHDATE": "1962-08-22T00:00:00-04:00",
          "CITY": "Medford",
          "COUNTRY": "US",
          "DISPLAYNAME": "Tara Carson",
          "FIRSTNAME": "Tara",
          "HIREDATE": "1997-08-01T00:00:00-04:00",
          "LASTEVALDATE": "2001-08-01T00:00:00-04:00",
          "LASTNAME": "Carson",
          "LOCTOSERVREQ": true,
          "NEXTEVALDATE": "2002-08-01T00:00:00-04:00",
          "PERSONID": "CARSON",
          "PERSONUID": 21,
          "POSTALCODE": "02155",
          "PRIMARYEMAIL": "tara.carson@helwig.com",
          "PRIMARYPHONE": "781-555-6247",
          "STATEPROVINCE": "MA",
          "STATUS": "ACTIVE",
          "STATUSDATE": "2003-09-25T15:44:38-04:00",
          "STATUSIFACE": false,
          "TRANSEMAILELECTION": "NEVER",
          "WFMAILELECTION": "PROCESS",
          "PHONE": [
            {
              "rowstamp": "[0 0 0 0 0 96 57 -106]",
              "ISPRIMARY": true,
              "PHONEID": 145855,
              "PHONENUM": "781-555-6247",
              "TYPE": "WORK"
            }
          ],
          "EMAIL": [
            {
              "rowstamp": "[0 0 0 0 0 93 114 125]",
              "EMAILADDRESS": "tara.carson@helwig.com",
              "EMAILID": 145855,
              "ISPRIMARY": true,
              "TYPE": "WORK"
            }
          ]
        }
      ]
    }
  }
}

To get information about a single record in the REST API, you need to reference the Unique ID of the record. In this example, since we are referencing the PERSON object, the PERSONUID attribute is our Unique ID. To query for a specific Person record, include the PERSONUID in the URL:

http://maximo_host/maxrest/rest/os/mxperson/88?_format=json&_compact=1

Querying Maximo Data with LDAP Authentication

If your Maximo instance is configured to use LDAP Authentication, you must use a slightly different HTTP Header to supply the appropriate Maximo credentials. The other information, such as the URL and HTTP Method, remain the same.

In place of MAXAUTH, Authorization is used as the property in the HTTP Header. The same Base64 encoded username:password combination created earlier is also used for the value, however, this time it is preceded with the word Basic and a space character.

It comes together like this using the JSON API:

GET http://maximo_host/maximo/oslc/os/mxperson?oslc.where=personid="CAR%"
Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=

In Postman:

Similarly, for the REST API:

GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4=

Maintaining Your Session

Once you establish a successful connection to Maximo, you will receive a cookie back in the response with a JSESSIONID token.

It is recommended to use this token in subsequent requests back to the Maximo API. This will improve performance and limit the number of sessions that Maximo creates.

Please feel free to leave any comments or questions below. For visual instruction of the previous steps, check out our video tutorial.

Related posts

16 comments

  • Hi,
    I am checking the Rest API to get the workflow task is assigned to some user, by query tis object structure “/maximo/oslc/os/MXAPIWFASSIGNMENT” and condition is “?oslc.select=*&oslc.where=ownertable=”SR” and processname=”MyCompanyWR”, I can get some workflow task, but my problem is that: when i input the user for Rest API authentication, the service always return the Workflow Task which assigned to this user only. My expectation is that: I used only single service user for Rest API authentication like “MAXADMIN”, and get the user’s assigned task by condition like add to the selection condition like “oslc.select=*&oslc.where=ownertable=”SR” and processname=”MyCompanyWR” and assigncode = “MyUserOnly”..
    Thank you so much
    Long.

    • Bob Richardson

      Hi Long,

      If I understand your question, you want to return records from the MXAPIWFASSIGNMENT object structure beyond those records that are assigned to the user being used for authentication. There is a data restriction, called ASSIGNFILTER, on the MXAPIWFASSIGNMENT object structure that is likely impacting your results. If you take a look at that restriction the expression is,

      assigncode = :&PERSONID& and assignstatus in (select value from
      synonymdomain where domainid = ‘WFASGNSTATUS’ and maxvalue = ‘ACTIVE’)

      To return different results, you will likely want to duplicate this object structure and either remove or apply another expression that is more in inline with the record set you are wanting.

  • Ronak Agrawal

    Hi Alex,

    How maintain the session for a user when Maximo instance uses LDAP BASIC Auth. Maintaining session workflow:
    1. Login (OSLC/login)
    2. Subsequent API calls using the Cookies (Get Object values, update object values etc..)
    3. Logout (OSLC/logout) (This is also one of the and last subsequent calls for that session).

    I am struggling in defining the Header values for the subsequent calls.

    If I put Header as :
    i. Cookie:”LtpaToken2=; JSESSIONID=” (NOTE Values are taken from initial OSLC/login Method) – The server generates another session

    ii. Two headers:
    Cookie:”LtpaToken2=”
    Cookie:”JSESSIONID=”
    Server returns 401 response

    iii. Use single Cookie for each call, with value of LtpaToken – Server generates new session
    iv. Use single Cookie for each call, with value of JSESSIONID – Server returns 401 response.

    NOTE: All the above calls are over HTTPS not HTTP.

    Please suggest with any REST Call and response example, for Session management in LDAP BASIC Auth.
    Session management for Native Auth works as you have mentioned in this post.

    Thanks

  • How do I query the Maximo JSON API using python scripting alone? That is no PostMan?

    I have Maximo 7.6.1 and I am using basic authentication.

    I used Postman to make my Get Request, which was successful and return data, and then clicked on the “Code” button to the right to get the python script. When I use it in my IDE I get this error:

    {“Error”:{“reasonCode”:null,”message”:”Lexical error at line 1, column 13. Encountered: \”%\” (37), after : \”\””,”statusCode”:”500″}}

    Here is the python:
    import requests

    url = “http://myserver/maximo/oslc/os/mxwo”

    querystring = {“lean”:”1″,”oslc.select”:”wonum,actstart,status,description,reportedby,agx,agy”,”oslc.where”:”problemcode=%22DR07%22″,”status”:”%22APPR%22″}

    payload = “”
    headers = {
    ‘maxauth’: “mypasswordhereinbase64”,
    ‘cache-control’: “no-cache”,
    ‘Postman-Token’: “3803cf2c-5aed-4739-aab0-f5c86692f7e0”
    }

    response = requests.request(“GET”, url, data=payload, headers=headers, params=querystring)

    print(response.text)

  • Sreekala

    Hi ,
    For ADFS enabled maximo environment ,GET http://maximo_host/maxrest/rest/os/mxperson?personid=CAR%
    Authorization: Basic bWF4YWRtaW46bWF4YWRtaW4= is not working.
    Getting the below error:
    function LoginErrors(){this.userNameFormatError = ‘Enter your user ID in the format \u0026quot;domain\\user\u0026quot; or \u0026quot;user@domain\u0026quot;.’; this.passwordEmpty = ‘Enter your password.’; this.passwordTooLong = ‘Password is too long (\u0026gt; 128 characters).’;}; var maxPasswordLength = 128;
    //]]>

    Any help would be appreciated

  • Mark Fresa

    Does anyone know how to POST updates to Maximo using Postman in URL strings? Please contact me if possible. Thanks in advance.

  • Ed Matthews

    If you have the other comment I just sent this below provides some more detail but not the answer.
    In the ibm guide available here:
    https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html#_querying_maximo_asset_management_by_using_the_rest_api

    it says,

    “Just getting the links to the member resources may not be very exciting or useful. Rather than traversing individual URIs for details, the oslc.select clause is used to get more details inlined in this JSON response.

    GET /oslc/os/mxasset?oslc.pageSize=10&oslc.select=assetnum,location,description,status”

    In the article example above, how would you / could you use the json api to get the same result as
    http://maximo_host/maxrest/rest/os/mxperson/88?_format=json&_compact=1 ?

    Trying to understand better the advantages and tradeoffs of using
    maximo/oslc/os vs maxrest/rest/os

    Thanks,
    Ed

    • Alex Walter

      Biggest advantages are: 1) the ability to dynamically pull data based on information that may not necessarily be listed in the Object Structure, 2) more fine-grained control of filtering and sorting, 3) the ability to support paging through sets of data, and 4) continuing feature enhancements and support from IBM. The REST API is static and will not continue to be developed, where the JSON API is being updated with each new release of Maximo.

      Hope this helps,
      Alex

  • Ed Matthews

    Hi Bob,

    I’ve heard it’s best to move to the json syntax for its power and flexibility, but the rest message format returned is preferable to the URIs for the case I’m solutioning.
    Is there a way to use the json api syntax but to get an output like that of the rest api, that is, the data not the URIs?
    It seems maybe possible using {*} for each object, I will work on that option, but that appears to make the query URLs more complex, given the integration object itself that I’m using contains the attribution an external system wants to use, so setting the query syntax to use {*} from the top object down following the whole object structure is redundant.

    Wondering what I may be missing.

  • TANWEER

    Hi Alex
    i am using REST API in the LDAP enabled environment ,which needs  Basic Authentication . i have written the below code but form data is not passing to maximo where as a blank service request record created.

    where as if i pass data in url using &, it creates the record with data. but large data cannot be passed in this manner since there is limitation of url size. following is the code i have written to pass form data , can you suggest why form data is not passing.

    body
    {
    direction:ltr;text-align:left;
    }
    .row
    {
    display:block; padding:10px;    
    }

      function CallWebAPI() {
        var formData = new FormData(document.forms.myForm);
            
        var XHR = new XMLHttpRequest();
           
        });

        // Set up our request
        XHR.open(“POST”, “http://controldesk.local/maxrest/rest/os/MYSR”);
          XHR.setRequestHeader(‘Authorization’,’Basic cG14aW50OlBAc3N3MHJkMTA=’);

        // The data sent is what the user provided in the form
        XHR.send(formData);
      }
     
      // Access the form element…
        

    Basic Authentication Using JavaScript

     
      DESCRIPTION:
     
     
     
      INTERNALPRIORITY:
     
     
     
     
      civilid:
     
     

     

    Thanks & Regards

    Tanweer

    • Alex Walter

      Make sure you don’t have a CORS issue going on with XHR requests.
      https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

      • Nonitha

        Is it possible to read the content of the JSON body from automation script?
        request.getQueryParam() is to read query parameters and request.getHeaderParams() is to read header parameters.
        Is there any method to read body content from the JSON API?
        Because passing parameters in URL has many restrictions.

        Thanks
        Nonitha

        • Alex Walter

          There is a request.readRequestBody() method that returns a byte array.

          Hope that helps,
          Alex

  • Thanks for explaining how to encode the login & password. I’m going to try using CURL and see if I can login and retrieve results via a URL.

  • John Harper

    any way to capture the jsession id and run a get oslc/logout for that session for high volume of call?

    • Alex Walter

      The JSESSIONID can be captured via the Set-Cookie header in the response from the oslc/login call. When you are finished with the session call the oslc/logout with those credentials.

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