POST: Create an attachment

This topic provides instructions for using the POST operation to add an attachment.

Overview

To create an attachment instance, perform a POST on the attachment collection, passing either:

  • A JSON string.

  • An octet-stream (technical preview and subject to change).

Note: Bulk POSTs are not supported.

Attachments contain two different types of data that can be POSTed: 

  • The attachment entity details.

  • The attachment’s binary content. The binary content is generally created using client tools or libraries, not using a text editor.

The REST API supports content types of multipart/form-data and octet-stream data (technical preview and subject to change).

When supplying the attachment name in the request, extra spaces at the beginning or at the end of the file name are trimmed, and do not cause any errors.

You can specify a path for the attachment.

Back to top

Flow

  1. Create the attachment outside of ALM Octane using client tools or libraries.

  2. POST the attachment to an entity. The attachment must have an owner, and you specify the owner using an "owner" fields such as owner_work_item or owner_test. For an example, see POST request for json attachments.

  3. Tests: You can associate the attachment with specific test steps. You make this association by updating the test script with a PUT operation. For an example, see POST request of json attachment and PUT request to manual test steps .

Back to top

Examples

When creating an attachment, we specify the item to which the attachment is associated. This can be any work item, and other items such as runs and run steps.

Note that the Content-Type is multipart/form-data, and it accepts application/json format.

While posting, we associate the attachment with an owner entity. In this example, the attachment is associated with a work_item whose ID is 1002.

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/attachments
Content-Type: multipart/form-data; boundary=a1b2c3d4
Accept: application/json

--a1b2c3d4
Content-Disposition: form-data; name="entity"
Content-Type: application/json; charset=UTF-8

{
                "owner_work_item": {
                                "id": 1002,
                                "type": "work_item"
                },
                "name": "attachment.png",
                "description": "This is attachment.png image file"
}
--a1b2c3d4
Content-Disposition: form-data; name="content"; filename="attachment.png"
Content-Type: image/png
Content-Transfer-Encoding: base64

iVBORw0KGgoAAAANSUhEUgAAALAAAAAzCAIAAAC48RV/AAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAALRSURBVHhe7ZjhUewwDITph3roh3qoh36OOLYc
rSRHd445YNjv17Msr2R5J9y8lxshChqCADQEAWgIAtAQBKAhCEBDEICGIAANQQAaggA0BAFoCALQ
EASgIQhAQxCAhiDAXzTE5/vrS+H1/bNFyDJoCAJ8gyE+3oLnCoOT/FZDrLzjj0FDrOM/G0LepNFn
0GaiefsIgzV/pCPAvuwqQ6h9fbZWLBFVuyX4iAJblS4LrVKsObh43UKUTtx8Uqiijh6YnDkmDBE2
07oJ5zIY1plOIdivm/HBjf4EQcUB6tXCQ72dpOjgjp6hjlTKbzfKOEZ3gVlDHLeVUfR2WgDbC4KJ
TqRb/60GUo/3gKjJWZewkRzp5SSjJeRFRULf0eN0jmaN7qgQlpHd3sVFFvyGsHMI53LHsDClraKL
ygyUmJF31fwREwn6w1HnRSMNT6CDoaxQ2+/bdn2RSUO0FjW9o3Aug2ENdYKxdLKRRdVcBEVkFYEZ
J5q+akCg04vv1ksL4UrSf/AL0ftH+gXCuQTBU51gLJ10ZEE1F0GRQS87T/tC3GmIsNlVfpgwROvu
aOGuufjguQ4OCclHNqx2RIyIP2HIi+YahbFOC6WFJL1zXvBBLhtC+j/aMgkVH0x0vG6J7MnpyOxy
w0WMiC+3sQdNfyea5kY77lgvJHm2claoLXSRlUz8yZB7G44LYELr3AcznWh/F8vfxiw3XOTspYDW
f17Udrwf7KEmMyzjEkaFYgE5fZm5H5X65vL/DOoCej8clwQzHby87ORvY5YbLhKI+GGrMedFCy1U
qGF3TAVU8iOFbJOCOnCBOUOQaYL3fgg5rywkxlrylaAhnsxVQ/jPUv9i0BB/kVVfCMeavxg0xLO5
aoiC+vFRWfJtqNAQBKAhCEBDEICGIAANQQAaggA0BAFoCALQEASgIQhAQxCAhiAADUEAGoIANAQB
aAgC0BBEcbt9ATZhuQV8mjteAAAAAElFTkSuQmCC
--a1b2c3d4--

*** Response ***
{
                "total_count": 1,
                "data": [{
                                "type": "attachment",
                                
                                "id": "1001"
                }],
                "exceeds_total_count": false
}

See Add an attachment to a manual test script.

The Content-Type is application/octet-stream. The request body contains the file stream. The request query contains the file name and a reference to the entity that will own the attachment.

*** Request ***
POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/attachments?name=p01.jpg&owner_release={"type":"release","id":"1001"}
Content-Type: application/octet-stream
<@INCLUDE *C:\Downloads\p01.jpg*@>

The Content-Type is application/octet-stream and the ALM-OCTANE-TECH-PREVIEW request header is set to true for this technical preview resource. The request query contains the file name to upload and a reference to the entity that will own the attachment.

Note that this method allows you to set the attachment's name. In the following example, the uploaded file name was my_uploaded_image.jpg. It will be uploaded as an attachment with the name my_attached_image.jpg.

*** Login Request ***
curl -X POST \
-H "Content-Type: application/json" \
-c cookies.txt \
-d "{\"user\":\"<username>\",\"password\":\"<password>\"}" "http://<server_name>:<port>/authentication/sign_in"
*** Upload Request ***
curl -X POST \
-H "ALM_OCTANE_TECH_PREVIEW: true" \
-H "Content-Type: application/octet-stream" \
-b cookies.txt \
--data-binary @C:/my_files/my_uploaded_image.jpg \
"http://<server_name>:<port>/api/shared_spaces/<shared_space_id>/workspaces/<work_space_id>/attachments? \
name=my_attached_image.jpg&owner_work_item=<work_item_id>"

Back to top

See also: