Knowledge Base

 View Only

Attachments Attachments Attachments!

By Iman Bilal posted 08-29-2017 11:09


What are Attachments?

Jama is designed to allow for great flexibility of content, making it the ultimate definition of a system of record. While many of our customers are busy tapping away at the keyboard, they are often associating their content with documents, images, graphs, tables, equations, and so much more. External documents and images are referred to as attachments in Jama.


Uploading Attachments via REST API

There are two main ways to utilize attachments in Jama:

  1. Attach a file to an item
  2. Embed a clickable link to an attachment within an item's text


Adding an Attachment to a Jama Item

Attachments can be uploaded through our REST API and associated with an item in three quick steps:

Step 1: Create an Attachment Item

Attachment Items are items that contain the meta data for an attachment. A name, description, and any other fields associated with the attachments item type can be defined in the JSON payload.

This is exactly like filling out the name and description when an attachment is created in the UI:

Attachment Item JSON Payload



    "name""Poppy Flower",

    "description""A pretty picture"



Note: By default, Name is the only required field in the Attachment item type.

POST the attachment Item using the following endpoint:

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

You should receive a response confirming the attachment was created. Use the location to determine the ID of the newly created attachment item:








You have successfully created an attachment item!


Step 2: Upload the Attachment File

Files can be uploaded to Jama using a PUT with form-data to the following endpoint:

PUT /rest/v1/attachments/{attachmentID}/file

The attachmentID is the ID retrieved from the response location in step #1 above. If you receive a 200/201 response status from the server, you have successfully uploaded a file to the Jama attachment!

Step 3: Associate the Attachment With an Item

To associate an attachment item with a Jama item, the attachment widget must be enabled on the Jama item’s item type prior to establishing an association.

Attachments can be associated with items that contain a POST method for an attachment. The attachment item ID is required in all cases. The following attachment endpoints are available:

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


POST /rest/v1/testPlans/{testPlanID}/attachments


POST /rest/v1/testRuns/{testRunID}/attachments


The JSON payload should contain the attachment item ID:





You should receive a response indicating the status of your POST as shown below:





    "location":" http://{base_url}/rest/latest/items/2209254/attachments/1133"




The final result should appear in the attachment widget section of the object in Jama like this:


You have successfully associated an attachment with a Jama item using the REST API!


Embedding a Link to an Attachment in a Jama Object

Embedding clickable hyperlinks for attachments within content is also possible through our REST API. These appear in Rich Text fields as clickable links that can be used to download attachments.

Once an attachment item is created, and the attachment’s file is uploaded (steps #1 and 2 from the approach above), there are three steps to creating a clickable link to the attachment:

Step 1: Get the Attachment’s Attachment Value and File Name

Once an attachment is created in Jama, and its file has been uploaded, GET the attachment item using the following endpoint:

GET /rest/v1/attachments/{attachmentID}

Retrieve the attachment value from the fields section, as well as the attachment’s fileName (highlighted below):



      "id": 1133,

      "documentKey": "INF-ATT-31",

      "globalId": "GID-ATT-115929",

      "itemType": 89027,

      "project": 20319




      "createdBy": 18368,

      "modifiedBy": 18368,

      "fields": {



            "name"Poppy Flower,

            "description"A pretty picture,


      "resources": {

            "self": {

                "allowed": [





      "mimeType": "image/jpeg",

      "fileSize": 7295,

      "type": "attachments"



Note: the attachment value is not the attachment item’s ID, rather the attachment value stored in the fields section of an attachment object.

Step 2: Create a Hyperlink to your Attachment Item

Create a string with the following form:

<a href="https://{base_url}/attachment/{attachmentValue}/attachmentFileName">Clickable Text</a>


Step 3: Update Jama Item's Rich Text Field

The string from step #2 now needs to be inserted into a Rich Text field of an Item in order to be accessible via the UI. Any endpoint that creates or updates a Jama Item's content can be used to update/generate an item with the clickable link embedded in a Rich Text field. Below are a few available endpoints:

POST /rest/v1/items

PUT, PATCH /rest/v1/items/{itemID}

POST /rest/v1/testplans


PUTPATCH /rest/v1/testplans/{testPlanID}


POST /rest/v1/testruns


PUTPATCH /rest/v1/testruns/{testRunID}

A clickable link should now appear in the object’s Rich Text field as shown below:


Clicking on the hyperlink text should result in the attachment being downloaded:


You have successfully embedded a link to your Jama attachment item!


Downloading Linked Attachments 

An attachment's file can be downloaded using the previously created attachment link in three steps: 

Step 1:  Retrieve the Attachment Link

Retrieve the object containing an embedded attachment link. Below are a few available endpoints:

GET /rest/v1/items/{itemID}


GET /rest/v1/testruns/{testRunID}


Step 2:  Parse out the Attachment Link

Parse out the embedded attachment link from the retrieved object’s Rich Text field’s content. Parsing libraries such as JSOUP for Java and BeautifulSoup for Python are helpful for this step.


Step 3: Download the Attachment File

Download the file using the following endpoint:

GET /rest/v1/files

The request payload should contain the link URL that was parsed out in step #2 and will look like this:


If a response status of 200/201 is received, then you’ve successfully downloaded your attachment’s file to your working directory!

Need Help Getting Started?

For help getting started on uploading and downloading attachment files from Jama, check out our starter scripts available on GitHub.

#tutorial #REST