Admin Info

EN | Administrator Guide for Configuring the UPPS! Extension Links Synchronizer (LS)

---

Overview

Who is this documentation for?

This documentation is intended for system or project administrators responsible for configuring the UPPS! Extension Links Synchronizer (LS).

Prerequisites

Before reading this documentation, you should be familiar with basic Polarion project administration.

What you will learn

After reading this documentation, you will be able to active, and configure the behaviour of the Links Synchronizer for specific projects individually.

Overview of Links Synchronizer

The Links Synchronizer automatically manages Work Item links. It scans the description of a Work Item being saved and ensures that any Work Items referenced via a Polarion Cross-Reference, Polarion Live Link, or Hyperlink receive a corresponding Work Item link, according to a predefined configuration.

Configuration

Introduction

The Links Synchronizer can be configured using either of the following two options:

• Configuration page — accessible in each Polarion project, this lets you specify how the extension should behave for that project. Once configured, the link roles of every Work Item saved in that project are automatically managed according to the configuration.
• Polarion job — applies the configuration across all projects for which the extension is enabled. Use this primarily to synchronize existing Work Items whose link roles have not yet been processed, or after making changes to the Links Synchronizer configuration.

It is strongly recommended that you test this feature in a non-production environment before using it in production. The extension adds and removes link roles across multiple work items, potentially spanning different projects, depending on how the work items are linked and how the extension is configured.

Configuration via Configuration Page

Access the Configuration Page

The Links Synchronizer is configured separately for each Polarion project. Administration permission is required.

1. Click the Administration button, navigate to the UPPS! Extensions entry, and open the drop-down menu.
2. Click Links Synchronizer to open the configuration page.

 

At the top of the configuration page you will find the following options:

Note: Saving the configuration by clicking SAVE CONFIGURATION has no effect on your Polarion project until you check the Enable extension for this Project checkbox.

Extra Fields Config

This section contains settings that control the extension's behavior based on the configuration and content of a Work Item.

Include references in TestSteps of WorkItems
Enabling this option causes the extension to scan the Test Steps field for Work Item references in addition to the description field.

Enabling this option may significantly impact the performance of the Links Synchronizer job, as Test Step content is processed at the Java level, which is considerably slower than SQL processing.

Include references in resolved WorkItems
By default, resolved Work Items are not processed. Enabling this option causes the extension to scan for Work Item references in Work Items configured with a direct link rule and set the appropriate link role even if the Work Item is resolved (i.e., has a resolution value set).

Note: For performance reasons, permissions to modify Work Item links are not checked when this option is enabled. Only enable this if you permit Work Item links to be modified on resolved Work Items.

Include references to resolved target WorkItems with backling configurtions
By default, resolved Work Items are not processed. Enabling this option causes the extension to scan for Work Item references in Work Items configured with a backlink rule and set the link role on the referenced Work Item even if it is resolved (i.e., has a resolution value set).

Note: For performance reasons, permissions to modify Work Item links are not checked when this option is enabled. Only enable this if you permit Work Item links to be modified on resolved Work Items.

Extra Backlink Config

Backlink Revision Action

Polarion links can reference a specific revision of a target Work Item in a direct link, but this is not possible with a backlink. If a reference including a revision is added to a source Work Item's description and a backlink rule applies, you must define how the Links Synchronizer should handle this case.

Fallback

All Types

A general configuration used to apply link rules to any referenced Work Item in a description. The rules defined here are applied when no type-specific configuration exists for the Work Item being evaluated, or when no type-specific filter could be applied.

Typed Configuration

A type-specific configuration used to apply link rules to referenced Work Items in a description. These rules are only applied when a type-specific configuration exists for the Work Item being evaluated and a matching type-specific filter applies.

Rule

A rule defines which link role should be used under which conditions. Each rule specifies a link role, a target project, and optionally target Work Item types on the left side. Target Work Item types can be left empty if the target type is not relevant. The reference data types for which the link role applies are specified on the right side of the rule.

Rule Priority

The number on the left side of each rule indicates the order in which rules are evaluated when matching a Work Item reference. A lower number means higher priority. You can reorder rules using the up and down buttons to move a rule above or below its neighbor.

Type Fallback

This configuration checks the "All Types" configuration as a fallback option. If it is not active, nothing is done if no rule applies, or links are removed that would otherwise match an "All Types" configuration.

Reserved Link Roles

AThis setsection oflists the link roles used exclusively forby thisthe extension.Links Synchronizer. All link roles listed inhere this— sectionwhether (set automatically andor manually set link roles)— are matched withagainst Work Items referenced WorkItems in the description of any WorkItemWork Item in the current projectproject, and handled according to the filtersconfigured set above.rules. Depending on whether a matching filter can be applied to referenced WorkItems and the associated link,applies, the link will either be set, removed, or updated if changes need to be made.updated.

ItOnly is strongly recommended to use onlyassign link roles here that are used exclusively forby thisthe feature,Links sinceSynchronizer. linksLinks are alsoautomatically removed when athe corresponding reference is removedno fromlonger or not foundpresent in a Work Item description.

Reference Data Type

Polarion differentiatessupports betweenthe following reference data types withfor whichembedding workitemsWork are embeddedItems in a description.description:

Cross-References

• Cross References:

  Cross References are specialSpecial Polarion hyperlinkslinks used to quickly navigate to thea referenced WorkItemWork Item within a LiveDoc. TheyIdentifiable by a dashed underline, they can be identified by the dashed underline under the WorkItem reference and can containdisplay the outline number, type icon, idID, or title of the referenced WorkItem.Work AItem, user-definedwith labelan mayoptional alsocustom be specified.label. Clicking suchone a link will shiftshifts the LiveDoc view intoto the position of the referenced WorkItem.Work Item.

• Live Links:

  Live Links are specialSpecial Polarion hyperlinkslinks used to reference any WorkItemWork Item within a Polarion repository. ItThey can containdisplay the type icon, idID, or title of the referenced WorkItem.Work AItem, user-definedwith labelan mayoptional alsocustom be specified.label. Clicking suchone a link will openopens the WorkItemWork Item in the Tracker view.

Hyperlinks

• Hyperlinks:

  Hyperlinks behave like commonly known hyperlinks. TheseStandard hyperlinks are by default displayed with their URL or alternativelyan withoptional custom label. For the Links Synchronizer to process a user-definedhyperlink, label. In order for the extension to work for these hyperlinks, theirits URL must containmatch the base.url value ofin the polarion.properties configuration (the— URLthat is, it must point to the same Polarion server).server. Clicking suchone a link will openopens the URL in the same or a new browser tab.

Backlink 

SetsWhen a backlink rule applies, the link inis set on the otherreferenced WorkiternWork andItem notrather than the one that hascontaining the reference in its description.

Be aware of the description,following creatingconsiderations awhen backlink.using backlinks:

• If the created link on the otherreferenced WorkitemWork Item is deleted manually, the changesource Work Item cannot bedetect detectedthis by the Workiterm that references that Workitermchange, and the link will stayremain missing. ThisRegular is a common technical hurdle arising from the useexecution of backlinks. A regular update of all Workitems by the LS Jobjob is thereforerecommended recommended.to keep backlinks in sync.
• If the otherreferenced WorkitemWork isItem inbelongs to a foreigndifferent project, conflicts may arise between the LS configurationconfigurations of the foreigntwo project and this LS configuration.projects.
• There may also be problemsUsers with users who have different permissions in the respectiveacross projects thatmay affectencounter issues reading or writing Workiterns.Work Items involved in backlinks.
• ARevision-specific revisionreferences of a Workitem reference isare not supported for backlinks and is thereforewill not be created by the extension, as the resulting statethis would beresult invalid.in an invalid state.

CAUTION:Caution:
 The following listsare caveatsknown inlimitations of the Links SynchronizerSynchronizer. extension thatSome are not implemented due to technical difficultiesconstraints; orothers may incurcause significant performance penalities.impact.

No

• Validationcross-project ofconfiguration Linkvalidation Synchronizer Configurations between 2 or more Projects.
  There is no validation checkingbetween athe Links Synchronizer configuration against a Links Synchronizer configurationconfigurations of anotherdifferent project.projects. This means thata rule in one project may conflict with a rule can be set up that is complementary toin another rule— in a configuration of another project. Forfor example, one project may be set up to create a link,link whilethat the other project's configuration attempts to delete. Review configurations across projects carefully when Work Items are linked across project containingboundaries.
  the

  Missing read permissions on target WorkItemWork mayItems attempt to delete that link.

• Missing permissions to read a target WorkItem.
  If a user does not have permission to read a WorkItem that is the target ofWork a Reference or Link,Item, the Links Synchronizer cannot readretrieve the required information needed (e.g.such WorkItemas Type)Work Item type) to checkdetermine whether a link needs toshould be set or removed. Therefore, referencesReferences and links to WorkItemsunreadable thatWork are not readable by the userItems are skipped.

• Missing or invalid target WorkItemWork ofItems a Link or Reference.
  The Links Synchronizer treats missing or incorrect WorkItems as if the user had no permission to read the required information (see above). So ifIf a target WorkItemWork ofItem referenced in a Reference or Linkdescription does not exist, it willis betreated the same as a missing-permission case (see above) and skipped.

Configuration via Polarion Job

Configure the Job

Add the following scheduler job configuration via Global Administration > Scheduler and configure it as needed.

  <!--
    Processes workitems in all projects with an enabled UPPS!E Links Synchronizer configuration
    to ensure that the workitem links align with the Links Synchronizer configuration.

    Properties:
      - userVaultKey:
          The key identifying a user account in the Polarion user account vault.
          The job will then execute as the specified user.
          Ensure that this user has permission to modify workitems in all projects.

          Possible values: Key of a user specified in the User Account Vault
          Optional: If the job is executed manually through the Polarion Monitor interface.
          Required: If the job is executed automatically via cron-job.

      - batchSize:
          The number of workitems that will be processed before a commit to the svn repository will occur.
          Due to technical circumstances, committing a large amount of changes may render the system unstable or unusable.
          A batch size is therefore specified that will divide workitems changed by the Links Synchronizer into commit groups
          up to a maximum of ${batchSize} workitems.

          Possible values: Any integer greater than 0
          Optional: Default value is 500 workitems.

      - showUpdatedWorkItems:
          Specify whether to explicitly list all workitems in the job log by their id that were updated.
          The job log will print a lucene query with all updated workitems so that you can list them in the workitem tracker.

          Possible values: true or false
          Optional: Default value is false.
  -->
  <job
      disabled="true"
      id="upps.links.synchronizer.job"
      name="UPPS!E Links Synchronizer: Ensure sync"
      scope="system">
      <!-- <userVaultKey></userVaultKey> -->
      <!-- <batchSize>500</batchSize> -->
      <!-- <showUpdatedWorkItems>false</showUpdatedWorkItems> -->
  </job>

Starting the Job

Once you have configured the LSLinks Synchronizer job, it appears as an entry in the Monitor.

Start the LS job by checking the box next to it (1), then clicking Execute now (2). You can refresh the job view (3) to check the current status. For detailed information about the job process, view the log (4).

If the userVaultKey job property is not configured, the job runs as your currently logged-in user. Work item changes and the permissions required to make them are evaluated based on your user account and your permissions in each project.

After the job completes successfully, you can review the updated work items if the showUpdatedWorkItems property is enabled. If any work items were updated, the job log will contain the following entry:

This is a Lucene query that you can paste into the Polarion work item tracker search to list the updated work items in detail.