# Jama Connect (/integrations/jama)

[Jama Connect](https://www.jamasoftware.com/) manages requirements, their relationships, and verification records. Use the Jama Connect block to search and edit items, inspect relationships and comments, compare versions and baselines, and work with test execution results.

## Connect your account \[#connect-your-account]

In Jama Connect, open your profile and select **Set API credentials**. Create a client ID and secret, then save them with your Jama instance URL in the block's **Jama Account** field. Use the instance's base URL, such as `https://example.jamacloud.com`, including a context path if your self-hosted instance uses one.

Jama uses the OAuth client credentials grant for these personal API credentials. Sim obtains short-lived access tokens when needed. The credentials retain their owner's Jama permissions; they do not grant administrator access. Jama requires a **Named Creator** license and REST API access. This authentication method supports Jama Cloud and self-hosted Jama Connect 8.62 or later, including instances that use SSO. See [Jama's API authentication guide](https://dev.jamasoftware.com/api/#advanced-authentication).

## Work with requirements and tests \[#work-with-requirements-and-tests]

- **Custom fields:** Use **Get Item Type** to read the internal field names, types, and required fields before creating or updating an item. Use **List Pick List Options** for valid option IDs. Field names and status values vary by instance.
- **Create items:** Select a project and item type, then supply **Fields** as a JSON object. **Parent Item ID** places the new item inside an existing container. Sets and folders also require **Child Item Type ID**.
- **Update items:** Supply a JSON Patch array, for example `[{"op":"replace","path":"/fields/name","value":"Updated requirement"}]`. Only the listed paths change. The supported operations are `add`, `remove`, and `replace`.
- **Search:** **Search Items** uses Jama's abstract item search, which can return requirements, test plans, test cycles, test runs, and attachments. Results include their item type and current fields. File downloads are not included.
- **Filters:** For a saved filter with `projectScope` set to `CURRENT`, provide **Project** when listing its results.
- **Test execution:** Read the test run and its item type before updating execution fields. Use Jama's configured field names and status values, and supply ISO 8601 timestamps for execution dates.
- **Pagination:** List and search operations return one page, with a default of 20 and a maximum of 50 results. Set the next **Start Offset** to `pageInfo.startIndex + pageInfo.resultCount` and stop when it reaches `pageInfo.totalResults`, or when the page is empty.

Requests use the supported `/rest/v1` API. Read requests and idempotent updates retry bounded transient failures; creates and JSON Patch updates are not automatically replayed. Jama Cloud and self-hosted instances can apply their own API throttling. See [Jama's API cookbook](https://dev.jamasoftware.com/cookbook/).

## Use the block \[#usage-instructions]

Search and manage requirements, inspect custom item types and pick lists, trace upstream and downstream relationships, collaborate with comments, compare item versions and baselines, and read test plans, cycles, and runs or update execution results. Connect with saved Jama API client credentials that retain the account owner’s permissions.

## Actions \[#actions]

### Jama List Projects \[#jama-list-projects]

List Projects in Jama Connect using the connected user's access permissions.

#### Input \[#input]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |

#### Output \[#output]

| Parameter | Type | Description |
| - | - | - |
| `projects` | array | List Projects result |

### Jama Get Project \[#jama-get-project]

Get Project in Jama Connect using the connected user's access permissions.

#### Input \[#input-1]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | project ID |

#### Output \[#output-1]

| Parameter | Type | Description |
| - | - | - |
| `project` | object | Get Project result |

### Jama List Item Types \[#jama-list-item-types]

List Item Types in Jama Connect using the connected user's access permissions.

#### Input \[#input-2]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | No | Only item types enabled in this project |

#### Output \[#output-2]

| Parameter | Type | Description |
| - | - | - |
| `itemTypes` | array | List Item Types result |

### Jama Get Item Type \[#jama-get-item-type]

Get Item Type in Jama Connect using the connected user's access permissions.

#### Input \[#input-3]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemTypeId` | string | Yes | itemType ID |

#### Output \[#output-3]

| Parameter | Type | Description |
| - | - | - |
| `itemType` | object | Get Item Type result |

### Jama List Items \[#jama-list-items]

List Items in Jama Connect using the connected user's access permissions.

#### Input \[#input-4]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |
| `rootOnly` | boolean | No | Only root-level items in the project |

#### Output \[#output-4]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Items result |

### Jama Search Items \[#jama-search-items]

Search Items in Jama Connect using the connected user's access permissions.

#### Input \[#input-5]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `query` | string | Yes | Text to find in item names, descriptions, and fields |
| `projectId` | string | No | Restrict search to a project |
| `itemTypeId` | string | No | Restrict search to an item type |
| `documentKey` | string | No | Exact document key |
| `modifiedSince` | string | No | Only items modified since this ISO 8601 date |
| `sortBy` | string | No | Sort field and direction, for example modifiedDate.desc |

#### Output \[#output-5]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | Search Items result |

### Jama Get Item \[#jama-get-item]

Get Item in Jama Connect using the connected user's access permissions.

#### Input \[#input-6]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemId` | string | Yes | item ID |

#### Output \[#output-6]

| Parameter | Type | Description |
| - | - | - |
| `item` | object | Get Item result |

### Jama Create Item \[#jama-create-item]

Create Item in Jama Connect using the connected user's access permissions.

#### Input \[#input-7]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | project ID |
| `itemTypeId` | string | Yes | itemType ID |
| `fields` | json | Yes | Jama field names and values, including name and required custom fields |
| `parentItemId` | string | No | Parent item ID; otherwise create at the project root |
| `childItemTypeId` | string | No | Child item type ID, required for sets and folders |

#### Output \[#output-7]

| Parameter | Type | Description |
| - | - | - |
| `id` | number | Created resource ID |
| `location` | string | API URL of the created resource |

### Jama Update Item \[#jama-update-item]

Update Item in Jama Connect using the connected user's access permissions.

#### Input \[#input-8]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemId` | string | Yes | item ID |
| `patch` | json | Yes | JSON Patch array using add, remove, or replace, for example \[{"op":"replace","path":"/fields/name","value":"Updated name"}] |

#### Output \[#output-8]

| Parameter | Type | Description |
| - | - | - |
| `status` | number | Successful HTTP status code |

### Jama Delete Item \[#jama-delete-item]

Delete Item in Jama Connect using the connected user's access permissions.

#### Input \[#input-9]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemId` | string | Yes | item ID |

#### Output \[#output-9]

| Parameter | Type | Description |
| - | - | - |
| `status` | number | Successful HTTP status code |

### Jama List Item Children \[#jama-list-item-children]

List Item Children in Jama Connect using the connected user's access permissions.

#### Input \[#input-10]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `itemId` | string | Yes | item ID |

#### Output \[#output-10]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Item Children result |

### Jama List Upstream Items \[#jama-list-upstream-items]

List Upstream Items in Jama Connect using the connected user's access permissions.

#### Input \[#input-11]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `itemId` | string | Yes | item ID |

#### Output \[#output-11]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Upstream Items result |

### Jama List Downstream Items \[#jama-list-downstream-items]

List Downstream Items in Jama Connect using the connected user's access permissions.

#### Input \[#input-12]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `itemId` | string | Yes | item ID |

#### Output \[#output-12]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Downstream Items result |

### Jama List Relationships \[#jama-list-relationships]

List Relationships in Jama Connect using the connected user's access permissions.

#### Input \[#input-13]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |

#### Output \[#output-13]

| Parameter | Type | Description |
| - | - | - |
| `relationships` | array | List Relationships result |

### Jama Get Relationship \[#jama-get-relationship]

Get Relationship in Jama Connect using the connected user's access permissions.

#### Input \[#input-14]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `relationshipId` | string | Yes | relationship ID |

#### Output \[#output-14]

| Parameter | Type | Description |
| - | - | - |
| `relationship` | object | Get Relationship result |

### Jama Create Relationship \[#jama-create-relationship]

Create Relationship in Jama Connect using the connected user's access permissions.

#### Input \[#input-15]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fromItemId` | string | Yes | fromItem ID |
| `toItemId` | string | Yes | toItem ID |
| `relationshipTypeId` | string | No | Relationship type ID; defaults to the instance default |

#### Output \[#output-15]

| Parameter | Type | Description |
| - | - | - |
| `id` | number | Created resource ID |
| `location` | string | API URL of the created resource |

### Jama Delete Relationship \[#jama-delete-relationship]

Delete Relationship in Jama Connect using the connected user's access permissions.

#### Input \[#input-16]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `relationshipId` | string | Yes | relationship ID |

#### Output \[#output-16]

| Parameter | Type | Description |
| - | - | - |
| `status` | number | Successful HTTP status code |

### Jama List Relationship Types \[#jama-list-relationship-types]

List Relationship Types in Jama Connect using the connected user's access permissions.

#### Input \[#input-17]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |

#### Output \[#output-17]

| Parameter | Type | Description |
| - | - | - |
| `relationshipTypes` | array | List Relationship Types result |

### Jama List Item Comments \[#jama-list-item-comments]

List Item Comments in Jama Connect using the connected user's access permissions.

#### Input \[#input-18]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `itemId` | string | Yes | item ID |

#### Output \[#output-18]

| Parameter | Type | Description |
| - | - | - |
| `comments` | array | List Item Comments result |

### Jama Create Comment \[#jama-create-comment]

Create Comment in Jama Connect using the connected user's access permissions.

#### Input \[#input-19]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemId` | string | Yes | item ID |
| `text` | string | Yes | Comment text |
| `inReplyTo` | string | No | Parent comment ID when replying |

#### Output \[#output-19]

| Parameter | Type | Description |
| - | - | - |
| `id` | number | Created resource ID |
| `location` | string | API URL of the created resource |

### Jama List Item Versions \[#jama-list-item-versions]

List Item Versions in Jama Connect using the connected user's access permissions.

#### Input \[#input-20]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `itemId` | string | Yes | item ID |

#### Output \[#output-20]

| Parameter | Type | Description |
| - | - | - |
| `versions` | array | List Item Versions result |

### Jama Get Item Version \[#jama-get-item-version]

Get Item Version in Jama Connect using the connected user's access permissions.

#### Input \[#input-21]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `itemId` | string | Yes | item ID |
| `versionNumber` | string | Yes | Version number returned by List Item Versions |

#### Output \[#output-21]

| Parameter | Type | Description |
| - | - | - |
| `item` | object | Get Item Version result |

### Jama List Filters \[#jama-list-filters]

List Filters in Jama Connect using the connected user's access permissions.

#### Input \[#input-22]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | No | Only filters for this project |

#### Output \[#output-22]

| Parameter | Type | Description |
| - | - | - |
| `filters` | array | List Filters result |

### Jama Get Filter \[#jama-get-filter]

Get Filter in Jama Connect using the connected user's access permissions.

#### Input \[#input-23]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `filterId` | string | Yes | filter ID |

#### Output \[#output-23]

| Parameter | Type | Description |
| - | - | - |
| `filter` | object | Get Filter result |

### Jama List Filter Results \[#jama-list-filter-results]

List Filter Results in Jama Connect using the connected user's access permissions.

#### Input \[#input-24]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `filterId` | string | Yes | filter ID |
| `projectId` | string | No | Project ID required for a filter whose projectScope is CURRENT |

#### Output \[#output-24]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Filter Results result |

### Jama List Baselines \[#jama-list-baselines]

List Baselines in Jama Connect using the connected user's access permissions.

#### Input \[#input-25]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |

#### Output \[#output-25]

| Parameter | Type | Description |
| - | - | - |
| `baselines` | array | List Baselines result |

### Jama Get Baseline \[#jama-get-baseline]

Get Baseline in Jama Connect using the connected user's access permissions.

#### Input \[#input-26]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `baselineId` | string | Yes | baseline ID |

#### Output \[#output-26]

| Parameter | Type | Description |
| - | - | - |
| `baseline` | object | Get Baseline result |

### Jama List Baseline Items \[#jama-list-baseline-items]

List Baseline Items in Jama Connect using the connected user's access permissions.

#### Input \[#input-27]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `baselineId` | string | Yes | baseline ID |

#### Output \[#output-27]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | List Baseline Items result |

### Jama List Test Plans \[#jama-list-test-plans]

List Test Plans in Jama Connect using the connected user's access permissions.

#### Input \[#input-28]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |

#### Output \[#output-28]

| Parameter | Type | Description |
| - | - | - |
| `testPlans` | array | List Test Plans result |

### Jama Get Test Plan \[#jama-get-test-plan]

Get Test Plan in Jama Connect using the connected user's access permissions.

#### Input \[#input-29]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `testPlanId` | string | Yes | testPlan ID |

#### Output \[#output-29]

| Parameter | Type | Description |
| - | - | - |
| `testPlan` | object | Get Test Plan result |

### Jama List Test Cycles \[#jama-list-test-cycles]

List Test Cycles in Jama Connect using the connected user's access permissions.

#### Input \[#input-30]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `testPlanId` | string | Yes | testPlan ID |

#### Output \[#output-30]

| Parameter | Type | Description |
| - | - | - |
| `testCycles` | array | List Test Cycles result |

### Jama Get Test Cycle \[#jama-get-test-cycle]

Get Test Cycle in Jama Connect using the connected user's access permissions.

#### Input \[#input-31]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `testCycleId` | string | Yes | testCycle ID |

#### Output \[#output-31]

| Parameter | Type | Description |
| - | - | - |
| `testCycle` | object | Get Test Cycle result |

### Jama List Test Runs \[#jama-list-test-runs]

List Test Runs in Jama Connect using the connected user's access permissions.

#### Input \[#input-32]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `testCycleId` | string | Yes | testCycle ID |

#### Output \[#output-32]

| Parameter | Type | Description |
| - | - | - |
| `testRuns` | array | List Test Runs result |

### Jama Get Test Run \[#jama-get-test-run]

Get Test Run in Jama Connect using the connected user's access permissions.

#### Input \[#input-33]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `testRunId` | string | Yes | testRun ID |

#### Output \[#output-33]

| Parameter | Type | Description |
| - | - | - |
| `testRun` | object | Get Test Run result |

### Jama Update Test Run \[#jama-update-test-run]

Update Test Run in Jama Connect using the connected user's access permissions.

#### Input \[#input-34]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `testRunId` | string | Yes | testRun ID |
| `fields` | json | Yes | Complete execution fields to update, including testRunStatus, testRunSteps, or executionDate as supported by the item type |

#### Output \[#output-34]

| Parameter | Type | Description |
| - | - | - |
| `status` | number | Successful HTTP status code |

### Jama List Releases \[#jama-list-releases]

List Releases in Jama Connect using the connected user's access permissions.

#### Input \[#input-35]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |

#### Output \[#output-35]

| Parameter | Type | Description |
| - | - | - |
| `releases` | array | List Releases result |

### Jama List Tags \[#jama-list-tags]

List Tags in Jama Connect using the connected user's access permissions.

#### Input \[#input-36]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `projectId` | string | Yes | project ID |

#### Output \[#output-36]

| Parameter | Type | Description |
| - | - | - |
| `tags` | array | List Tags result |

### Jama List Pick Lists \[#jama-list-pick-lists]

List Pick Lists in Jama Connect using the connected user's access permissions.

#### Input \[#input-37]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |

#### Output \[#output-37]

| Parameter | Type | Description |
| - | - | - |
| `pickLists` | array | List Pick Lists result |

### Jama List Pick List Options \[#jama-list-pick-list-options]

List Pick List Options in Jama Connect using the connected user's access permissions.

#### Input \[#input-38]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `startAt` | number | No | Zero-based result offset (default 0) |
| `maxResults` | number | No | Results per page, from 1 to 50 (default 20) |
| `pickListId` | string | Yes | pickList ID |

#### Output \[#output-38]

| Parameter | Type | Description |
| - | - | - |
| `options` | array | List Pick List Options result |

### Jama Get Current User \[#jama-get-current-user]

Get Current User in Jama Connect using the connected user's access permissions.

#### Input \[#input-39]

| Parameter | Type | Required | Description |
| - | - | - | - |

#### Output \[#output-39]

| Parameter | Type | Description |
| - | - | - |
| `user` | object | Get Current User result |