Ketryx Documentation
Book a DemoFAQTraining Videos
  • Introduction
  • 📄Manuals
    • MAN-01 Ketryx Lifecycle Management
    • MAN-02 Software Release Process
    • MAN-03 Supply Chain Management: Software Dependencies
      • Threat Modeling
      • Vulnerability Management
      • Working with CycloneDX
      • Working with SPDX
    • MAN-04 Supply Chain Management: Cloud Dependencies
    • MAN-05 Milestones
    • MAN-06 Test Management
    • MAN-07 Traceability
    • MAN-08 Risk Management
    • MAN-09 Git-Based Configuration Items
    • MAN-10 Managing items in Ketryx
    • MAN-11 Approval Rules
    • MAN-12 Computational Controls
    • MAN-13 Data Export
  • 🛠️Work Instructions
    • WI-01 Requirement
    • WI-02 Software Item Specification
    • WI-03 Task
    • WI-04 Test Case
    • WI-05 Test Execution
    • WI-06 Anomaly
    • WI-07 Complaint
    • WI-08 Change Request
    • WI-09 Corrective and Preventive Action (CAPA)
    • WI-10 Risk
    • WI-11 Document
  • 🌐Integrations
    • Jira
    • Azure DevOps
    • TestRail
    • Jama
    • Polarion
    • Chrome extension
    • Source Code
      • Azure DevOps
      • Bitbucket
      • GitHub
      • GitLab
      • Code Change Reviews
    • Release documents
      • Google Workspace
    • Authentication
  • 📚Reference
    • Ketryx Query Language
    • Advanced Settings
    • Glob Pattern Matching Algorithm
    • Traceability Configuration
    • Document Templating
    • Project Settings
    • Custom Item Types
    • Assistant
    • Agents
    • Release Notes
  • 🔃API
    • Authentication
    • Build API
    • Project API
    • Item API
    • Webhooks
Powered by GitBook

Ketryx

  • ketryx.com
  • What is Ketryx?

Resources

  • FAQ
  • Training Videos

© 2025 Ketryx Corporation

On this page
  • 1. Introduction
  • 2. Setting up the integration
  • 2.1. Traceability widget
  • 3. Frequently Asked Questions
  • 3.1. Q: How does Ketryx synchronize Polarion data?
  • 3.2. Q: Can I customize how Ketryx maps Polarion fields and work item links?
  • 3.3. Q: How do I handle changes in Polarion schema (e.g., custom fields)?
  • 3.4. Q: What happens to deleted items?
  • 3.5. Q: How do I handle releases?
  • 4. Polarion Configuration
  • 4.1. Overview
  • 4.2. Polarion work item type mapping
  • 4.3. Polarion status mapping
  • 4.4. Polarion work item links mapping
  • 4.5. Polarion test result mapping
  • 4.6. Polarion field mapping

Was this helpful?

Export as PDF
  1. Integrations

Polarion

Guide on the Ketryx integration with Polarion

New in 2.11

1. Introduction

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

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

  • synchronize data between Ketryx and Polarion 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 Polarion, please ensure you are running at least version 2404 of Polarion and have the REST API enabled.

  • Note: the initial connection should be made from a service account (e.g. ketryx@yourcompany.com), which should have Polarion administrator privileges. It should NOT be someone's personal account, even if that person is an administrator.

  • Rationale: Whoever sets up the initial connection to Ketryx via the API will be credited with making the changes that Ketryx makes in Polarion. The biggest problem this creates is the danger that once the original person who sets up Ketryx leaves the company, typically, that person's IT credentials are revoked. In turn, this would revoke Ketryx's access to Polarion and cause the Ketryx/Polarion integration to stop working. (No data would be lost, but this is very annoying and potentially difficult to troubleshoot.)

  1. Create a personal access token (PAT) for a user in Polarion.

    1. Log in as that user and navigate to My Account, or as a user with Manage Users permission navigate to Global->Administration->User Management->Users and select the user.

    2. Click Personal Access Token.

    3. Enter a name and an expiration date.

    4. Click Create Token and take note of the generated PAT.

  2. As Ketryx admin, log in to Ketryx.

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

  4. Provide the URL of your Polarion instance and the generated PAT to establish the connection.

  5. Confirm the integration in Ketryx by navigating to the Create project page where the Polarion section will allow you to link a Polarion project.

    If the user associated with the PAT has GET permissions in the Global context, a dropdown with a list of available projects will be shown. Otherwise, a text field will allow you to enter a project ID manually (go to Administration in a Polarion project to see the project ID).

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

2.1. Traceability widget

To install the plugin:

  1. Download the plugin JAR file from the Ketryx admin portal under Organization -> Connections -> Polarion -> Download plugin.

  2. Copy the JAR file to the YOUR-POLARION-INSTALL-DIR/polarion/plugins directory on your Polarion server.

  3. Restart the Polarion server to load the plugin.

Before configuring the traceability widget, you will need to create an API key:

  1. In Ketryx, navigate to Organization -> Connections -> Polarion.

  2. Click Create API key.

  3. When prompted, authenticate with multi-factor authentication.

  4. Click Create API key in the dialog.

  5. Copy the generated key.

Then, add the traceability widget in Polarion:

  1. Navigate to Administration -> Global Administration -> Work Items -> Form Configuration (or Administration -> Work Items -> Form Configuration for project-specific configuration).

  2. In the "Form Layouts" section, click "Edit" for one of the work item types where you want to add the widget.

  3. Add the following XML to the form layout configuration:

    <extension apiKey="YOUR-API-KEY" content="relations" id="ketryx" url="https://app.ketryx.com" />

    Replace YOUR-API-KEY with the API key generated earlier.

  4. Save the form layout configuration.

  5. Repeat steps 2-4 for each work item type where you want the traceability widget to appear.

The traceability widget will now appear in work item forms, showing relations to other work items, test runs and items from other systems connected to Ketryx.

3. Frequently Asked Questions

3.1. Q: How does Ketryx synchronize Polarion data?

By default, Ketryx synchronizes the following work items between the platforms:

Polarion work item type IDs
Ketryx item type

acceptanceCriteria, epic, feature, hardwareRequirement, productRequirement, requirement, softwareRequirement, softwarerequirement, systemrequirement, useCase, userNeeds, userstory

Requirement

task

Task

codereviewTestCase, softwareTestCase, softwaretestcase, systemtestcase, testCase, testcase, unitTestCase, unittestcase

Test Case

anomaly, bug, defect, issue

Anomaly

changerequest

Change Request

risk

Risk

designElement, designOutput, softwareDesign, softwareInterface, softwareModule, softwareUnit

Software Item Spec

Work item links are synchronized as relations between items in Ketryx. By default, the following work item link types are created:

Polarion work item link IDs
Ketryx relation type

relates_to, follow_up

Is Related To

parent, refines, contain

Has Parent

implements

Implements

verifies

Tests

Ketryx also synchronizes test runs as Test Execution items and creates relations to the corresponding Test Case items.

3.2. Q: Can I customize how Ketryx maps Polarion fields and work item links?

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

3.4. Q: What happens to deleted items?

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

3.5. Q: How do I handle releases?

The Ketryx plugin for Polarion is required to manage releases from Polarion in Ketryx. Ketryx currently synchronizes versions only from Polarion collections. A future release will allow for version management without the plugin (Polarion 2410 and newer) and support Polarion plans (Polarion 2404 and newer).

Work items of a document included in a collection will be part of the corresponding version in Ketryx.

4. Polarion Configuration

4.1. Overview

The Polarion settings in Ketryx enable users to configure how Polarion work items and test runs map to Ketryx items. This mapping ensures accurate data synchronization between the two systems, maintaining traceability and compliance. These configurations are crucial for integrating work items and test runs into Ketryx workflows seamlessly.

The configuration includes the following mappings:

  • Polarion work item type to Ketryx item type

  • Polarion status to Ketryx item state

  • Polarion work item link type to Ketryx relation type

  • Polarion test result to Ketryx test result

  • Polarion field to Ketryx item field

You can find IDs of work item types, work item links, statuses, fields and test results in the Administration section of a Polarion project. The relevant subsections are Work Items->Types, Work Items->Custom Fields, Work Items->Enumerations, Testing->Test Run Custom Fields and Testing->Test Results.

4.2. Polarion work item type mapping

Mapping between Polarion work item types and Ketryx items. Note that matching is case-sensitive.

Example

Map additional Polarion work item types:

[
  {
    "workItemType": "Custom Bug",
    "itemType": "ANOMALY"
  },
  {
    "workItemType": "Custom Requirement",
    "itemType": "REQUIREMENT"
  }
]

Example

Overwrite a default mapping using type ID or type name:

[
  {
    "workItemType": "issue",
    "itemType": "TASK"
  },
  {
    "workItemType": "Issue",
    "itemType": "TASK"
  }
]

4.3. Polarion status mapping

Mapping from Polarion status IDs to Ketryx states. This maps statuses for both, work items and test runs.

Example

Map a Polarion status with ID "draft" to the state "OPEN":

{
  "draft": "OPEN"
}

4.4. Polarion work item links mapping

Mapping from Polarion work item link IDs to Ketryx relations.

Example

Map Polarion work item link with ID "verifies" to system relation "TESTS":

{
  "verifies": "TESTS"
}

4.5. Polarion test result mapping

Mapping from Polarion test result IDs to Ketryx results.

Example

Map test result IDs:

{
  "passed": "PASS",
  "failed": "FAIL",
  "warnings": "PASS_WITH_EXCEPTION"
}

4.6. Polarion field mapping

Mapping from Polarion-specific fields to Ketryx fields or relations.

A field that is mapped to a relation can reference items by their source key. The field in Polarion can be of type "String" (single-line plain text), "Text" (multi-line plain text) or "Enum". For fields of type "String" or "Text" multiple keys can be specified by separating them with whitespace (spaces, line breaks, etc.), commas or semicolons.

Example

Map a Polarion field with ID "customField" to the field "Custom Field":

{
  "customField": "Custom Field"
}

Example

Map a Polarion field with ID "affectsJiraItems" to relations of type "AFFECTS" targeting items from Jira:

{
  "affectsJiraItems": {
    "type": "references",
    "targetSystem": "Jira",
    "relationType": "AFFECTS"
  }
}

PreviousJamaNextChrome extension

Last updated 22 days ago

Was this helpful?

Ketryx provides a Polarion plugin that allows you to add the to the Polarion work item form.

Aside from these pre-defined item types Ketryx allows you to override or add custom work item type mappings, see .

Yes. Ketryx provides that enable you to define how Polarion fields map to Ketryx items. Both built-in and custom fields can be mapped to Ketryx fields.

If you add custom fields in Polarion, you can configure Ketryx to recognize them using the setting. Additional work item links can be configured using .

You can use collections to manage releases in Polarion and synchronize them with Ketryx. Ketryx will synchronize collections as versions if they are named according to the (e.g. if your project contains a collection named "System Spec 3.1.0", Ketryx will synchronize it as version "3.1.0"). If a version with the same version number already exists in Ketryx, the Polarion version will be associated with it. In order to have Polarion determine version properties, such as the name, set accordingly.

To associate test runs with a particular version, create a custom field in Polarion. Configure the field in the setting, using the type name "Test Run" and the ID of the custom field. Edit a test run to enter a version number in the custom field (e.g. enter "3.1.0" and Ketryx will synchronize the test run as a Test Execution for version "3.1.0").

General advanced settings can be relevant, too, such as Approval workflow to enable approvals. See for a complete list of available settings.

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

Refer to for a complete list of Ketryx statuses.

Refer to for a complete list of Ketryx relation types.

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

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

🌐
Advanced settings
Ketryx Advanced Settings
Polarion configuration
advanced settings for Polarion
Polarion field mapping
Polarion work item links mapping
traceability widget
Version number pattern
Integration precedence
Version fields
Item types
Fields
Status mapping
Relations
Fields