Now that we’re familiar with how to access data in Maximo using the RESTful architecture provided by the OSLC framework, let’s dig into how we can leverage this same infrastructure when integrating Maximo with another system. The Maximo RESTful framework allows messages conforming with its API to create new records, as well as update existing ones. It also allows you to define what data you need to be back-channeled so that you, the requesting party, have a view into what information is created in Maximo. This blog post will focus on how to create new records in Maximo using the REST API.
Say you’re designing an integration between Maximo and an application your users interact with to log service requests, and that you’re using Maximo to manage your work against your assets. So, when a user identifies a service need, you want to create a record of that in Maximo so that you can manage it. Let’s also say that you want this processing to happen in real-time and on-demand. RESTful architecture provides you with the framework needed to accomplish these goals.
If your reporting application allows you to send HTTP messages when events occur, you would need to configure it to send a message to Maximo when a user identifies their service need. Maximo will accept that message, and process the payload into a new SR record, returning HTTP status codes and information about the record it creates in order to give you the tools you need to ensure your request has been properly handled. The details of what would need to be included in the payload from your app to Maximo would be specific to your business needs, but the broad strokes of this model example should serve to start you off on the right foot.
Let’s try creating an SR record similar to the one we created within Maximo in the first blog post, but this time, let’s create the SR by sending a RESTful request over to Maximo as if we were an application that is being integrated with Maximo. I’ll be using Postman, an app for designing and testing RESTful APIs, in order to emulate the source system in our use case.
The first thing to note in this case is the HTTP verb that we are using. RESTful services across the web implement functionality for a handful of verbs to classify the desired behaviour from the target system. In terms of this use case, we’ll be relying on the POST verb. Sending an HTTP request with a POST verb is asking the target system to do some processing on the payload after it receives it. Since Maximo models your business rules, you will want it to apply them to the record you are trying to create, whether the record is being created in the front end or via REST calls. Using POST is appropriate in this case. We are directing this POST message to the same collection endpoint as we used when querying SRs in the earlier example: https://<server>/maximo/oslc/os/mxsr/?lean=1.
Next, let’s examine the structure your payload will need to adopt in order to conform to the Maximo API. We’re using JSON as our language to represent our data, so here’s what a request’s body would need to look like to create a similar SR to the one we made earlier. Here’s how this payload looks when you set it in Postman. Note that the Maximo object attributes are referred to here by name, but that the attribute names are in lowercase.
Since we’re using JSON as our convention for representation, we need to state that to Maximo so that it knows how to process the payload. Another format that’s supported by Maximo’s REST services is XML, and the two are processed very differently, so the distinction is important. To differentiate between XML and JSON, we set the “Content-type” header in the HTTP Request to “application/json”.
The other really useful header to keep in mind when creating records is the Properties header. This is a non-standard header that Maximo supports, which allows you to dictate which properties you would like to be returned from the object that you are creating or updating. This can be useful for gathering a Maximo record’s identifier or for verifying that your payload has been correctly processed. In our scenario, let’s say that we would like to scrape information about our record after it gets sent over. To do that, we set the Properties header to “ticketid, reportedby, assetnum, reportedphone, reportedemail, location, affectedpersonid, reportdate, description”, or a comma-separated list of the attributes we want to verify after the record is created. This is useful since we are expecting the affected user’s phone number and email to cross over to the SR on association of the user, but we’re not sending that information over. We also want to make sure that the reported date timestamp is set when we create a new record.
Here is what the headers look like for our message when we create it using Postman:
Now that we have a representation of our object’s state and we’ve parameterized the exchange, we can POST our request off to Maximo. Make sure you include your MAXAUTH header in order to authenticate, which allows the transaction to take place.
Having done so, we receive a response from Maximo:
First, we note the HTTP Response Code. In this case, it is 201 Created, which indicates that our request was successful, and that a new resource has been placed into the collection.
Next we observe the payload of the response. We see a JSON representation of our object that conforms to the properties we requested in the “Properties” header. We can see that Maximo has done its job correctly, and crossed the user’s phone number and email over, as well as set the reported date correctly. We also note that there are two fields supplemental to the ones we’ve asked for, namely _rowstamp, and href. These two fields will be returned with any object’s creation. The rowstamp indicates the database rowstamp associated with the new record, while the href serves as a reference to the newly-created record. It would be good practice to associate the href with the source-record in the source system so that it can refer to the Maximo record with ease if it needs to propagate changes.
Now that we’ve created a record in Maximo using REST services, let’s go take a look at it, and make sure it looks like the first one that we created by hand. We’ll grab the ticketid from the response and look for our ticket in the View Service Requests app.