API Cookbook

Executing Tests through the Jama REST API

In Jama Connect, there is a flow for executing test cases through the API. This guide will give you an overview of the testing-related objects in Jama Connect and show you the API calls needed to take a test all the way through execution. Some examples will be given from some of our own implementations at Jama.

Getting Familiar with Jama Connect Test Center Objects and Concepts

There are some core objects and concepts to have in mind when working with the Test Center.

Test Case Item

A Test Case Item is like a regular item in Jama, with extra fields (such as steps) and capabilities (it can be executed). Test Cases are created inside Projects just like items, independent of Test Plans. They are also versioned like other items.

Test Run Items

A Test Run Item can be thought of as an execution instance of a Test Case Item. They are created by the system when a Test Cycle is created inside a Test Plan, and they are updated with a status and actual results when executed. A Test Case could have many Test Runs associated with it. These cannot be created directly; this is the reason there is no POST in the /testruns REST endpoint.

Test Plans

A Test Plan is a collection of Test Cases grouped into Groups for organization and Cycles for execution. Test Plans can be created directly.

Test Groups

Test Groups are a grouping of Test Cases inside a Test Plan. They have no direct impact on the way Test Cases are executed; they exist mostly to allow users to group Test Cases into some sort of meaningful sections. For instance, a Test Plan could have groups based on functional breakdowns like "Tree Operations", "Items", etc. Although they are not pertinent to execution, each Test Plan must have at least one Test Group in which to place tests. Test Plans are created with a group called "Default Test Group" which can be used or replaced with custom groups.

Test Cycles

Test Cycles are a collection of Test Run Items that correspond to a particular execution of a Test Plan. For example, you could have a Test Cycle for each release candidate build, or Test Cycles for different browsers, depending on what makes sense for your testing. This terminology may be a bit confusing at first when coming from other test management systems, but the thing to keep in mind is that a "Test Run" is a single item, and a "Test Cycle" is a collection of Test Runs that have been run together at the same time for the same organizational purpose.

When a Test Cycle is created, all Test Case Items in that Test Plan have corresponding Test Run Items created in the system for that Test Cycle. Accordingly, a Test Cycle must be created before any Test Case can be executed. Test Cycles cannot be created independently of a Test Plan (there is no POST in the /testcycles endpoint).

An Example: These concepts as written definitions are a bit tricky, so here is a bit of a rundown on how we test internally:

We have a master regression library with hundreds of Test Case Items that we can test. At the time of each release regression, we create a few different Test Plans based on different configurations of the product, in our case, "Release 8.20 - Hosted", "Release 8.20 - Clients", "Release 8.20 - Server & Database". Inside those Test Plans, we add all, or a subset, of the Test Cases in the regression library, grouped by hierarchy, which, in our case, corresponds to areas of the product like "Stream" and "Projects". To execute these tests, we create one or more Test Cycles in the Test Plan. The "Release 8.20 - Clients" plan, for instance, tests different browsers, so there are cycles like "MacOS Chrome", "Windows Firefox", "Internet Explorer", etc.

Much of our regression library is automated, and our automation tooling executes, and updates results via the API using methods similar (but with much more wrapping) to what will be outlined below.

The Process

This process assumes you already have created Test Case Items that you want to execute. If you are only updating existing executions, you may need to skip further down in the guide.

Creating a Test Plan

First, a Test Plan must be created. If you are planning to use an existing Test Plan that has already been created (using the API or UI), you can skip this section.

POST /testplans with a payload like:

{
"project": 43,
"fields": {
"name": "Connect Plan 1"
}
}
							

project
is the API ID of the project where the Test Plan will be created

name
is the only required field in the payload

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T18:46:54.094+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494",
"id": 20494
}
}
							

You will need the id for further operations.

Adding Test Cases to a Test Plan

Test Cases are organized in Test Plans by groups. These groups are only for classification and have no bearing on the way that Test Cases are executed. However, test cases must be added to a Group in the Test Plan; they cannot be added to a Test Plan directly. You can either use the "Default Test Group" present in every Test Plan, or create new groups.

To find the default group:
GET /testplans/{testPlanId}/testgroups
where {testPlanId} is the API ID of the existing test plan, (from above, 20494)

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T19:16:01.311+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 1,
"totalResults": 1
}
},
"links": {},
"data": [
{
"id": 157,
"name": "Default Test Group"
}
]
}
							

In a brand-new Test Plan, "Default Test Group" will be the only group. You will need its id if you plan to add test cases to it, or:

To add your own group:

POST /testplans/{testPlanId}/testgroups
with a payload like:
where {testPlanId} is the API ID of the existing test plan (from above, 20494)

{
"name": "Stream"
}
							

name
is the only required field in the payload

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T19:20:35.340+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494/testgroups/160",
"id": 160
}
}
							

You will need the id for further operations

To add a Test Case to a Group:

At this time, there is no batch operation for adding Test Cases, so each test case must be added individually using:

POST /testplans/{testPlanId}/testgroups/{testGroupId}/testcases
with a payload containing a single test case id like:

where {testPlanId} is the API ID of the existing test plan (from above, 20494) and {testGroupId} is the API ID of the Test Group (from above, 157 for the default group, 160 for the custom)

{
"testCase": 20497
}
							

testCase
is the only item in the payload and should be set to the API ID of the Test Case you want to add

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T19:36:44.452+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494/testgroups/160/testcases/20497",
"id": 20497
}
}
							

The id returned in this case should match the id of the Test Case you provided in the payload

Creating a Test Cycle

A Test Cycle must be created to execute tests. Test Cycles are created through an existing Test Plan.

POST /testplans/{testPlanId}/testcycles
with a payload like:
where {testPlanId} is the API ID of the existing test plan (from above, 20494)

{
"fields": {
"name": "Internet Explorer",
"startDate": "2018-06-06",
"endDate": "2018-06-13"
}
}
							

name, startDate, and endDate are the only required fields in the payload. Note that there are other payload options for specifying which Test Groups and statuses that are added to the Cycle, but those won't be discussed here. Consult the API documentation for those options.

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T20:39:05.921+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testcycles/20536",
"id": 20536
}
}
							

You will need the id for further operations

Finding an Existing Test Cycle:

If you need to work with an existing Test Cycle, it can be found in this manner.

GET /testplans/{testPlanId}/testcycles where {testPlanId} is the API ID of the existing test plan (from above, 20494)

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-08T15:57:09.863+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 2,
"totalResults": 2
}
},
"links": {
... omitted for brevity ...
},
"data": [
{
"id": 20510,
"documentKey": "JEET1-TSTCY-17",
"globalId": "70957",
"itemType": 36,
"project": 43,
"createdDate": "2018-06-07T19:58:19.000+0000",
"modifiedDate": "2018-06-07T19:58:19.000+0000",
"lastActivityDate": "2018-06-07T19:58:19.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTCY-17",
"globalId": "70957",
"name": "Build 2018-06-06",
"testPlan": 20494,
"startDate": "2018-06-07",
"endDate": "2018-06-15",
"description": "",
"project": 43
},
"resources": {
"self": {
"allowed": [
"GET",
"PUT",
"PATCH",
"DELETE"
]
}
},
"type": "testcycles"
},
... second object omitted for cookbook example brevity ...
]
}
							

You will need the id for further operations

Executing a Test

You now have almost all the data needed to record a test execution. Before you can do that, though, you need to find the actual Test Run object created when you created the Test Cycle. You will need the id of the Test Case Item, the Test Plan, and the Test Cycle

GET /rest/v1/testruns?testCycle={testCycleId}&testCase={testCaseId}&testPlan={testPlanId}
where {testPlanId} is the API ID of the existing test plan (from above, 20494), {testCycleId} is the API ID of the Test Cycle (from above, 20536 for the created one, 20510 for the existing), {testCaseId} is the API ID of the Test Case to be executed (from above, 20497)

If successful, you will get a response that looks like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T21:01:36.530+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 1,
"totalResults": 1
}
},
"links": { ... removed for cookbook example brevity ...
},
"data": [
{
"id": 20539,
"documentKey": "JEET1-TSTRN-520",
"globalId": "70962",
"itemType": 37,
"project": 43,
"createdDate": "2018-06-07T20:39:02.000+0000",
"modifiedDate": "2018-06-07T20:39:02.000+0000",
"lastActivityDate": "2018-06-07T20:39:02.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTRN-520",
"globalId": "70962",
"name": "One",
"testPlan": 20494,
"testCycle": 20536,
"testRunSetName": "Internet Explorer",
"testCase": 20497,
"description": "",
"modifiedDate": "2018-06-07",
"testRunStatus": "NOT_RUN",
"project": 43,
"forcePassed": false
},
"resources": {
"self": {
"allowed": [
"GET",
"PUT",
"PATCH"
]
}
},
"testCaseVersionNumber": 1,
"testCaseCurrentVersionNumber": 1,
"sortOrderFromTestGroup": 1,
"testGroup": [
20536,
160
],
"type": "testruns"
}
]
}
							

If you have specified the id for Test Case, Test Plan, and Test Cycle, you should get one Test Run result in the data. You will need the id for further operations.

Next, you will need to either use PUT or PATCH to update the status of this test run:

Test Runs without Steps:

On test runs without steps, you can simply update the testRunStatus field.

PATCH /rest/v1/testruns/{testRunId}
with a payload like:
where {testRunId} is the API ID of the Test Run (from above, 20539)

[
{
"op": "REPLACE",
"path": "/fields/testRunStatus",
"value": "PASSED"
}
]
							

PUT /rest/v1/testruns/{testRunId}
with a payload like:
where {testRunId} is the API ID of the Test Run (from above, 20539)

{
"fields": {
"testRunStatus": "BLOCKED"
}
}
							

Valid values for /fields/testRunStatus are PASSED, NOT_RUN, FAILED, INPROGRESS, and BLOCKED.

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T21:14:14.611+0000"
}
}
							

Test Runs with Steps

On test runs with steps, you must pass the entire array of test steps (in the original order) with new statuses.

Here is an example of a Test Run object with steps. Note that the testRunSteps array is implicitly ordered by the step number as seen in the UI:

{
"id": 20569,
"documentKey": "JEET1-TSTRN-525",
"globalId": "70967",
"itemType": 37,
"project": 43,
"createdDate": "2018-06-11T21:34:09.000+0000",
"modifiedDate": "2018-06-11T21:34:09.000+0000",
"lastActivityDate": "2018-06-11T21:34:09.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTRN-525",
"globalId": "70967",
"name": "One",
"testPlan": 20494,
"testCycle": 20536,
"testRunSetName": "Internet Explorer",
"testCase": 20497,
"description": "",
"testRunSteps": [
{
"action": "You do something",
"expectedResult": "Something happens",
"notes": "",
"status": "NOT_RUN"
},
{
"action": "You do something else",
"expectedResult": "Something else happens",
"notes": "",
"status": "NOT_RUN"
}
],
"modifiedDate": "2018-06-11",
"testRunStatus": "NOT_RUN",
"project": 43,
"forcePassed": false
}
							

Given the two steps above, you can do the following:

PUT /rest/v1/testruns/{testRunId}
with a payload like:

{
"fields": {
"testRunSteps": [
{
"status": "PASSED"
},
{
"status": "PASSED"
}
]
}
}
							

or

{
"fields": {
"testRunSteps": [
{
"status": "FAILED"
},
{
"status": "PASSED"
}
]
}
}
							

The testRunStatus for the Test Run will then be set automatically according to the status field on the steps.

Congratulations! You've executed a Test Case through the API!

What triggers the Last Activity Date?

Along with create date and modified date, we record the last activity date on every item. While modified date tracks the last time an item was saved, last activity date tracks when the last activity around the item happened. Below we list the types of events that last activity date should be triggered by.

· Item Updates
· Create new Item
· Edit and save Item
----- Note: deleted items cannot be seen so the last activity date is not visible.
· Comments On an Item
· Adding a comment directly to the item
· Deleting a comment that is directly on the item
· Relationships To and From an Item
· Adding a relationship to and from the item
· Removing a relationship to or from the item
· Tags on an Item
· Adding a tag to the item
· Removing a tag to the item
· Attachments on an Item
· Adding attachment to an Item
----- Note: Updating an attachment does not change the last activity date for the items it is a part of.
· Links on an Item
· Adding a link to an Item
· Editing a link on an Item
· Removing a link on an Item
· Reviews and Baseline
----- Sending items and creating baselines does NOT update the last activity date
· Executing Test Run *Only* updates test run's last activity date

Searching with abstract items endpoint

This document will review how you can use the abstract items endpoint to search for items with customized filters. Our abstractitems endpoint offers the best search and filtering capabilities in our API.

Abstract items a generic resource for getting the various types of items in Jama. This resource will return items you can pull from /items, /testplans, /testcycles, /testruns, /attachments. While there are a few endpoints within the abstract items resource, this article will focus on the search capabilities of the GET /abstractitems endpoint.

GET /abstractitems

Response Model

This endpoint returns an array of items. You can review our data model and our paging on our Dev portal. This endpoint also has support for our includes feature. The includes feature lets you get more information out of your results without making more calls and it is recommended to use with this endpoint.

Search Parameters

This endpoint offers many query parameters that you may use to narrow your results to precisely what you are looking for. We will cover these parameters in more detail later, for now let's consider some basic rules so you can correctly set up your query.

Matching Lists
Valid for: project, itemType, release, documentKey, contains

If you would like to provide more than one value for a parameter, you may repeat the parameter. For example, if you want to see all items in either project 15 or 20, then you can make a request like this:

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?project=15&project=20'
							

Remember that when the parameter is repeated, you are grouping the values together with OR expressions. You will get broader results as you add more parameters of the same type.

Matching Date Time Fields
Valid for: createdDate, modifiedDate, lastActivityDate

The date base parameters operate a little differently. You may provide one or two ISO8601 values. When one date time is provided, it will return items which match that field within the range from the date provided to the time of the request. When two values are provided, it will return items which match that field within the range of the two provided date times. The date values should use the ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. Note that these date time formats are set using the UTC timezone or zero timezone offset.

In this example, we would get all items with a modifiedDate from 2018-06-19T21:29:15.037Z up to the time the request is made:

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?modifiedDate=2018-06-19T21:29:15.037Z'
							

This example will return all items with a created date between 2018-06-01T00:00:00.000Z and 2018-06-07T00:00:00.000Z:

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?createdDate=2018-06-01T00:00:00.000Z'&createdDate=2018-06-07T00:00:00.000Z'
							

Sorting Results
Parameter: sortBy

After you've chosen your filters, you may want to sort the results you get back. If you do not provide a sortBy value, results will default to sorting by sequence in ascending order and then by documentKey in ascending order. You may provide one or more fields to sort by and they will be used in the order they are sent in.

You must format the sortBy value this way:

{fieldname}.{order}

where fieldname is the fieldname and order are "asc" for ascending, or "desc" for descending.

This example will sort results by project in ascending order first, and then by last activity date descending second:

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?sortBy=project.asc&sortBy=lastActivityDate.desc'
							

Mix and Matching Parameters
Valid for: project, itemType, release, documentKey, contains, createdDate, modifiedDate, lastActivityDate

You may use any combination of query parameters in your query. So, you will be able to find all defects (specific item type id) from 2 different projects, that must contain the word "vegetables". When constructing these types of queries, remember this basic rule:

Duplicated parameters are grouped together with OR expressions.

These sets of parameters are then ANDed with each other.

For example, consider this request:

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?project=1&project=2&itemType=27&contains=vegetables'
							

There are 2 project params, 1 item type param, and 1 contains param. The logical expression for filtering results will look like this:

(project = 1 OR project = 2) AND (itemType = 27) AND
(contains = vegetables)
							

From here it should be possible to create complex filters on the fly.

Parameter Details

Contains

- The contains param lets you find items whose content contains your provided string values. Additionally, you can use some Lucene syntax if you format your string correctly.

In this example, Jama would return all items where the content contains the word "fire".

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?contains=fire' -H
							

An item will be matched if "fire" shows up in the name, description, any text field, and even the label of a picklist option if that option is set to the item. the case is ignored.

If you are interested in building more complex queries to filter on specific fields,

Simply wrap the same expression with double quotes and use it with the contains query params.

curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?contains="name:
"fire" AND name: "water""'
							

Please note that this works the same as the search bar in the UI. the main twist is that wild cards may be added to your Lucene query. When specifying fields, remember to use the name of the field and not the display or label. We are considering a different implementation for Lucene queries, so you may have better control.

project

- This simply matches items with the same project id.

itemType

- This simply matches items with the same item type id.

documentKey

- This simply matches items with the same document key.

release

- This simply matches items with the same release id.

createdDate

- See the above section on matching dates. This parameter will match with the created date of an item. Created date is set when it is first created.

modifiedDate

- See the above section on matching dates. This parameter will match with the modified date of an item. Modified date is updated when an items content changes and a new version is made.

lastActivityDate

- See the above section on matching dates. This parameter will match with the last activity date of an item. Last activity date is more sensitive to changes that are not reflected with the modified date. Comments directly on the item, relationships made to the item, changes to the location of the item, attachments added to an item will update the last activity date. More details description of changes to come.

Abstract Search - Lucene Parameters, Functions, and Limitations

-----------

Jama uses a version of Lucene search to help drill down into Abstract Items. It is important to understand the viable Parameters that are available, and the expected results from these parameters. Below you will find a breakdown of the Parameters. If we missed a scenario, please let us know!

Admins and API Developers should also be aware of the limitations of Lucene searches. For example, Jama will NOT be able to guarantee an exact match without using parameters to refine the search results. With the way Lucene data is indexed, exact match is difficult at best. Jama plans to continue to review ways to fine-tune these processes.

Example:

Assume 5 items have been created in the same project:

Item 1 - Name: Alpha
Item 2 - Name: Alpha Beta
Item 3 - Name: Beta Alpha
Item 4 - Name: Beta
Item 5 - Name: Happy Path with an item Description: includes the word "Alphabet"

It should be noted that (as seen in swagger) there is an application of bitwise OR operators. When applying a single string such as "Alpha Beta" the wild card parameters are taking the literal characterizations and searching for matches. If you structure requests which are looking for finite data inside specific fields such as IDs, you need to ensure you use multiple contain requests else you will create un-achievable requests

For more details on Lucene Syntax, feel free to peruse the official Apache documentation.
For more details on Bitwise operators, see the Wikipedia page on Bitwise operations.

REST Attachments

Attachments can be uploaded through our REST API and associated with an item in three calls. First, you must create an attachment item, then upload the file, and finally associate the attachment to an item. This should be straight forward after you have done it once. This document should help explain the steps clearly.

I will be sharing how to do this with Postman, a Google chrome extension.

Step 1: Create an Attachment Item

Attachment Items are items that contain the meta data for an attachment. You may define the name and description, or any other fields associated with the attachments item type.

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

Attachment Item JSON

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

Only the name field is required to create an attachment item unless the Item Type has been configured differently.

Post your attachment Item to this path:

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

You should get a response back saying 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/v1/attachments/1133"
}
}
							

Great, now you have an Attachment item. Next you need to upload the file to this item!

Step 2: Upload the file

You can 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 Item

To be clear, the attachment item is an item that has the meta data about an attachment. An Item is any old item you are familiar with in Jama, a requirement, test run, or anything else. You must have the Attachment widget enable on the item type before associating attachments to items.

You simply 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 very simple:

{
"attachment":1133
}
							

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

REST Attachments (Alt writeup)

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 within in Jama:
· Attach a file to an item
· Embed a clickable link to an attachment within an item's text

Attaching a File 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/v1/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.

If you receive a 200/201 response status, 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/v1/items/2209254/attachments/1133"
}
}
							

The 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 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 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
PUT, PATCH /rest/v1/testplans/{testPlanID}
POST /rest/v1/testruns 
PUT, PATCH /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/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. (https://github.com/JamaSoftware/UploadAttachments)

API Relationship Rules, Empty rule sets

When creating Relationships between items in Jama Connect, API Users sometimes experience API behavior which appears to contradict my Project Relationship rules, resulting in a “Bad Request” and a “Relationship violates rules configured for the project: from item ID: X, to item ID: Y”

Two things to pay attention to here:

1. API request directions From-To matters!
2. Relationships Rules: Small differences can have big impact.

API request directions From-To matters!

Users of the API should be cognizant that fromItem and toItem are specific functions and dictate which rules are to be used.

• The input value fromItem is the form item key that will be looked at to check for Relationship rules.
• Conversely, toItem is always the element which is being linked to.
• If the rules for a projects are different for each item, then the From and To will definitely matter

Relationships Rules: Small differences can have big impact.

Relationship Rules are Fickle on purpose. Because Relationship Rules will likely vary between orgs and projects, it is impossible to hit every scenario, but check below for one very complex scenario which hits on many of the major themes in Relationship creation and cross project usage.

In one scenario, ProjA and ProjB are expected to relate to each other

• Project A has rules that allows Features to be Derived From Requirements

• Project B has also been applied to a rule set, but where no rules were created.
  • This was a purposeful action by the Admin
  • The creation (and application) of this empty rule set states to Jama “Items in this Project are not allowed to be related.”

• When linking an ASYS Req in ProjA to a Feat in ProjB, the Admin and users have an expectation that this will function.
  • In the above scenario, all links fromItem ProjA --> toItem ProjB would be blocked and marked as “Bad Request”.
    While the rules of ProjA would allow a relationship, ProjB (which is purposefully empty) denies that these relationships are allowed.
  • The Jama API is required to look at both rule sets and trust/follow instructions as presented.
    
  • To allow creation of these relationships across projects, one of the following is required
    • Fix: ProjB rules should be clicked to “Allow relationships with item types not in this rule”
      Data would be allowed to link to ProjB items to other ProjB in any manner as no rules are expressed
      Data would only be allowed to link ProjB to ProjA items that follow ProjA rules.
      
    • Fix: ProjB is removed from the empty Rule set.
      Data would then be linkable as it is no longer using explicitly omitted rules.
      
    • Fix: ProjB has rules created that match Admin prescribed functions.

Creating Test Cases and Test Steps via API

Note that Jama only supports JSON but the Content-Type value is required

Creating Test Cases and Test Steps via API

Test Cases are different than Test Cycles, Test Plans, and Test Runs. While each of these elements have strong workflows and separate REST endpoints for their management, Test Cases are nothing more than Normal items with a specific json structure needed to craft the steps. This Cookbook item will cover the automated creation of a Test Case via the API.

Start by hitting up the POST /items endpoint. Create your call to the service as you would any other Item creation request, but pay attention to the following Structure changes to include Test Steps

{
  "globalId": "string",
  "project": 0,
  "itemType": 0,
  "childItemType": 0,
  "location": {
    "parent": {
      "item": 0,
      "project": 0
    }
  },
  "fields": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

{
"project": 57,
"itemType": 26,
"childItemType": 0,
"location": {
   "parent": {
      "item": 14771
       }
    },
"fields": {
   "name":"API Generated Test Case with two Steps",
   "description":"Two Test Steps will be created for this Item",
   "testCaseSteps": [{
      "action":"Step 1",
	  "expectedResult":"Http 200 result",
      "notes":"none"
      },
      {
      "action":"Step 2",
	  "expectedResult":"Dancing Bears",
	  "notes":"none"
	  }]
	}
}

• For this example, I have omitted the global ID reference as I have no need to manually set one (and rarely do).
• I am also omitting the Parent element of location as i need this grouped under my Test Cases set.
• From here the POST call is normal until you get to testCaseSteps
  • Note the additional square bracket [..] opening and closing the testCaseSteps. This is the same bracket you see structurally in the Data model when a TestCase is returned to you via GET.
• Each testCaseStep is included as a comma separated {..} subset.

On submission, I receive back an HTTP 201 response advising of my brand new ItemID

​

Inside Jama, I see my new item with testCaseSteps

​

From here, you can even add in additional workflow. Say you want to capture that this event was performed via API using a dedicated API id/token but was on behalf of a specific person or project.

Grab the itemID from the Created response and use the POST Comment function to insert your comment so the team can see this in the Test Case as well as the Comments Stream.

Admin Activities

Administration activities are available for reporting via the REST API at /activities/adminActivity. These activities have a new structure to better handle the different areas within administration and improve machine readability.

JSON Format

A new JSON format has been introduced to organize the details. Important Note: The details field is serialized and will need to be deserialized when reading the JSON.

Example JSON:

{
"id": 10634515,
"date": "2020-09-08T20:12:10.000+0000",
"user": 22856,
"userName": "Josh Smith",
"action": "Picklist modified",
"eventType": "UPDATE",
"details": "{\"verb\":\"edited\",\"targetType\":\"user\",\"targetObject\":\"Ron Washington\",\"changes\":[{\"field\":\"Last name\",\"initial\":\"Wishington\",\"updated\":\" Wishington \"}],\"children\":[]}"
}

Detail fields:

Target Types:

• item type
• organization
• permission
• pick list
• project
• relationship rule set
• relationship type
• user
• user group
• workflowSub - target types that would only appear in body (within ‘children’ json attribute): item type
• value - as in pick list value
• relationship rule

Verbs:

• added
• edited
• removed
• deleted
• activated
• deactivated
• substituted
• overrode
• indexed

x-jama-date-fields-with-time

On Jama's REST API, we’re using the best practice regarding dates and timezones ( ISO-8601 ).

The only section where this is not true is when serializing dates on the fields array:
Below are the results of a GET request. Notice how the "createdDate" is serialized as ISO-8601. The dates inside the fields array are not. We want to get the full date there, including time and timezone.

				{
				"data": {
				"id": 2973,
				"documentKey": "CL3-BUG-1",
				"globalId": "GID-14616",
				"itemType": 27,
				"project": 25,
				"createdDate": "2015-09-30T10:36:42.000+0000",
				"modifiedDate": "2021-01-08T20:57:44.000+0000",
				"lastActivityDate": "2021-01-08T20:57:44.000+0000",
				"createdBy": 5,
				"modifiedBy": 5,
				"fields": {
				"documentKey": "CL3-BUG-1",
				"globalId": "GID-14616",
				"name": "iOS music sound controls don't work",
				"description": "The sound controls don't work.",
				"priority": 300,
				"user1": 9,
				"assignedTo": 10,
				"dev_url$27": "1",
				"date1": "2021-01-16",
				"customDate$27": "2021-01-29",
				"modifiedDate": "2021-01-08"
				},
				

//the rest of the json response

The Solution

To provide an option for using ISO-8601 in a backward-compatible way, we created the x-jama-date-fields-with-time" header.

When the x-jama-date-fields-with-time" header appears as true, dates in the fields array will be fully serialized as ISO-8601 (including time and timezone).

Try in Swagger

If you desire to use this header in swagger all you need to do is set parameter value = true. If not, feel free to either ignore it and let it go without any value or set the value to false, either way it will bring back the results without the time as shown below.

Without header

With header

Get /relationships performance updates

Prior to the release of Jama Connect 9.2, the use of GET /relationships could cause large performance and system stability issues. Additional parameters to the call provide developers with options to make the call more performant and retrieve more results with each call. Adjustments were made with 9.7 and the following changes are required for anyone using the endpoint.

The GET /relationships API call allows for the following parameters to be associated on the call:

Retrieve Relationship with lastId paging

lastId paging which is described here relies on targeting a known id and retrieving a set number of results starting directly after that id. Standard paging relies on knowing the position in a list and retrieving a set number of results from the position. LastId paging due to its implementation at the database management system level tends to be more performant. Side note: there might be a reason for knowing the totalResults as part of the overall process. If so, then this call could be modified to have omitCount=false to get the totalResults on this initial call and then leave change to omitCount=true for the subsequent calls.

When using lastId paging, the system will take whatever lastId is received and then return the next set of ids from that point based on the maxResults. So, if a caller passes in lastId of 399 and maxResults of 1000, the system will return the next 1000 values starting at whatever id is greater than 399 (the lastId specified). Note that the ids are not necessarily contiguous. Your return set might have ids (based on the preceding example) of 134, 389, 510, 711, 912, 1056, etc. Ids are not contiguous since the caller is scoping to a particular project and relationships may be created over the entire instance, across multiple projects – the id value of the relationships are not tied to the project.

To utilize lastId paging, the caller simply adds the lastId to the call.  A typical call would look like this: https://<baseurl>/rest/v1/relationships?project=314&lastId=159265 or generically https://<baseurl>/rest/v1/relationships?project=<project>&lastId=<itemIdvalue>. Note that if lastId is specified, the startAt value is ignored even if it is included. So if the call was: https://<baseurl>/rest/v1/relationships?project=314&lastId=159265&startAt=10, the startAt value is simply discarded by the system and the call will start at relationship id of 159265 and return the default maxResults of 20.

The best approach is simply to make an initial call without a lastId to find the initial lastId which is best done by https://<baseurl>/v1/relationships?project=314&lastId=1&omitCount=true&maxResults=1

The payload will look something like this:

{ "meta":
{"status": "OK",
 "timestamp": "2023-05-29T12:24:48.962+0000",
 "pageInfo": 
 {"startIndex": 0,
  "resultCount": 1,
  "totalResults": 0}},
 "data": [
  {"id":90901,
     "fromItem":1010,
     "toItem":2109,
     "relationshipType":4,
     "suspect":false,
    "type": "relationships"}]
}

Note that the lastId here is 90901

Now make the next call and retrieve a batch size (e.g. 100 at a time). The lastId is now 91901.

Call looks like this: https://<baseurl>/rest/v1/relationships?project=314&lastId=90901&omitCount=true&maxResults=100

Data Payload return (only the first and last relationships are shown for brevity):

{ "meta": 
 {"status": "OK",
  "timestamp": "2023-05-29T13:24:48.962+0000", 
  "pageInfo": { "startIndex": 0, "resultCount": 100, "totalResults": 0}},
  "data": [
 {"id":90904, "fromItem":1400, “toItem":2605, "relationshipType":4, "suspect":false, "type": "relationships"},
 {...},
 {"id":93904, "fromItem":600, "toItem":665, "relationshipType":4, "suspect":false, "type": "relationships"}
]}

Note that the lastId is now 93904 since it is the id of the last relationship that has been returned to the caller.

Continue making these calls until the resultCount is less that the provided maxResults or the payload has empty data,

The return payload will look something like this:

{"meta":
 {"status": "OK",
  "timestamp": "2023-05-29T13:24:48.962+0000",
  "pageInfo": { "startIndex": 0, "resultCount": 0, "totalResults": 0}},
  "data":[]
}

Note: The caller watches for an empty data payload to stop the process. The decision to omit totalResults may vary based on the specific implementation requirements.

This example demonstrates the flexibility of lastId paging, accommodating various batch sizes and providing options for efficient data retrieval. The user can choose an approach based on their specific needs and system constraints.

Various FAQs

How can I know the lastId value before making an initial call?

You cannot. You must make an initial call to find the lastId to find the starting relationship Id. The caller can make a first call to retrieve the first relationship value for a single item (without startAt values) and then use this as the starting lastId.

How can the initial call be the starting lastId value?  The ids values aren’t deterministic, are they?

The call to GET /relationships is always sorted by the relationship ID values in ascending order, therefore once you know the first value paging through the rest is deterministic.

Is it okay to request more results in a batch than are in a given project?

Yes.  The batch will only ever return as many values as available and the resultCount will be returned the appropriate number.

There doesn’t seem to be any constraint on the lastId value.  Can I send any number here? And is it okay if the relationship id is not in the target project?

Yes.  Only relationship ids that are in the target project will be returned.  If you specify a relationship id that is not in the target project but there are relationship ids in the target project greater than the last Id then some values may be returned.  For example, if project A has relationship ids 5, 20, 30, and 67; and project B has relationship ids 25, 35 and 50.  If you attempted to retrieve relationships from project B but specified a last Id of 30 you would get relationship ids of 35 and 50 from project B but not relationship id 67 since that is in project A.  Note that technically relationships are not targeted to projects but rather the items on either end of the relationship are in the project so there are some odd possibilities here.