Managing 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.

Retrieving 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 request

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 body

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"
        }-
    ...
    -
}

Uploading 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 request

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 body

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

Uploading 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>

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

Using the Default HTML Form to Add a File Attachment

  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.

Downloading 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 request

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 body

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

{
data: "c2FtcGxlIGNvbnRlbnQgZm9yIGZpbGUgYXR0YWNobWVudA=="
}

Downloading 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 request

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 body

The file attachment SampleFileAttachment.txt is returned.

Downloading 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 Service Cloud 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.

    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.

Deleting 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

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