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. [email protected]), 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

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

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

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:

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?

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. In order to do so, configure the Polarion collection mapping to synchronize all or some collections, or to exclude specific ones. 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 Integration precedence accordingly.

Work items of a document included in a collection will be part of the corresponding version in Ketryx, at the revision of the document. If a work item appears at multiple revisions, the highest one will be included in the Ketryx version.

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:

[
  {
    "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"
  }
]

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":

{
  "draft": "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":

{
  "verifies": "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:

{
  "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"
  }
}

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

4.7. Polarion collection mapping

Mapping between Polarion collections and Ketryx versions.

The first matching entry will be used. Use "collectionName" to require an exact match with the collection name. If "versionName" is specified, the work items associated with that collection will be considered part of a version with that name. Otherwise, the version name is inferred from the collection name via the Version number pattern (e.g. if a collection is called "System Spec 3.1.0", Ketryx will synchronize it as version "3.1.0"). More than one collection can be synchronized as the same version by specifying the same "versionName" in multiple entries.

If a collection matches no entry, or an entry {"excluded": true}, it is ignored. By default, if this setting is not specified, or an empty array is supplied, no collection is synchronized.

Example

Synchronize all collections as versions

[
  { "excluded": false }
]

Example

Synchronize some collections, ignore the rest

[
  { "collectionName": "Use cases 1.0" },
  { "collectionName": "Test Plan 1.0" },
  { "collectionName": "Use cases 1.1" },
  { "collectionName": "Test Plan 1.1" }
]

Example

Synchronize some collections as specific versions, ignore the rest

[
  { collectionName: 'My collection A', versionName: 'Release 1.3' },
  { collectionName: 'My collection B', versionName: 'Release 1.3' },
  { collectionName: 'My collection C', versionName: 'Release 2.0' },
]

Example

Ignore specific collections, synchronize the rest

[
  { "collectionName": "My collection 2.0.0", "excluded": true },
  { "collectionName": "My collection 3.0.0", "excluded": true },
  { "excluded": false }
]

---

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