Working with Attachments

Author: Steve Gotsch

Updated: August 2024

Audience: Everyone

Products Applicable: Jama Connect®

Use Case

Working with Attachments

Best Practice

Attachments can be uploaded via the API and linked to an item in just three calls.

1. Create an attachment item
2. Upload the file
3. Associate the attachment to an item

This should be simple once you've done it before. For example, we used Postman, a Google Chrome extension, for the demonstration because our documentation tool, Swagger, doesn't support file uploads.

Implementation

Step 1: Creating an Attachment Item
Attachment items contain the metadata for an attachment file. Creating an attachment item is similar to creating any other item, as it requires including the name and description.

Attachment Item JSON

Only the name field is necessary for creating an attachment item unless the Item Type was configured differently.

{
   "fields":{
      "name":"Poppy Flower",
      "description":"A pretty picture"
}
}

Post your attachment Item to this path:

POST /rest/v1/projects/{projectID}/attachments

The response will indicate that the attachment was created. Use the location to determine the ID:

{

   "meta":{

      "status":"Created",

      "timestamp":"2015-02-09T21:53:06.576+0000",

      "location":"http://localhost:8080/contour/rest/latest/attachments/1133"

}

}

Step 2: Upload the File
Upload a file using a PUT with form data. The endpoint is /rest/v1/attachments/{attachmentID}/file. The key for the form data should be 'file.'
Here is a screenshot of what it looks like in Postman:

Step 3: Associate Attachment Item with ItemTo clarify, the attachment item contains metadata about an attachment, which is different from a requirement found in Jama's explorer tree. You'll need to enable the Attachment widget on the item type before associating attachments to items.

POST the attachment item ID to the attachment endpoint of the item you would like to associate with. Any of these paths are acceptable:

• /rest/v1/items/{id}/attachments
• /rest/v1/testplans/{id}/attachments
• /rest/v1/testruns/{id}/attachments

The JSON is straightforward:

{

   "attachment":1133

}

That's it! You can make some other attachment-related operations listed below:

GET /rest/v1/attachments{attachmentId}

Gets attachment metadata

PUT /rest/v1/attachment/{attachmentId}/file

Uploads file to attachment.

GET /rest/v1/attachment/{attachmentId}/file

Download the attached file.

GET /rest/v1/attachments/{attachmentId}/comments

Gets all comments for attachment Item

GET /rest/v1/items/{id}/attachments

Gets attachments on an Item. This also works for test plans and test runs.

POST /rest/v1/items/{id}/attachments

Associates the attachment items to the item

DELETE /rest/v1/item/{id}/attachments/{attachmentId}

References

• Success Programs
• Success Catalog
• Datasheets
• Request a Solution Offering or Training from the Success Catalog

Please feel free to leave feedback in the comments below.