IBM Maximo REST API Guide – Handling Attachments

Attachments in Maximo Asset Management are documents, files, or images that are attached to a resource such as an Asset or Service Request. The RESTful API supports the retrieval of attachments that are associated with resources.

To fetch, create, update, or delete an attachment for a resource by using API, such as MXAPIASSET, complete the following tasks:

Enable the attachments feature.
Configure the MXAPIASSET object structure with the DOCLINKS MBO as a child to the ASSET object.

Fetch the attachments

When you query a specific resource (using its ID) that has an attachment, a doclinks URL is returned for the attachment:

GET /oslc/os/mxapiasset/{rest id}?lean=1

{
  "assetnum": "1001",
  "changedate": "1999-03-31T16:53:00-05:00",
  "doclinks": {
    "href": "oslc/os/mxapiasset/{rest id}/doclinks"
  }
}

If you use the doclinks URL from the JSON data in the previous example, you receive a list of attached documents (reference to those documents) with the metadata.

GET oslc/os/mxapiasset/{rest id}/doclinks?lean=1

{
  "href": "oslc\/os\/mxapiasset\/{rest id}\/doclinks",
  "member": [
    {
      "href": "oslc\/os\/mxapiasset\/{rest id}\/doclinks\/75",
      "localref": "oslc\/os\/mxapiasset\/{rest id}\/doclinks\/0-75",
      "describedBy": {
        "identifier": "75",
        "fileName": "linearasset_screenshot.png",

The .../doclinks/{id} URL is the link to the actual attachment file. The content of the attachment can be fetched by,

GET oslc/os/mxapisset/{rest id}/doclinks/{id}

The .../doclinks/meta/{id} URL is the link to the metadata for the attachment file.

Create the attachments

The API supports the creation of attachments that are associated to resources. For example, after creating an asset, you want to attach a PDF file that describes the maintenance procedures for that asset.

To create a new attachment, you will need an doclinks URL for resource. As shown in fetching the attachment, take MXASSET as an example, the URL looks like as following,

"doclinks": {
  "href": "oslc/os/mxapiasset/{asset rest id}/doclinks"
},

An attachment is made up of two components:

Attachment file: You create an attachment by using the HTTP POST with binary content or base64 binary content. There is currently no support for multi-part messages.
Related metadata of the attachment: When creating an attachment for a resource there is a limited set of metadata that can be provided (along with the file) using HTTP Headers:

Header	Value	Description
slug	File Name	The name of the attachment file
encslug	File Name	If the attachment file name has non-ascii characters it can be provided in the header base64 encoded. It is suggested that you always base64 encode your file name using this property if you believe you might have a mix of non-ascii characters
Content-Type	“text/plain”	Based on the type of attachment - text/plain supports a .txt file
x-document-meta	Attachments	Tied to the DOCTYPES domain that defines the supported attachment types
x-document-description	Description	The description of the document
x-document-encdescription	Description	If the description has non-ASCII characters, it can be provided in the header base64 encoded. It is suggested that you always base64 encode your description using this property if you believe you might have a mix of non-ascii characters
custom-encoding	“base64”	This header facilitates testing using a browser client such as RESTClient (for FF). Allows you to paste in a base64 encoded image into the Body of the tool (otherwise you need to test with programmatic tool). You can use public tools to base64 encode your image file

Example:

POST oslc/os/mxapiasset/{asset rest id}/doclinks 
x-document-meta: FILE/Attachments
slug: test.txt
x-document-description:test file 

Body:
Hello this is my first test file

The response Location header contains the URL for the uploaded attachment (as shown in the following example).

Location: oslc/os/mxapiasset/{asset rest id}/doclinks/{id}

The GET on that URL will get the attached document that was uploaded before. Along with that, it also has a response header that is named Link, which has a URL to the metadata for this attachment.

Link: oslc/os/mxapiasset/{asset rest id}/doclinks/meta/{id}

This meta link can be used to get the metadata for the attachment. A GET on that link will fetch the JSON representation of the document description, mimetype etc as shown in the following example.

To create attachments of a WWW (URL) type, you can use the following request as an example:

POST /oslc/os/mxapiasse/{asset rest id}/doclinks
x-document-meta: URL/Attachments
slug: CNN
content-location: www.cnn.com
x-document-description:cnn web site

In the response, you get a Location header with the URL of the newly created URL attachment. Note that the URL was set on the content-location request header. The slug request header is used as the name of the attachment.

Another important thing to note: the x-document-meta request header has 2 parts - the URL type and document type. The URL type is a synonymdomain in Maximo Asset Management and hence hardcoding the values FILE or URL maybe a problem in case those values have been modified during installation. You could potentially do one of the 2

Avoid specifying the URL type altogether. The API framework defaults to the URL type based on your request. For example, if the request has the content-location header, it will be treated as a URL type with internal value of WWW. Otherwise it will treated as a URL type of FILE. In each of these cases the system will use the default external value for these internal values (FILE or WWW).
The other option would be to fetch the external values of the FILE and WWW types and then use that in the client side code to set the x-document-meta.

We tend to prefer the first approach as its simpler of the client.

Update the attachments

There is no support to update an attachment. To revise an attachment, you need to delete the current version and create a new version.

Delete the attachments

You can delete attachments by using the HTTP POST with the URL of the attachment and providing the x-method-override header with a value of DELETE.

POST oslc/os/mxapiasset/_MTAwMS9CRURGT1JE/doclinks/80 
x-method-override: DELETE

Handling attachments as part of the resource json

The following example adds two attached documents as part of asset creation:

POST /oslc/os/mxapiasset

{
  "assetnum": "TEST299",
  "siteid": "BEDFORD",
  "doclinks": [
    {
      "urltype": "FILE",
      "documentdata": "aGV5IGhvdyBhcmUgeW91",
      "doctype": "Attachments",
      "urlname": "greetingsabcd.txt"

In this example, the documentdata attribute has the base64 encoded document.

Below is an example of doing the same with WWW (url based) attachments:

POST /oslc/os/mxapiasset

{
  "assetnum": "TEST399",
  "siteid": "BEDFORD",
  "doclinks": [
    {
      "urltype": "URL",
      "doctype": "Attachments",
      "title": "espn",
      "newurlname": "www.espn.com",

We also support getting attachments inline as part of a json document. To do this just use the query parameter inlinedoc=1. An example shown below

GET /oslc/os/mxapiasset/{rest id}?inlinedoc=1

{
  "assetnum": "TEST299",
  "siteid": "BEDFORD",
  "doclinks": [
    {
      "urltype": "FILE",
      "documentdata": "aGV5IGhvdyBhcmUgeW91",
      "doctype": "Attachments",
      "urlname": "greetingsabcd.txt"

Edit this page on GitHub

Automation Scripts: Automation Scripts

Hierarchical Data: Dealing with Hierarchical Data