Manage File Attachments

A file attachment is a file that's attached to or associated with an object. For example, a user can attach a screenshot of an error message, for an incident. You can use the Connect REST API to perform the following file attachment tasks:

• Retrieve a List of File Attachments for an Object
• Upload File Attachment Content as Base64-encoded Text
• Upload File Attachments by Using HTML Forms
• Download File Attachment Content as Base64-encoded Text
• Download Individual File Attachments
• Download all of the File Attachments for a Resource
• Download File Attachments for Custom Objects
• Delete File Attachments

Retrieve a List of File Attachments for an Object

Use the GET method with the following syntax to view the list of file attachments for a specific instance of a resource (that is, an object):

https://your_site_interface/services/rest/connect/version/resource/resource_id/fileAttachments

Request Body

There are no elements in the request body for this task.

Response Body

Returns an array of file attachments of a resource.

Example URL

Using the GET method with the following URL returns a list of files attachments associated with a specific incident object:

https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments

Example Response

The list of file attachments associated with the incident with ID 5 is returned:

{
    items: [3]
    0: {
        rel: "canonical"
        href: "https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/97"
        }-
    1: {
        rel: "canonical"
        href: "https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/98"
        }-
    2: {
        rel: "canonical"
        href: "https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/99"
        }-
    -
    links: [4]
    0: {
        rel: "self"
        href: "https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments"
        }-
    ...
    -
}

Upload File Attachment Content as Base64-encoded Text

Use the POST method with the following syntax to upload a file attachment of a specific instance of a resource (that is, an object):

https://your_site_interface/services/rest/connect/version/resource/ resource_id/fileAttachments

You can't modify the content of a file attachment after it has been uploaded.

Note:

The size of a file attachment must not exceed 20 MB.

Request Body

The request body must contain the name of the file attachment and the content of the file attachment encoded in Base64 format.

Response Body

There are no elements in the response body for this task.

Example URL

Using POST with the following URL adds a new attachment to the incident with ID 5:

https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments

Example Request

{
"fileName":" SampleFileAttachment.txt ",
"data":" c2FtcGxlIGNvbnRlbnQgZm9yIGZpbGUgYXR0YWNobWVudA=="
}

Upload File Attachments by Using HTML Forms

You can use HTML forms to upload file attachments. Using HTML forms allows you to upload multiple file attachments of different formats at the same time. You can also download the file attachments in the same format as they were uploaded. As an integration developer, you can use HTML forms as part of the user interface for a user to upload file attachments. When a user selects an appropriate file attachment, the HTML form and the file attachment are sent to the application for uploading.

Uploading a file attachment using HTML forms is a POST method. You can't make any changes to the file attachment after it has been uploaded.

Note:

The size of a file attachment must not exceed 20 MB.

You can create your HTML form or use the default form that the application provides. The default HTML form is available at the following location:

https://your_site_interface/services/rest/connect/version/resource/resource_id/fileAttachments/formData[?pretty=true]

You can also find the form by using the create-form relational link under links at the following location:

https://your_site_interface/services/rest/connect/version/metadata-catalog/resource/fileAttachments

Typical HTML Form for Uploading a File Attachment

<form action="https://your_site_interface/services/rest/connect/
version/resource/resource_id/fileAttachments" method="POST" 
enctype="multipart/form-data">
<!-- File Attachment [0] -->
    <p>
        <label>ContentType</label>
        <br>
        <input name="contentType[0]" value="application/octet-stream" 
        pattern='^[a-zA-Z-]+/[-a-zA-Z0-9.+_*]+$' title='^[a-zA-Z-]+/[-a-zA-
        Z0-9.+_*]+$' maxlength="128" type="text">
    </p>
    <p>
        <label>Data</label>
        <br>
        <input name="data[0]" type="file" required>
    </p>
    <p>
        <label>FileName</label>
        <br>
        <input name="fileName[0]" pattern='^[^\t\n\/:*?"<>|]*$' 
        title='^[^\t\n\/:*?"<>|]*$' maxlength="100" type="text" required>
    </p>
    <p>
        <label>Description</label>
        <br>
        <textarea name="description[0]" maxlength="1333" rows=6 ></textarea>
    </p>
    <p>
        <label>Name</label>
        <br>
        <input name="name[0]" pattern='^[^\t\n]*$' title='^[^\t\n]*$' 
        maxlength="40" type="text">
    </p>
    <p>
        <label>Private</label>
        <input name="private[0]" type="checkbox">
    </p>
    <br>
    <input type="submit" id="submit" value="Upload">
</form>

Using the Default HTML Form to Add a File Attachment

The following example explains how to use the default HTML form to add a file attachment to the incident with ID 5.

1. Download the HTML form from your company's site, for example:

   https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/formData

2. If you plan to use a new HTML form other than the default form, verify the following in the HTML form:
   • The value of the action attribute is the URL of the appropriate instance of the resource (that is, the object) with which you want to associate the file attachment. In this example:

     action="https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments"

   • The value of the method attribute is POST.
   • The value of the enctype attribute is multipart/form-data.
3. After you download the form, open the form using a text editor and make the necessary changes, as required.

You can now use this HTML form in your client-side application code to let users upload file attachments.

Download File Attachment Content as Base64-encoded Text

Use the GET method with the following syntax to download a file attachment of a specific instance of a resource (that is, an object):

https://your_site_interface/services/rest/connect/version/resource/ resource_id/fileAttachments/fileAttachment_id/data

The following table lists the request path parameter:

Name	Type	Description
fileAttachment_id	integer	The primary key identifier of the file attachment, for example, a file attachment with ID 97.

Request Body

There are no elements in the request body for this task.

Response Body

The response body contains the content of the file attachment in Base64 format. You must decode the encoded Base64 content to view the actual content of the attachment.

Example URL

This example gets the data of file attachment with ID 97 of the incident with the ID 5 by using the GET method with the following URL:

https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/97/data

Example Response

The content of the file attachment with ID 97 is returned in Base64 format:

{
data: "c2FtcGxlIGNvbnRlbnQgZm9yIGZpbGUgYXR0YWNobWVudA=="
}

Download Individual File Attachments

You can use the download query parameter to download a file attachment instead of downloading the content of the attachment. Using the download query parameter eliminates the process of decoding the Base64 data, which is a complex process for files other than text files.

File attachments are returned in the same format as they were uploaded. For example, if the file was uploaded in a binary format, then the downloaded file attachment also contains the information in binary format.

Use the GET method with the following syntax to download an individual file attachment of a resource:

https://your_site_interface/services/rest/connect/version/resource/ resource_id/fileAttachments/fileAttachment_id?download

The following table lists the request path parameter:

Name	Type	Description
fileAttachment_id	integer	Primary key identifier of the file attachment, for example, a file attachment with ID 97.

Request Body

There are no elements in the request body for this task.

Response Body

The file attachment associated with the incident in the same format as the attachment was uploaded.

Example URL

This example retrieves the file attachment having an ID value of 97 of the incident having an ID value of 5 in the same format as the uploaded attachment.

Using the GET method with the following URL returns the file attachment with ID 97:

https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/97?download

Example Response

The file attachment SampleFileAttachment.txt is returned.

Download all of the File Attachments for a Resource

You can use the download query parameter to download all of the file attachments for a resource. Starting with the February 2017 release, the attachments are downloaded in a single, gzip-compressed .tar archive (.tgz file).

This procedure assumes that you are logged in to the Oracle B2C Service site.

Note:

In the February 2017 release, the optional compress parameter is available, but it does not perform any action because tgz is the only option.

1. Enter the following syntax into a browser:

   https://your_site_interface/services/rest/connect/version/resource/resource_id/fileAttachments?download

   Note:

   You can also use .../fileAttachments?download&compress=tgz, but it isn't necessary.

   Example URL

   This example downloads the file attachments for the incident having an ID value of 1:

   https://mysite.example.com/services/rest/connect/latest/incidents/1/fileAttachments?download

   A window appears to tell you that you have chosen to open the downloadedAttachment.tgz file.

2. Select the Save File radio button if it isn't already selected, then click OK.
3. Select a directory in which to save the .tgz file, then click Save.

   You can also rename the file if you want.

4. Decompress and extract the archive to retrieve the downloaded attachments.

Download File Attachments for Custom Objects

The syntax for downloading file attachments for custom objects is quite similar to the syntax for downloading file attachments for standard objects. The only difference is that for custom objects you need to use 'FileAttachments' instead of 'fileAttachments' in the URL.

To download individual file attachments for a custom object, use the GET method with the following URL:

https://your_site_interface/services/rest/connect/version/resource/resource_id/FileAttachments/FileAttachment_id?download 

To download all of the attachments for a custom object, use the following syntax and enter the URL into a browser:

https://your_site_interface/services/rest/connect/version/resource/resource_id/FileAttachments?download

Delete File Attachments

Use the DELETE method with the following syntax to delete a file attachment of a specific instance of a resource (that is, an object):

https://your_site_interface/services/rest/connect/version/resource/resource_id/fileAttachments/fileAttachment_id

The following table lists the request path parameter:

Name	Type	Description
fileAttachment_id	integer	Primary key identifier of the file attachment, for example, a file attachment with ID 97.

Request Body

There are no elements in the request body for this task.

Response Body

There are no elements in the response body for this task.

Example URL

Using the DELETE method with the following URL deletes the attachment having an ID value of 97 for the incident having an ID value of 5:

https://mysite.example.com/services/rest/connect/v1.4/incidents/5/fileAttachments/97