Skip to content

Maximo REST API

Jump to bottom
Pranav edited this page Aug 16, 2023 · 6 revisions

Documentation for Maximo REST API

Make sure you're logged into maximo before you click on the above link, or else it wont work.

PDFs

What is a REST API?

In simple terms, a REST (or RESTful) API allows you to query and send information to a server. In our case, we are communicating with the IKO Maximo database to do things like uploading items, uploading images, retrieving existing items, etc.

"REST" is simply a design philosophy for the API, so don't worry about it too much. An API is simply an interface that allows two applications to talk to each other. In this case, your computer is communicating with the Maximo Server.

HTTP Requests

To communicate with Maximo, you will need to utilize HTTP Requests. Reading up on http requests is recommended, as this guide will only explain parts that are relevant to Maximo.

Think about requests as a way to "talk" to the server. Each "request" you send to Maximo has 4 key components:

  1. Request Method

The request method is a way of telling Maximo what type of request you're sending.

Request method When it is used:
GET  Tells the server to retrieve information
POST  Tells the server that you are sending information
DELETE  Tells the server you are deleting information. This is very rarely used.
  1. URL

The URL tells Maximo which part of the database your request is about. Make sure the URL is encoded before sending.

When making a request to Maximo, the first part of the url always starts with:

https://prod.manage.prod.iko.max-it-eam.com/maximo/api/os/ -- production server. (never test on this server, unless your code is fully complete)

or

https://test.manage.test.iko.max-it-eam.com/maximo/api/os/ -- test server

The next part is the "object". The object is like a different section of the server. If you've done standardization, you might know that there is "item master" and "inventory". A couple other examples include "assets", "job plans", "locations", etc. If you want to upload or query an item, you would use the "item master" object. To upload or query an asset, you would use the "assets" object.

image

Each of these is a different "object"

Each object has its own identifier to use when making an http request. Here are some common ones:

Object Name
item master iko_itemmaster
inventory iko_inventory
assets iko_asset

To make a request to an object append the object name to the aforementioned url (like so):

https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_itemmaster

This link represents the entire database for item master.

When making a request, you will also need to use queries. Read up on them here (1st pdf in Documentation) ~ (page 8-13) before continuing.

In summary, a query is something that lets you filter the results of your request. If you made a GET request on the item master object for example, Maximo would return the entire item master database, which is not only useless, but would take a significant amount of time. Here is how to use queries:

  1. Add a ? to the end of the url after appending the object name.
  2. Append the query to the end of the url. Add and if using multiple queries.

Example: https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_itemmaster?oslc.where=itemnum=9000051&oslc.select=itemnum

Query Parameters in the above example:

parameter value
oslc.where itemnum="9000051"
oslc.select description

Sending a GET request to the above URL would return the "description" of an item in item master where the item number is 9000051. This will be further discussed later.

When making a POST request, the most commonly used query is action=importfile. This query allows you to upload things to the server (items, assets, etc.).

  1. Request Headers

Headers are not included in the URL, look at the examples to see how to include headers in your request. One header you will always need to include is your api key. If sending a post request, you will usually need to include the filetype header:

Request body format Header
XML filetype = XML
CSV filetype = FLAT (for csv bodies, the filetype header is optional)

Images require more headers, view the first pdf in documentation to learn more.

When making a POST request with a CSV or XML format body, you can also use the preview = 1 header to see what the result of your request would be without actually uploading anything, making it useful for testing while developing.

  1. Request Body

For the Maximo API, this is part is exclusively used when making POST requests. The request body is basically the information you want to send to the server. Generally the request body is a plain string which is formatted as a CSV or an XML file. Here is an example:

For uploading an item as XML:

<?xml version="1.0" encoding="UTF-8"?>
    <SyncIKO_ITEMMASTER xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <IKO_ITEMMASTERSet>
        <ITEM>
            <COMMODITYGROUP>401</COMMODITYGROUP>
            <DESCRIPTION>motor</DESCRIPTION>
            <DESCRIPTION_LONGDESCRIPTION></DESCRIPTION_LONGDESCRIPTION>
            <EXTERNALREFID>ERM</EXTERNALREFID>
            <IKO_ASSETPREFIX></IKO_ASSETPREFIX>
            <IKO_ASSETSEED></IKO_ASSETSEED>
            <IKO_JPNUM></IKO_JPNUM>
            <INSPECTIONREQUIRED></INSPECTIONREQUIRED>
            <ISIMPORT></ISIMPORT>
            <ISSUEUNIT></ISSUEUNIT>
            <ITEMNUM></ITEMNUM>
            <ITEMSETID>ITEMSET1</ITEMSETID>
            <ROTATING></ROTATING>
            <STATUS>ACTIVE</STATUS>
        </ITEM>
    </IKO_ITEMMASTERSet>
</SyncIKO_ITEMMASTER>

Uploading item as CSV:

COMMODITYGROUP,DESCRIPTION,DESCRIPTION_LONGDESCRIPTION,EXTERNALREFID,IKO_ASSETPREFIX,IKO_ASSETSEED,IKO_JPNUM,INSPECTIONREQUIRED,ISIMPORT,ISSUEUNIT,ITEMNUM,ITEMSETID,ROTATING,STATUS
409,"VALVE,PNU,STEM ACTUATED,V-3-M5,3626,FESTO",,ERM,,,,0,0,EA,9027909,ITEMSET1,0,ACTIVE

Since maximo is a database, the request body will be formatted like a table, with a header and value. In the XML format string you can see that each attribute is a tag, and either has a value, or is left blank (e.g. <DESCRIPTION>motor</DESCRIPTION> tells maximo that the description of the item you are uploading is "motor").

A notable exception to this is when you are uploading an image, in which case the request body is simply the image file.

Where can I find how to format the request body?

Navigate to the object (on the company Maximo website) you want to make an http request on, and click application export. Then select an object structure (depends on which object you are trying to make a request to) and select file type in "export configuration" (XML or FLAT, json is not used), then click ok. Usually this can only be done on the test environment (to access the test environment ask the Maximo admin (Jonathan Ma at the time of writing this) for a test server account and api key). The resulting file is the same format that your POST request should be in.

image

image

Request Response

Every time you send an http request, Maximo will return a "response" in the JSON format, and an status code. The status code tells you about the status of your http request. Read up on it here. Try sending a GET request or look at the examples below to see what a response usually looks like.

OK, but how do I use the API in my code?

Use the javascript fetch() function. To learn how to use it, look at an example in the code or read here.

Here are some examples of http requests in javascript:

Uploading an item

let xmldoc =     
    `<?xml version="1.0" encoding="UTF-8"?>
    <SyncIKO_ITEMMASTER xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <IKO_ITEMMASTERSet>
        <ITEM>
            <COMMODITYGROUP>${item.commoditygroup}</COMMODITYGROUP>
            <DESCRIPTION>${item.description.replaceAll('&','&amp;')}</DESCRIPTION>
            <DESCRIPTION_LONGDESCRIPTION>${item.longdescription.replaceAll('&','&amp;')}</DESCRIPTION_LONGDESCRIPTION>
            <EXTERNALREFID>${item.glclass}</EXTERNALREFID>
            <IKO_ASSETPREFIX>${item.assetprefix}</IKO_ASSETPREFIX>
            <IKO_ASSETSEED>${item.assetseed}</IKO_ASSETSEED>
            <IKO_JPNUM>${item.jpnum}</IKO_JPNUM>
            <INSPECTIONREQUIRED>${item.inspectionrequired}</INSPECTIONREQUIRED>
            <ISIMPORT>${item.isimport}</ISIMPORT>
            <ISSUEUNIT>${item.issueunit}</ISSUEUNIT>
            <ITEMNUM>${item.itemnumber}</ITEMNUM>
            <ITEMSETID>ITEMSET1</ITEMSETID>
            <ROTATING>${item.rotating}</ROTATING>
            <STATUS>ACTIVE</STATUS>
        </ITEM>
    </IKO_ITEMMASTERSet>
    </SyncIKO_ITEMMASTER>`;

let response = await fetch('https://test.manage.test.iko.max-it-eam.com/maximo/api/os/IKO_ITEMMASTER?action=importfile', {     
    method: "POST",
    headers: {
        "filetype":"XML",
        "apikey": yourMaximoApiKey,
        //"preview": "1"
    },
    body: xmldoc,
});
let content = await response.json(); // Content is the request response. Access information from it the same way as a Map (content['key']).

Getting id, commodity group and description of an item:

The id is always included in an http GET response. However, to get additional information (such as description, gl class, etc.) you will need to use the oslc.select query as show below.

let response = await fetch(`https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_item?oslc.where=itemnum=9000055&oslc.select=commoditygroup,description`, {
    method: "GET",
    headers: {
        "apikey": yourMaximoApiKey,
    }
})
let content = await response.json();

let itemURL = content["rdfs:member"][0]["rdf:resource"]; //itemURL = "http://localhost/maximo/api/os/iko_itemmaster/_OTAwMDA1NS9JVEVNU0VUMQ--"
let itemId = itemURL.slice(25); //item id is last 25 characters of item URL

Response (value of content variable):

STATUS: 200

{
  "prefixes": {
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
    "oslc": "http://open-services.net/ns/core#"
  },
  "oslc:responseInfo": {
    "rdf:about": "http://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_item?oslc.where=itemnum=9000055&oslc.select=commoditygroup,description"
  },
  "rdfs:member": [
    {
      "_rowstamp": "[0 0 0 0 -55 72 -45 -45]",
      "itemorginfo_collectionref": "http://localhost/maximo/api/os/mxitem/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo",
      "spi:description": "VALVE,PNU,96875,ASCO",
      "spi:commoditygroup": "409",
      "itemcondition_collectionref": "http://localhost/maximo/api/os/mxitem/_OTAwMDA1NS9JVEVNU0VUMQ--/itemcondition",
      "itemspec_collectionref": "http://localhost/maximo/api/os/mxitem/_OTAwMDA1NS9JVEVNU0VUMQ--/itemspecclass",
      "conversion_collectionref": "http://localhost/maximo/api/os/mxitem/_OTAwMDA1NS9JVEVNU0VUMQ--/conversion",
      "rdf:about": "http://localhost/maximo/api/os/mxitem/_OTAwMDA1NS9JVEVNU0VUMQ--"
    }
  ],
  "rdf:about": "http://localhost/maximo/api/os/mxitem"
}

As you can see above, the description and commodity group are included in the response under content["rdfs:member"][0]["spi:description"] and content["rdfs:member"][0]["spi:commoditygroup"].

Getting ALL info about an item:

We will use the item id that we retrieved from the previous request (_OTAwMDA1NS9JVEVNU0VUMQ--) and make a new request.

let response = await fetch(`https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--`, {
    method: "GET",
    headers: {
        "apikey": yourMaximoApiKey,
    }
})
let content = await response.json();

Response (value of content variable):

STATUS: 200

{
  "spi:itemtype": "ITEM",
  "spi:status": "ACTIVE",
  "spi:itemsetid": "ITEMSET1",
  "spi:description": "VALVE,PNU,96875,ASCO",
  "rdf:about": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--",
  "prefixes": {
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
    "oslc": "http://open-services.net/ns/core#"
  },
  "_rowstamp": "[0 0 0 0 -55 72 -45 -45]",
  "spi:externalrefid_description": "Equipment Repair & Maint",
  "itemorginfo_collectionref": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo",
  "spi:itemorginfo": [
    {
      "spi:status": "ACTIVE",
      "prefixes": {
        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
        "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
        "oslc": "http://open-services.net/ns/core#"
      },
      "_rowstamp": "[0 0 0 0 99 -112 118 -63]",
      "spi:category": "STK",
      "localref": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo/0-842",
      "spi:orgid": "IKO-CAD",
      "spi:status_description": "Active",
      "rdf:about": "http://childkey#SVRFTS9JVEVNT1JHSU5GTy85MDAwMDU1L0lURU1TRVQxL0lLTy1DQUQ-"
    },
    {
      "spi:status": "ACTIVE",
      "prefixes": {
        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
        "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
        "oslc": "http://open-services.net/ns/core#"
      },
      "_rowstamp": "[0 0 0 0 99 -112 118 -62]",
      "spi:category": "STK",
      "localref": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo/1-222938",
      "spi:orgid": "IKO-EU",
      "spi:status_description": "Active",
      "rdf:about": "http://childkey#SVRFTS9JVEVNT1JHSU5GTy85MDAwMDU1L0lURU1TRVQxL0lLTy1FVQ--"
    },
    {
      "spi:status": "ACTIVE",
      "prefixes": {
        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
        "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
        "oslc": "http://open-services.net/ns/core#"
      },
      "_rowstamp": "[0 0 0 0 112 -60 -24 103]",
      "spi:category": "STK",
      "localref": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo/2-373231",
      "spi:orgid": "IKO-UK",
      "spi:status_description": "Active",
      "rdf:about": "http://childkey#SVRFTS9JVEVNT1JHSU5GTy85MDAwMDU1L0lURU1TRVQxL0lLTy1VSw--"
    },
    {
      "spi:status": "ACTIVE",
      "prefixes": {
        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
        "spi": "http://jazz.net/ns/ism/asset/smarter_physical_infrastructure#",
        "oslc": "http://open-services.net/ns/core#"
      },
      "_rowstamp": "[0 0 0 0 99 -112 118 -61]",
      "spi:category": "STK",
      "localref": "http://localhost/maximo/api/os/iko_item/_OTAwMDA1NS9JVEVNU0VUMQ--/itemorginfo/3-76357",
      "spi:orgid": "IKO-US",
      "spi:status_description": "Active",
      "rdf:about": "http://childkey#SVRFTS9JVEVNT1JHSU5GTy85MDAwMDU1L0lURU1TRVQxL0lLTy1VUw--"
    }
  ],
  "spi:itemnum": "9000055",
  "spi:rotating": false,
  "spi:isimport": false,
  "spi:issueunit": "EA",
  "spi:commoditygroup": "409",
  "spi:orderunit": "EA",
  "spi:inspectionrequired": false,
  "spi:status_description": "Active",
  "spi:externalrefid": "ERM",
  "spi:sparepartautoadd": false
}

Uploading an image:

Note: replace {itemId} with the actual item id (e.g. {itemId} becomes _OTAwMDA1MS9JVEVNU0VUMQ--).

let response = await fetch(`https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_item/{itemId}?action=system:addimage`, {
    method: "POST",
    headers: {
        "x-method-override":"PATCH",
        "Slug":`itemnum.jpg`,
        "Content-type":"image/jpeg",
        "custom-encoding":"base",
        "apikey": yourApiKey,
    },
    body: image
});

Response: Status: 204 No Response Body

Actions related to images will usually not return a response body, and the response code will usually always be 200-series, even if your request was invalid. The only way to confirm the request worked is to go to the maximo website.

Deleting an image:

let response = await fetch(`https://test.manage.test.iko.max-it-eam.com/maximo/api/os/iko_item/{itemId}?action=system:deleteimage`, {
    method: "POST",
    headers: {
        "x-method-override":"PATCH",
        "apikey": yourApiKey,
    },
    body: image
});

Response: Status: 204 No Response Body

Clone this wiki locally