Admin Info

Polarion links can only reference a specific revision of a target WorkItemWork Item in a direct linklink, andbut dothis is not have the ability to do sopossible with a backlink. So ifIf a reference withincluding a revision is added in the description ofto a source WorkItem,Work anItem's actiondescription and a backlink rule applies, you must be defineddefine how the Links Synchronizer should behavehandle whenthis a reference with a revision is added and a backlink configuration would apply.case.

Fallback

All Types

A general configuration that is used to create aapply link rules to aany referenced WorkItemWork Item in a description. The rules set updefined here are usedapplied ifwhen no type-specific configuration has been set upexists for athe WorkItemWork whose description isItem being evaluatedevaluated, or when no type-specific filter could be applied.

Typed Configuration

A type-specific configuration used to apply link rules to a referenced WorkItemWork Items in a description. TheThese rules set up are only usedapplied ifwhen a type-specific configuration has been set upexists for athe WorkItemWork whose description isItem being evaluated and a matching type-specific filter applies.

Rule

A rule contains the informationdefines which link role should be used under which conditions. ItEach containsrule specifies a link role, a target projectproject, and optionally target WorkItemWork Item types are specified on the left sideside. ofTarget theWork rule. The target WorkItemItem types can be left empty if the target type is not relevantrelevant. for that rule. In addition, theThe reference data types to the right of the rule for which the corresponding link role is to be usedapplies are also specified foron thesethe conditions.right side of the rule.

Rule Priority

The number on the leftmostleft side of each rule in the general configuration or in any of the typed configuration indicates the order in which eachrules ruleare isevaluated usedwhen to matchmatching a WorkItemWork referenceItem andreference. indicatesA whichlower linknumber rolemeans willhigher be used if the sprcific rule configuration applies.priority. You can change the order of thereorder rules by using the up and down buttons to switchmove with thea rule above andor below,below respectively.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

A set of link roles used exclusively for this extension. All link roles listed in this section (automatically and manually set link roles) are matched with referenced WorkItems in the description of any WorkItem in the current project and handled according to the filters set above. Depending on whether a filter can be applied to referenced WorkItems and the associated link, the link will either be set, removed, or updated if changes need to be made.

It is strongly recommended to use only link roles that are used exclusively for this feature, since links are also removed when a reference is removed from or not found in a description.

Reference Data Type

Polarion differentiates between following reference data types with which workitems are embedded in a description.

• Cross References:

  Cross References are special Polarion hyperlinks used to quickly navigate to the referenced WorkItem within a LiveDoc. They can be identified by the dashed underline under the WorkItem reference and can contain the outline number, type icon, id or title of the referenced WorkItem. A user-defined label may also be specified. Clicking such a link will shift the LiveDoc view into position of the referenced WorkItem.

• Live Links:

  Live Links are special Polarion hyperlinks used to reference any WorkItem within a Polarion repository. It can contain the type icon, id or title of the referenced WorkItem. A user-defined label may also be specified. Clicking such a link will open the WorkItem in the Tracker view.

• Hyperlinks:

  Hyperlinks behave like commonly known hyperlinks. These hyperlinks are by default displayed with their URL or alternatively with a user-defined label. In order for the extension to work for these hyperlinks, their URL must contain the base.url value of the polarion.properties configuration (the URL to the same Polarion server). Clicking such a link will open the URL in the same or a new browser tab.

Backlink 

Sets the link in the other Workitern and not the one that has the reference in the description, creating a backlink.

• If the created link on the other Workitem is deleted manually, the change cannot be detected by the Workiterm that references that Workiterm and the link will stay missing. This is a common technical hurdle arising from the use of backlinks. A regular update of all Workitems by the LS Job is therefore recommended.
• If the other Workitem is in a foreign project, conflicts may arise between the LS configuration of the foreign project and this LS configuration.
• There may also be problems with users who have different permissions in the respective projects that affect reading or writing Workiterns.
• A revision of a Workitem reference is not supported for backlinks and is therefore not created by the extension, as the resulting state would be invalid.

CAUTION:
The following lists caveats in the Links Synchronizer extension that are not implemented due to technical difficulties or may incur significant performance penalities.

• Validation of Link Synchronizer Configurations between 2 or more Projects.
  There is no validation checking a Links Synchronizer configuration against a Links Synchronizer configuration of another project. This means that a rule can be set up that is complementary to another rule in a configuration of another project. For example, one project may be set up to create a link, while the other project containing the target WorkItem may 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 of a Reference or Link, the Links Synchronizer cannot read the required information (e.g. WorkItem Type) to check whether a link needs to be set or removed. Therefore, references and links to WorkItems that are not readable by the user are skipped.
• Missing target WorkItem of 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 if a target WorkItem of a Reference or Link does not exist, it will be 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