Polarion

The Polarion adapter allows to extract table items from a Polarion database server and to open Polarion artifacts from YT.

Instead of connecting to the Polarion application server, YAKINDU Traceability connects directly to the Polarion database. To make this possible, you have to allow external access to the database. Polarion provides a description of how to do so: https://almdemo.polarion.com/polarion/sdk/doc/database/ExternalDatabaseConnection.pdf. You can use any SQL client to check whether you can successfully connect to the database.

Configuring web access to Polarion

Double-clicking on a Polarion artifact in YT will display this artifact in a web browser. This also works the other way round: If you select another artifact in the browser, YT will select it as well.

In order to make this work, you have to configure a so-called web driver in YT. YT will need it to do two things:

  • Launching a browser
  • Responding to UI changes in YT, such as selecting an artifact

Please note that the web driver must match your web browser and your operating system. You can find the web driver executables for several web browsers in the following table. Follow the instructions (if available) on the particular website and make sure to download the web driver that matches your web browser and its version as well as your operating system.

Browser Website
Firefox https://github.com/mozilla/geckodriver/releases
Chrome http://chromedriver.chromium.org/downloads
Edge https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/

Unpack the downloaded archive file to an arbitrary directory on your computer.

Configure the web browser and the associated web driver in the YT preferences:

  • Go to Window → Preferences → YAKINDU Traceability → Adapters
  • In the "Choose a browser to open Polarion" preference, select the browser you want to use, e.g., Firefox or Chrome.
  • In the "Webdriver Location" preference, select the web driver executable.

A correct configuration might look like this:

If you do not configure a web browser and a web driver as described, YT will use the internal Eclipse browser. However, that browser is rather limited. While it supports selection propagation from YT to the browser, it does not support the opposite direction. That is, you can select an item in YT and have it displayed in the browser, but if you select anything in the web browser, YT will not get notified.

You will also have to set a webURLPrefix in the Polarion data access configuration.

Data access

The Polarion data access configuration specifies the Polarion database server to connect to.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Polarion as data access type.

Supported keywords:

  • server – The Polarion server’s IP address and port number
  • user – The user name for logging into the Polarion server
  • password – The password for logging into the Polarion server
  • webURLPrefix – The URL prefix for accessing Polarion work items via a web browser, e.g., http://mypolarion.example.com. The URL prefix must point to the web server that is integrated into the Polarion server.
  • undefined attribute value – The value to return when reading a nonexistent parameter of an element. Default is the empty string: "".

Sample configuration:

server "192.168.3.160:5433" user "external" password "secret007"
undefined attribute value = "<undefined>"

The example above will connect to the Polarion database server, which must be available at the IP address 192.168.3.160 and must be listening on port 5433. The user name for logging in is „external” with the password „secret007”. Whenever a nonexistent parameter is accessed, the text value <undefined> will be returned.

server "192.168.3.160:5433" user "external" password "secret007" webURLPrefix "http://mypolarion.example.com"

In addition to connecting to the database server, the above configuration also specifies a URL prefix (webURLPrefix). YT uses it for opening a Polarion artifact in a web browser. Double-clicking on a Polarion artifact in YT navigates the web browser to the URL that results from concatenating the URL prefix and the indication of the specific work item.

Artifact type

The Polarion adapter allows for flexible artifact configuration to specify which artifacts YAKINDU Traceability should import from the Polarion data access.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Polarion data access in the Data access drop-down list.

Keywords

Supported keywords:

  • != – „Not equals” operator to use within a condition
  • == – „Equals” operator to use within a condition
  • contains – Constraint for substring check
  • customField – Reads a custom fields from work items, see below.
  • include objects if - Starts an include expression. Artifacts will be included if they satisfy the following conditions expression.
  • map - Starts an mapping block. This is optional.
  • name - Defines the name of the artifacts.
  • valueOf – Starts a valueOf condition.

To filter artifacts delivered by the data access the include objects if( condition ) expression is used. It instructs the Polarion adapter to only consider artifacts that satisfy the specified condition.

A condition is defined by the following syntax:

valueOf( attributeName ) operator value

Here,

  • operator is a boolean operator, like ==, !=, or contains, and
  • value is a literal string, like „foobar”.

As attributeName, you can use any of the predefined constants from the following list:

  • author
  • autosuspect
  • created
  • deleted
  • description
  • duedate
  • id
  • initialEstimate
  • location
  • module
  • outlinenumber
  • plannendEnd
  • plannendStart
  • previousStatus
  • priority
  • project
  • remainingEstimate
  • resolution
  • resolvedOn
  • revision
  • severity
  • status
  • timeSpent
  • title
  • type
  • updated
  • uri

To access custom fields, use customField instead of valueOf.

Custom fields

A custom field is a named field you can define in Polarion, in addition to the work item fields mentioned above. A work item can have zero, one, or more custom fields.

Polarion provides a number of possible types for custom fields, including multi-value types. However, when accessing custom fields from YT, values are always mapped to text strings in YT, i.e., an expression like customField("storyPoints") always returns a text. If a custom field has multiple values, YT retrieves them as a single string with the individual value separated by a comma (‚,’).

To access the value of a custom field, use the customField clause. You can use the customField clause multiple times to access multiple custom fields. While editing, code completion will show you the available custom field name.

Please note: Multiple conditions are implicitly concatenated by a logical AND.

Example:

include objects if(
	valueOf(type) == "userstory"
	customField("storyPoints") != ""
)
name valueOf(id)

The example above will include artifacts whose type is userstory and that have the custom field storyPoints set. The custom field storyPoints being unset will be recognized by comparison with the empty string. The latter could be changed by the undefined attribute value option in the data access configuration. The name of these artifacts will be set to the id attribute’s value.

You can map attributes, too. Example:

include objects if(
	valueOf(type)=="userstory"
	customField("storyPoints")!=""
)
map{
	^attribute to valueOf(author)
	^severity to valueOf(severity)
}
name valueOf(id)

This example expands the previous example. Here we are mapping two attributes to the values of a Polarion work item.

The Polarion adapter allows to specify which links YAKINDU Traceability should import from the Polarion data access. Make sure artifact types have been configured before.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select a Polarion artifact type with Polarion as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • The data access to be selected depends on your A and B artifact types, which should have been configured in a prior step:
    • If A and B are both Polarion artifact types with the same Polarion data access, select that data access. No further configuration is necessary, because YT will link matching types automatically.
    • If either A or B is not a Polarion artifact type, select the Native File.

By default all links in Polarion are resolved against the current (latest) items and ignored if the item does not exist. If you want to read only links which are not linked to the baselined version of an item you can configure the mapping to ignore them:

include link if (
	valueOf(revision) == ""
)

Example:

Supported options:

  • include link if ( condition) – Filter for link attributes
  • valueOf – Refers to the attributes in the link table.
  • map - Starts an mapping block. This is optional.

A list of available link attributes can be displayed by content assist (pressing [Ctrl]+[Space] inside the braces of valueOf).

Example:

In this example, YT reads all trace links between two polarion items which are not suspect. The attributes suspect, role, and revision are available in link attributes.