Configuring Document Merge Actions

Users with the requisite permissions can merge Work Item content between two Documents. A default set of merge actions is available to users. It is defined in the configuration file actions.xml. This file specifies which actions are available in the Merge sidebar for a Document that is the target of the merge action a user want to perform. The Merge sidebar is accessible when comparing two Documents.

Administrators can modify the configuration to exclude any of the actions defined in this file. For example, if the project's managers decide that copying a Work Item should not be allowed, the Copy the Work Item action can be excluded in the configuration. When excluded, the action is hidden in the sidebar, even if it would otherwise be a valid action. Allowed actions can optionally be conditional, allowed only if the conditions described in the <conditions> element of actions are satisfied. You can find more detailed information in comments at the end of the actions.xml configuration file.

In the same configuration file you can also control merging of Work Item fields, specifying which fields should and should not be included when merging Work Items.

This configuration is available in both global and project scope, and requires editing the underlying XML configuration file. You can do that either online in Administration, or offline in an XML editor, uploading the modified file back to the Administration page.

Merge Terminology

The actions.xml file contains explanatory comments and action descriptions that use some terms that it is important to understand.

  • Source Document: the Document the user is merging content FROM.

  • Source item: a Work Item contained in or appearing via reference in the Source Document.

  • Target Document: the Document the user is merging content TO.

  • Target item: a Work item contained in or appearing via reference in the Target Document.

  • Overwritten item: a Work Item in the target Document that is referenced from the source Document, but the content is changed in the target Document.

Working With the Configuration File

To access the configuration file:

  1. Log in with administrator permissions for the scope you want to configure, and open the project (or Repository for a global configuration).

  2. Enter Administration, and in Navigation select Documents and Pages > Merge Actions.

In the editor on the page, you modify the XML code as necessary and save the change. Alternatively, you can use the link on the page to download the XML file, modify it offline, and upload it back to the page.

Configurable elements include:

  • The action's title and description (<title> and <description> elements). Users see these strings in panels inside the Merge sidebar.

  • The background color of the action selector in the Merge sidebar, via the color attribute of an <action> element. The value is a CSS-style hexadecimal... #FFFFFF, for example.

  • The color of text (foreground) in an action selector in the Merge sidebar (rendered from the <title> and <description> elements of an <action> element). Specified in the text-color attribute of an <action> element.

Example of the color attributes in an action element:

<action id="com.polarion.unmarkWorkItem" color="#c0392b" text-color="#FFFFFF">
			

Disabling Merge Actions

If managers decide that one or more of the default set of merge actions should not be available to users, simply enclose the relevant <action> element(s) in a XML comment marker: <!-- -->

Example:

<!-- <action id="com.polarion.deleteWorkItem" color="#c0392b" text-color="#FFFFFF">
    <title>Delete Work Item</title>
    <description>
        Delete Work Item from the Document and the repository (but not from History)
    </description>
</action> -->
				

TIP

Comment out actions rather than delete them. Should things change in the future, actions can then be easily enabled by removing the comment markers.

Using Merge Action Conditions

You can optionally configure merge actions to be conditional contingent upon some condition(s) being satisfied. The <conditions> element can contain one or more <condition> elements and logical operator tags to define simple or complex conditions, including the result of a query on Work Items. The following points are important to keep in mind when specifying conditional merge actions:

  • The <conditions> element is a child of the <action> element. Only one <conditions> element is allowed within any <action> element. Any that appear after the first one are ignored.

  • The <conditions> element can contain multiple <condition> elements.

  • You can construct complex conditions by using nested <and>, <or>, and <not> tags within a <condition> element.

  • The <not> tag can contain multiple tags and the result is the same as if they were inside an <and> tag. Therefore, the <not> tag actually works like a NAND logical operator.

  • Empty <and>, <or> tags evaluate to "true". Empty <not> tags evaluates to "false".

  • Unknown or invalid elements and tags, and <condition> elements having an unknown/invalid id attribute value are ignored.

Conditions Configuration Format

The following example also shows the possible condition ID values, except for query-based conditions - information for that follows the listing.

<action id="...">
    <conditions>
        <not>
            <condition id="com.polarion.sourceDocumentBranchedFromTarget"/>
        </not>
        <not>
            <condition id="com.polarion.targetDocumentBranchedFromSource"/>
        </not>
        <not>
            <condition id="com.polarion.sourceWorkItemBranchedFromTarget"/>
        </not>
        <not>
            <condition id="com.polarion.targetWorkItemBranchedFromSource"/>
        </not>
    </conditions>
</action>
					

Query-based Merge Action Conditions

If a <condition> element has one of the following values specified in its id attribute, the element can contain a Lucene query on the respective artifact (see Example, below):

  • com.polarion.sourceWorkItemQuery - the element value should be a query on the attributes of the Source Work Item.

  • com.polarion.targetWorkItemQuery - the element value should be a query on the attributes of the Target Work Item.

  • com.polarion.sourceDocumentQuery - the element value should be a query on attributes of the Source Document.

  • com.polarion.sourceDocumentQuery - the element value should be a query on attributes of the Target Document.

Example:

<action id="...">
    <conditions>
        <-- Work Item queries: --> 
        <condition id="com.polarion.sourceWorkItemQuery">type:task</condition>
        <condition id="com.polarion.targetWorkItemQuery">type:requirement AND status:draft</condition>
        <-- Document queries: -->
        <condition id="com.polarion.sourceDocumentQuery">type:generic</condition>
        <condition id="com.polarion.targetDocumentQuery">type:test-spec AND NOT status:draft</condition>
    </conditions>
</action>
					

Notes:

  • If no query is specified in the element (i.e. the query is empty), the condition is ignored.

  • If a query is specified, but no Work Item exists on the relevant merge side for the current merge action, then the condition is ignored even if the query can return some results in some other context.

Configuring Work Item Field Merging

When you merge Work Items between two Documents, you may want to exert some control over which fields are merged. Two actions for fields are present and enabled by default in the actions.xml file:

  • Merge All Fields: merges all supported Work Item fields. You can modify the description, or comment it out to if the action should not be available to users.

  • Merge Some Fields: merges only the fields specified in the com.polarion.mergeFieldsAction in the actions.xml file.

    You specify the fields to be copied in <field> elements within the <fields> element. Other fields are skipped. You can also explicitly specify field that should not be copied in <field> elements within the <excluded-fields> element.

See also: User Reference: Fields Not Supported for Merging.

Note

When comparing Documents across different projects, merge actions use settings from the project where the Target is stored.