1. REST API Get Started V4REST API for Oracle Fusion Cloud Financials
  2. Reference
  3. Work with Attachments

Work with Attachments

This topic helps you with information that you can use to work with attachments associated with your REST resources.

Some tasks or business processes require that you store and maintain documents, images, or other files in the form of attachments for future reference. Attachments may exist in the form of large objects, text, an image, or a media file. In general, Oracle REST APIs support working with all types of attachments.

Based on your business requirement, you may access the REST resources that support attachments and perform any of the CRUD operations. To get the expected outcome, you must understand how to retrieve and store attachments using the HTTP methods. You also must know the specific resource attributes and the relevant values to pass in the request. These details could vary based on the data type of the attachment and the location where it's stored. In the following sections, let's understand a little more about how to work with attachments.

Storage

Oracle Applications Cloud supports working with attachments in two ways:
  • Storing attachments in a column within the same database table
  • Storing attachments in an external content repository such as Oracle WebCenter Content
How you perform the CRUD operations on attachments depends on where the attachments are stored and in which data type. The following table can help you understand a little more about these storage locations and some key points to consider while working with them.
Storage Location Key Points

If attachments are stored in the column of a database table
  • Stored content is accessible in the form of an enclosure link with support for BLOB or CLOB data type attachments.
  • Supported data types are large objects, text, and multimedia.

If attachments are stored in an external content repository
  • Facilitate download using the FileContents enclosure link that contains a reference to the file on the repository.
  • Attachment is stored as a child resource. It can include multiple attachments in the form of a list.
  • Supported attachment types are FILE, TEXT, and URL.

How you work with attachments depends on the way a particular business object is available as a REST endpoint and the permitted actions. Unless specifically restricted, all attachment resources support CRUD operations.

Let's look at a few examples so that you can understand how REST APIs handle attachments. As the most frequently used methods, the following sections focus on the GET and POST operations.

Get an Attachment

Let's take the example of an employee record for employee number 1731955. That record contains a photograph as an attachment used for displaying the profile picture. In this example, the content is stored in the column of a database. Here's the sample GET request: 

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955

The response might appear as shown here:

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      }, {
        "name" : "Picture",
        "type" : "attachment",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : false,
        "actions" : [ {          
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/octet-stream" ]
        } ]
      } ],
      "item" : {
        "links" : [ {
         ...
        }, {
          "rel" : "enclosure",
"href" : "http://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955/enclosure/Picture",
          "name" : "Picture",
          "kind" : "other"
        } ],
        "actions" : [ {
        } ]
      },
      "links" : [ {
        ...
      } ]
  }
}

In the links section of the response, you can see that the reference to the image stored in the database appears as an enclosure link. If the image is stored as a child attachments resource, the response would vary as shown here:

"items": [
        {
            "AttachedDocumentId": 300100548213429,
            "LastUpdateDate": "2021-11-09T03:20:09.640+00:00",
            "LastUpdatedBy": "JDoe",
            "DatatypeCode": "IMAGE",
            "FileName": "Picture.png",
            "DmFolderPath": null,
            "DmDocumentId": "UCMFA00058526",
            "DmVersionNumber": "58442",
            "Url": null,
            "CategoryName": "PROFILE_IMAGE",
            "UserName": "Default Image",
            "Uri": null,
            "FileUrl": "/content/conn/FusionAppsContentRepository/uuid/dDocID:58442?download&XFND_SCHEME_ID=1&XFND_CERT_FP=050B97D1B0F57AC305F88E205CE029181C4A07C8&XFND_RANDOM=-7556731710778165326&XFND_EXPIRES=1636479471368&XFND_SIGNATURE=a0GQlxttK~EVWFAxSwW1XuO0BEgzHYneIjl7R9NcECBJ~4y6TKRBlaHf~C0WHPG9wpm~rpWjpd-tZmGejYBgVmKz~Mx~oM~Fi1ZwAjjPRNxx0uqtmuf6s8XVBUMZgoXk1jG2lIWOv1HIjsGf17xcu1P2WJlGIrYCDRFTgMs5u1ZUGyUcLBNe4X59ty~DrNYPzrXhd2fCZ2koPPL12f2UtXIUClQuGFmxZPxOyWv6WKFzrZyXv4T5hcPNa3oeW7ULMERR-DLy0eDuOVPHF~AeoUUMvNkQYdxENs7qkE9XYgCyLD7iekdNvEL6~quGTbjMsxNYE-JozfVyCv4GsmDTtQ__&Id=58442",
            "UploadedText": null,
            "UploadedFileContentType": "image/png",
            "UploadedFileLength": 157,
            "UploadedFileName": null,
            "ContentRepositoryFileShared": "false",
            "Title": "Picture",
            "Description": "Image description",
            "ErrorStatusCode": null,
            "ErrorStatusMessage": null,
            "CreatedBy": "JDoe",
            "CreationDate": "2021-11-09T03:20:08+00:00",
            "ExpirationDate": null,
            "LastUpdatedByUserName": "John Doe ",
            "CreatedByUserName": " John Doe",
            "AsyncTrackerId": null,
"links": [
                .
                .
                .
                {
                    "rel": "enclosure",
                    "href": " http://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955/ child/ProductGroupAttachments/00020000000EACED0005770800005AF31A4423D40000000EACED0005770800005AF31A4423D3/enclosure/FileContents",
                    "name": "FileContents",
                    "kind": "other"
                },
                
            ]
 }
]

In the links section, you can notice that the href property for FileContents contains a link to download the attachment that's stored as a child resource.

Create an Attachment

To create an attachment, you must first determine the type of attachment and then pass the required information in the POST request. Let's consider the example of adding an image to a Product Catalog resource bearing product ID 100000011628005. If you're creating an attachment using a base64 encoded format of the image, include the encoded text as part of the request payload. Here's a sample POST request containing the encoded text: 

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X POST https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/ -d '{"Image": "/9j/4AAQSkZJRgABAQEASABIAAD/4QBQRXhpZgAASUkqAAgAAAABAGmHBAABAAAAGgAAAAAAAAABAIaSAgAbAAAALAAAAAAAAABTb2Z0d2FyZTogTWljcm9zb2Z0IE9mZmljZQAA/9sAQwAIBgYHBgUIBwcHCQkICgwUDQwLCwwZEhMPFB0aHx4dGhwcICQuJyAiLCMcHCg3KSwwMTQ0NB8nOT04MjwuMzQy/9sAQwEJCQkMCwwYDQ0YMiEcITIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIy/8AAEQgBaAHgAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNiOvQfC/xXWeZLXXIliLcC5T7uf9odq0p42nN2ehwYzhnGYePPG00u2/3HqmaNwFRpIssaujBkYZBHIIrgviveXVjoFpJazyQubjBMbEEjBrpqTUIOR42Ew0sTXjQTs5Ox6DkUZFfMH/AAkOs/8AQTu/+/po/wCEh1n/AKCd3/39NcX9oR/lPqP9T63/AD9X3M+n8ijIr5g/4SHWf+gnd/8Af00f8JDrP/QTu/8Av6aP7Qj/ACh/qfW/5+r7mfT+RRuFfMH/AAkOs/8AQUu/+/prY0f4h6=="}'

The response would contain reference as an enclosure link:

{
"rel" : "enclosure", 
"href" : "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/123456789/enclosure/Image", 
          "name" : "Image", 
          "kind" : "other" 
        }

Alternatively, if you want to create an attachment that's available as a child resource, you must specify a few attributes in the request. The following table lists the required attributes and indicative values based on the attachment type.

Attachment Type Required Attributes and Values

File

 
"DatatypeCode": "FILE",
"CategoryName": "<name of the category>",
"FileContents": "encoded file stream"

Free form text

 
"DatatypeCode":"TEXT"
"CategoryName": "<name of the category>",
"UploadedText":"Sample freeform text…"

URL

 
"DatatypeCode":"WEB_PAGE"
"CategoryName": "<name of the category>",
"Url": "<link to the web page/url>"

Taking the same example of adding an image to a Product Catalog resource bearing product ID 100000011628005, if you need to pass it as a file type of an attachment, here's how you would construct the POST request. 

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X POST https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/

And here's the sample request body:

{
        "DatatypeCode":"FILE",
        "FileName":"Image.png",
        "CategoryName":"CATALOG_IMAGE",
        "Title":"Image",
        "Description":"Image description",
        "FileContents":
        "R0lGODlhEAAQALMAAIuWq6WxwwFGevn9/9Xz//H7/+z6/+77//b9//r///z//////wAAAAAAAAAAAAAAACH5BAEAAAsALAAAAAAQABAAAARKcMlJq7026M1DDUQoih4FAmiqAtM5vqzkGnRNx4t77PyOu4WgMPgjAAiCpFJQKB4Rr5CTMKhaq7/AMcHtcnGSo2JMHoMXqzRmHQEAOw=="
    }

The response would be similar to what we saw earlier for the GET request example. The image would be accessible in the form of an enclosure link. 

"links": [
                .
                .
                .
                {
                    "rel": "enclosure",
                    "href": " 
http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/00020000000EACED0005770800005AF31A4423D40000000EACED0005770800005AF31A4423D3/enclosure/FileContents",
                    "name": "FileContents",
                    "kind": "other"
                },
                
            ]

To download the attachment, click the link provided in the href property of FileContents.

References

Your product may have specific resources that support attachments. Refer to your product-specific REST API guide for additional guidance.