Data import and export with REST API

Edit online

You can use REST APIs to export data from your system into an external system or application and to import data from an external system or application into your Manage system. You can export and import JSON, XML. or CSV files.

Importing data

To import data, you must choose a Manage object structure that references the Manage business objects that consume the data. If you use a CSV file, you must select an object structure that is enabled for flat files. All object structures that are for a primary API are flat-file enabled.

The syntax is validated for the data before the data is stored in an internal Manage repository.

The following table contains examples of importing data by using REST APIs:

Table 1. Examples of importing data
Use case REST API calls and responses
Data is synchronously imported from a CSV file that contains 10 records

The following call is used:

POST /maximo/api/os/object 
structure?action=importfile

CSV file content

The following response is returned:

{
 “validdocs”:10
}
Asset and site data is synchronously imported from a JSON file array

The following call is used:

POST /maximo/api/os/object 
structure?action=importfile
Filetype: JSON
[
{
“assetnum”:”asset number”,
 “siteid”:”site ID”
},
{
“assetnum”:”asset number”,
 “siteid”:”site ID”
}
]
Data is asynchronously imported from a CSV file

The following call is used:

POST /maximo/api/os/object 
structure?action=importfile&name=filename.csv&async=1

CSV file content
Note: When doing a CSV export that is using a .notation attribute or its alias, the output was in lower-case. This issue is now fixed in Maximo Manage 8.5 and the output is now in upper-case.

The APIFILEIMPORT cron task retrieves the imported data and processes the content. The cron task runs every 30 minutes, and you can configure how frequently the cron task runs.

After you import data, a location URL that contains the status of the APIFILEIMPORT cron task is provided. If an error occurs while the cron task processes the data, the response to the location URL is embedded with a URL that connects to an error file, which you can download. When the error is resolved, import the file again. Ensure that you specify a new name for the name query parameter.

If you are using a JSON file, to enable this error response, the Filetype request header must be JSON.

The following response is an example of the response to the location URL when an error occurs. The file type is JSON.

{
 "iscomplete": true,
 "totalcount": 3,
 "errcount": 1,
 "requser": "Username",
 "fileimportreqqueueid": 3,
 "format": "JSON",
 "errorfile": "http://host:port/maximo/api/fileimporterrfile/3",
 "_rowstamp": "1521573",
 "iscancelled": false,
 "reqdatetime": "2019-02-20T14:08:22-05:00",
 "name": "testloc3.json",
 "href": "http://host:port/maximo/api/os/mxapifileimportqueue/_dGVzdGxvYzMuanNvbg--",
 "pindex": 3,
 "osname": "MXAPIOPERLOC"
}

Exporting data

If you export data by using REST APIs for a machine-to-machine integration, you must create an API key for the external client.

The default file format to export data is JSON.

For example, the following REST API call exports asset, site, and location data from the MXAPIASSET object structure as a CSV file:

GET /api/os/mxapiasset?oslc.select=assetnum,siteid,status,location&oslc.pageSize=100&
oslc.where=status=”OPERATING”&_format=csv&apikey=API key

For more information about the new REST APIs, see the Maximo® REST API.