Supporting File Import (CSV/XML) Import Preview using REST api
you can upload data from flat files or XML or JSON files to Maximo Asset Management by using RESTful API action=importfile by using the application import capability.
Prepare Object Structure
To import XML files, you do not need to configure the object structure. To import flat files, similar with the application import, you need to configure object structure to support the flat file structure. This implies there shouldn’t be any alias conflict for that specific object structure. To verify that, find the object structure, such as MXAPIMETER, in the Object Structure application. Make sure the Support Flat Structure check box is selected and no alias conflict is detected by the system (the Alias Conflict check box is clear). If there are any conflicting fields, select the Add/Modify Alias action and add a new alias to the conflicted field, starting with the first child object. The rest of this section focuses on flat files but XML files is the same with a different header value.
Security
There is no special requirement on security - it just follows the normal Object structure security concepts. This implies that you got to have support for INSERT/SAVE/DELETE sigoptions (for your corresponding security application for the object structure) to be able to import csv files.
Prepare CSV
The CSV format is the same as a typical application import in Maximo Asset Management. When you import files from CSV, the attribute name of each field must match with attribute alias in Maximo Asset Management.
For example, the CSV file content can be as follows
METERNAME,METERTYPE,READINGTYPE,DESCRIPTION,MEASUREUNITID RUNHOURS2,CONTINUOUS,DELTA,Run Hours2,HOURSTEMP-F2,GAUGE,,Temperature in Fahrenheit2,DEG F
Preview
Before processing the data into the database, you should validate if there any errors occured by using the preview functionality, which is supported in the import file API. For example:
POST oslc/os/mxapimeter?action=importfile&lean=1maxauth:<base64 encoded user:password>preview:1
Body:
METERNAME,METERTYPE,READINGTYPE,DESCRIPTION,MEASUREUNITID RUNHOURS2,CONTINUOUS,DELTA,Run Hours2,HOURSTEMP-F2,GAUGE,,Temperature in Fahrenheit2,DEG F
After you make the POST request to server, the system returns the preview response, which includes the validation information and warning messages and shown in the following error message example:
{"invaliddoc": 2,// how many invalid records"totaldoc": 2,//how many records in csv file in total"validdoc": 0,//how many valid records"warningmsg": "\nBMXAA5598E - Processing of an inbound transaction failed. The processing exception is identified in document 1.\n\tBMXAA0024E - The action ADD is not allowed on object METER. Verify the business rules for the object and define the appropriate action for the object.\nBMXAA5598E - Processing of an inbound transaction failed. The processing exception is identified in document 2.\n\tBMXAA0024E - The action ADD is not allowed on object METER. Verify the business rules for the object and define the appropriate action for the object." //the error messages for each record.}
You can determine the problem from warning messages and then fix it. In the sample error responses, you can tell that the issue is caused by missing the security setup. After granting the sigoptions and reprocess the call, the successful preview looks like following example:
{"invaliddoc": 0,"totaldoc": 2,"validdoc": 2,"warningmsg": ""}
File Import
After previewing, you can import the file into Maximo Asset Management by removing preview header from request:
POST oslc/os/mxapimeter?action=importfile&lean=1
Body:
METERNAME,METERTYPE,READINGTYPE,DESCRIPTION,MEASUREUNITID RUNHOURS2,CONTINUOUS,DELTA,Run Hours2,HOURSTEMP-F2,GAUGE,,Temperature in Fahrenheit2,DEG F
The response is as follows:
{"validdoc": 2}
Other file types are supported, like XML/JSON, customized delimiter, and textqualifier. You can easily configure them with the following headers when you do the POST call.
| Header | Description | Default value |
|---|---|---|
| filetype | The type of the uploading file, it can be FLAT or XML | FLAT |
| delimiter | The delimiter of csv file | , |
| textqualifier | When the data include any delimiter, it will be wrapped by textqualifier | ” |
| preview | If the importfile API is running in preview mode. It can be 0 or 1 | 0 |
Asynchronous File import
We can upload files asynchronously using the rest apis starting 7611. To do this just add the query parameter async=1 and another query parameter name=<some unique name identifying the load>. The response would be a location url (in the response header) for the client program to poll to get status on the upload. The response of that polling is given in a json document that also indicates how many records have been processed so far which can be leveraged by the client program to show a progress indicator. At the end of the upload, the json document would contain the list of errors that it incurred as part of the upload and a embedded link to download the error file. The error file would be in the same format as the request upload file and will contain the error message along with the original data for each of the error records. Note that this error file only contains error records and not the ones that were processed successfully.
Internally Maximo has a crontask (API_FILE) that processes the upload at a configurable frequency.