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.)
Create a personal access token (PAT) for a user in Polarion.
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.
Click Personal Access Token.
Enter a name and an expiration date.
Click Create Token and take note of the generated PAT.
As Ketryx admin, log in to Ketryx.
Navigate to Organization, then Connections and click Add Polarion connection.
Provide the URL of your Polarion instance and the generated PAT to establish the connection.
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.
3. Frequently Asked Questions
3.1. Q: How does Ketryx synchronize Polarion data?
By default, Ketryx synchronizes the following work items between the platforms:
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
Aside from these pre-defined item types Ketryx allows you to override or add custom work item type mappings, see Polarion configuration.
Work item links are synchronized as relations between items in Ketryx. By default, the following work item link types are created:
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?
Yes. Ketryx provides advanced settings for Polarion that enable you to define how Polarion fields map to Ketryx items. Both built-in and custom fields can be mapped to Ketryx fields.
3.3. Q: How do I handle changes in Polarion schema (e.g., custom fields)?
If you add custom fields in Polarion, you can configure Ketryx to recognize them using the Polarion field mapping setting. Additional work item links can be configured using Polarion work item links mapping.
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).
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 Version number pattern (e.g. if your project contains a collection named "System Spec 3.1.0", Ketryx will synchronize it as version "3.1.0").
Work items of a document included in a collection will be part of the corresponding version in Ketryx.
To associate test runs with a particular version, create a custom field in Polarion. Configure the field in the Version fields 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").
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.
General advanced settings can be relevant, too, such as Approval workflow to enable approvals. See Advanced settings for a complete list of available settings.
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:
Example
Overwrite a default mapping using type ID or type name:
Refer to Item types and Fields for a complete list of built-in types and fields available in Ketryx.
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":
Refer to Status mapping for a complete list of Ketryx statuses.
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":
Refer to Relations for a complete list of Ketryx relation types.
4.5. Polarion test result mapping
Mapping from Polarion test result IDs to Ketryx results.
Example
Map test result IDs:
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":
Example
Map a Polarion field with ID "affectsJiraItems" to relations of type "AFFECTS" targeting items from Jira:
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.
Last updated
Was this helpful?