Working with Attachments using Jama Connect® REST API

Updated: October 2024

Audience: Jama Connect® Administrators 

Products Applicable: Jama Connect®

What are Attachments? 

Jama is designed to allow for great content flexibility, making it the ultimate definition of a system of record. While many of our customers are busy tapping away at the keyboard, they often associate their content with documents, images, graphs, tables, equations, and 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 contain the metadata for an attachment. The JSON payload can define a name, description, and other fields associated with the attachment's item type.

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

Note: Name is the default required field in the attachment item type.

POST the attachment Item using the following endpoint:

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:

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 before 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:

The JSON payload should contain the attachment item ID:

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

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:

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

Note: the attachment value is not the attachment item’s ID but 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:

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

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

Step 2: Parse out the Attachment Link

Parse out the embedded attachment link from the content of the retrieved object’s Rich Text field. 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:

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, you've successfully downloaded your attachment file to your working directory. 

Need Help Getting Started?

• If you need help uploading and downloading attachment files from Jama, check out our starter scripts, which are available on GitHub.

Please feel free to leave feedback in the comments below.