Jama

Guide on the Ketryx integration with Jama

New in 2.11

1. Introduction

Ketryx provides seamless integration with Jama, enhancing compliance and streamlining the management of configuration items and releases. This integration is purpose-built to:

• align your Jama workflows with industry standards such as ISO 13485, IEC 62304, and ISO 14971,

• synchronize data between Ketryx and Jama to maintain consistent electronic records,

• provide traceability across requirements and to test cases and test results, and

• enforce workflows that incorporate electronic approvals and audit trails for robust compliance.

This guide offers step-by-step instructions for setting up and utilizing the integration, and answers to frequently asked questions.

2. Setting up the integration

To integrate Ketryx with Jama, please ensure you have the REST API enabled in your Jama instance, and you have administrative permissions on both platforms. If so, proceed with the following steps:

1. Create API credentials

   1. As an organization admin, log into Jama.

   2. Open your user profile page and navigate to Set API Credentials.

   3. Provide a name for the credentials and click Create API Credentials.

   4. Take note of the Client ID and Client Secret, respectively - the secret is shown only once.

2. As Ketryx admin, log in to Ketryx.

3. Navigate to Organization, then Connections and click Add Jama connection.

4. Provide the required credentials (i.e., URL of your instance and OAuth credentials from above) to establish the connection.

5. Confirm the integration in Ketryx by navigating to the Create project page where the Jama section will now have a dropdown listing your Jama projects.

After setting up the connection Ketryx projects can be created and linked with one Jama project each.

3. Frequently Asked Questions

3.1. Q: How does Ketryx synchronize Jama data?

By default, Ketryx synchronizes the following data between the platforms:

• Defect: Any item of a Jama item type used as Defect is imported into Ketryx as Anomaly item.

• Test Cases: Any item of a Jama item type used as Test Case is imported into Ketryx as Test Case item.

• Test Runs: A Jama Test Run is mapped to a Test Execution in Ketryx.

• Test Plans: A Jama Test Plan is mapped to a Test Plan in Ketryx. These items incorporate all the relationships established in Jama (i.e, test cases and runs) and can be manually managed within Ketryx. Alternatively, they can be automatically synchronized if the setting "Automatically update release test plan based on external test plan(s)" is enabled.

Aside from these well-known item types Ketryx also comes with default mappings which can be customized. Such default mappings include, but are not limited to:

• IU (Intended Use): Mapped to Requirement of requirement type Intended use.

• SOFTW (Software Requirement): Mapped to Requirement of requirement type Software system.

• SOFTWI (Software Item): Mapped to Software Item.

• HRM (Harm): Mapped to Risk.

• VAL (Validation): Mapped to Test Case of test type Validation.

To override or add custom item type mappings, use advanced settings for Jama.

3.2. Q: Can I customize how Ketryx maps Jama fields and relationships?

Yes. Ketryx provides advanced settings for Jama that enable you to define how Jama fields map to Ketryx items. For instance, you can configure a Jama release field to map to Ketryx versions.

As with item types, Ketryx comes with default mappings for common Jama fields, such as but not limited to Title, Description and Test Run Status as well as default relationship mappings, e.g., Validation is mapped to Tests in Ketryx.

3.3. Q: How do I handle changes in Jama schema (e.g., custom fields)?

If you add custom fields in Jama, you can configure Ketryx to recognize them using the Jama field type mapping setting.

3.4. Q: What happens to deleted items?

When any item is deleted in Jama it is marked as deleted in Ketryx but remains linked for traceability.

3.5. Q: How do I handle releases?

There are multiple ways to handle releases in Jama, thus there are multiple options how to set up the integration. These non-prioritized options are currently supported:

1. Default release field: Use Jama's built-in default release field and map it to introducedInVersion in Ketryx. Note, that whenever release changes in Jama, it will also change in Ketryx.

2. Custom release fields: Use one, or ideally two, custom release1 and release2 fields and map them to introducedInVersion and obsoleteInVersion, respectively, in Ketryx.

4. Jama Configuration

4.1 Overview

The Jama settings in Ketryx enable users to configure how Jama items map to Ketryx items. This mapping ensures accurate data synchronization between the two systems, maintaining traceability and compliance. These configurations are crucial for integrating requirements, defects, tests, releases etc. into Ketryx workflows seamlessly.

The configuration includes the following:

1. Jama item mapping: Matches Jama item types to Ketryx item types including default types such as Test Plan but also your own custom types.

2. Jama item status mapping: Aligns Jama statuses with Ketryx item states.

3. Jama item relationships mapping: Maps Jama fields to create relational links in Ketryx with items in external systems.

4. Jama field type mapping: Matches Jama fields to Ketryx attributes.

As organization admin, you can find your Jama item types, their fields and your relationship types in the Jama ADMIN center.

Furthermore, general advanced settings can be relevant, too, such as Approval workflows to enable approvals, optionally with status transitions. These are done in Ketryx and a sync back to Jama.

Refer to Advanced settings for a complete list of available settings.

4.2 Jama item mapping

The Jama item mapping defines how Jama item types are translated into Ketryx item types, e.g., a type Use Case in Jama would become a Requirement of requirement type Use case.

Example Configuration

[
   {
      "jamaItemType": "SOFTW",
      "itemType": "REQUIREMENT",
      "fieldValues": { "requirementType": { "value": "Software system" } }
   },
   { "jamaItemType": "CR", "itemType": "CHANGE_REQUEST" }
]

• jamaItemType: The item type in Jama (use the Key or Display name).

• itemType: The item type in Ketryx.

• fieldValues: Bind static values based on the Jama item type, e.g., specifying a requirementType or testType.

Refer to Item types and Fields for a complete list of built-in types and fields available in Ketryx.

4.3 Jama item status mapping

The Jama item status mapping aligns Jama status names with Ketryx item states such as OPEN, REOPENED, IN_PROGRESS, RESOLVED, or CLOSED.

Example Configuration

{
  "Backlog": "OPEN",
  "Done": "RESOLVED"
}

• Backlog in Jama maps to Open in Ketryx.

• Done in Jama maps to Resolved in Ketryx.

Refer to Status mapping for a complete list of Ketryx statuses.

4.5 Jama item relationships mapping

The Jama item relationships mapping maps relationships from Jama to Ketryx relationship types.

Note, that the hierarchical item structure in Jama is always mapped to has parent relationships. Additionally, for more flexibility, a relationship type for parent-relations can be used in Jama and mapped to Ketryx.

Example Configuration

{ 
   "Related to": "RELATES_TO"
}

• Related to relations in Jama map to Relates to in Ketryx.

The following relations are mapped by default:

• Related to: Relates to

• DI - DO: Fulfills

• Validation and Verification: Tests

• Change Request: Affects

Refer to relationType for a complete list of Ketryx relation types.

4.2 Jama field type mapping

The Jama field type mapping defines how Jama fields (e.g., custom fields) are translated into Ketryx attributes. This is done globally across all item types.

To provide static values based on an item type, refer to Jama item mapping.

Example Configuration

{
   "release1": "introducedInVersion",
   "release2": "obsoleteInVersion",
   "deferFix": "rationaleForDeferringResolution"
}

• release1/release2: Maps Jama release fields to a corresponding Ketryx version.

• deferFix: Maps a (rich) text field named deferFix to rationaleForDeferringResolution.

The following standard Jama fields are always mapped to corresponding Ketryx fields:

• Name

• Description

• Test Case Steps

• Test Run Steps

• Test Run Status

The following field mappings are included by default but can be overridden:

• Status

• Assigned to

Refer to Fields for a complete list of built-in fields available in Ketryx.

---

For more detailed instructions and advanced configuration options, please refer to the Ketryx Advanced Settings section of the documentation.