Attachments Attachments Attachments!

By Iman posted 25 days ago

  

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

{

  "fields"{

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

{

  "meta"{

    "status""Created",

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

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

  }

}

 

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:

{

  "attachment":1133

}

 

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

{

  "meta"{

    "status""Created",

    "timestamp":"2017-08-25T21:21:49.789+0000",

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

Screen_Shot_2017-08-30_at_11_58_16_AM.png

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 filename

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}

 

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

{

  "data"{

      "id": 1133,

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

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

      "itemType": 89027,

      "project": 20319

      "createdDate""2017-08-25T21:21:49.789+0000",

      "modifiedDate""2017-08-25T21:21:49.789+0000",

      "lastActivityDate""2017-08-25T21:21:49.789+0000",

      "createdBy": 18368,

      "modifiedBy": 18368,

      "fields": {

            "attachment"78574,

            "globalId""GID-ATT-115929",

            "name"Poppy Flower,

            "description"A pretty picture,

       }

      "resources": {

            "self": {

                "allowed": [

                    "GET"

                ]

             }

       }, 
      "fileName": 
"poppy.jpeg",

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

Screen_Shot_2017-08-30_at_12_01_37_PM.png


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/testplans/{testPlanID}
 

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:

https://{base_url}/attachment/{attachmentValue}/attachmentFileName

 

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.
0 comments
133 views

Permalink

Tags

  • Jama features and functionality
  • REST
  • Content Type
  • tutorial