Atlassian JIRA Connector [pre Sync 3.5]

Atlassian JIRA Queries

It is recommended to use Atlassian JIRA server-side queries (or “filters” in JIRA) for the Changes Query and Initialization Query, because it is easier to check that the queries are working over the JIRA web UI by looking at the query results.

To create a JIRA server-side query (“filter”), in the Web UI for JIRA, select Issues > New. There is the choice of a simple or advanced search; the advanced search allows relative dates.

For example, to get the tasks which have changed in the past two days, use:


updated >="-2d"

When the Changes Query is created, make sure that the time scoping works properly before using it in Tasktop Sync.

Once the query has been defined, click on the Search button, and then in the left-hand pane, click on Save it as a filter. There will be a page which asks for a name and a description. The name here will need to match the name in synchronizer.xml exactly. It is recommended to use a name with three parts: “Tasktop Sync”, the project name, and a description of what is returned, e.g. “Tasktop Sync - Cobra Project JIRA - Recently Modified Defects”.

Atlassian JIRA Repository requirements

JIRA does not have the concept of links, so a custom field for storing Tasktop Sync proxy associations will need to be created. It must be a free text field, global (all issues). In synchronizer.xml, the custom field will be referred to with with the custom field ID, so the name is arbitrary. It is recommended to name this field tasktop_sync_proxy for documentation purposes.

Tasktop Sync requires the ID of this custom field.

To find the custom field ID, go to the JIRA web interface and sign in as an administrator. Select Administration from the header on the right side, then click on Issues, and select View Custom Fields. On the right hand side of the entry of the relevant field, there will be a link for Configure. The custom Field ID will be in the last part of that URL, e.g. if clicking Configure links to http://example.com:8080/secure/admin/ConfigureCustomField!default.jspa?customFieldId=10000, then the custom field ID is attribute.jira.custom::customfield_10000.

JIRA should also be configured to allow remote API calls. To turn on remote API calls, first sign into JIRA as an administrator and select Administration from the header. Under System select General Configuration and then scroll down and find Edit Configuration. After clicking Edit Configuration, scroll down and find Accept remote API calls, then select the On radio button and click Update to complete the change.

Atlassian JIRA synchronizer.xml requirements

Required repository properties

The following properties need to be added to the repository section.

   <scope>
      <field id="project" value="COBRA"/>
   </scope>
   <proxy-storage-attribute id="attribute.jira.custom::customfield_10000" />
   <proxy-storage-attribute id="attribute.jira.custom::customfield_10000" sparse="true"/>

Additional requirements

JIRA excludes empty custom attributes from the task data. When mapping a custom JIRA attribute, a sparse flag must be set to true, e.g.:

   <attribute key="attribute.jira.custom::customfield_10100" sparse="true">

The above setting ensures that Tasktop Sync will detect that the value of a custom JIRA attribute has been cleared.

The default copy attribute mapping strategy must be used when mapping a custom JIRA attribute. This strategy, when paired with the sparse attribute, ensures that if the target custom attribute has been excluded from the JIRA task data, then the attribute will be created.

Status caster

To map status in JIRA with workflow restrictions, a multiple submission Groovy scripted caster should be used. An example of a multiple submission Groovy scripted caster can be found in the Tasktop Sync User Guide.

Comments

The comment-content-type for JIRA repositories should be set to confluence.

Fix/Affects Version attributes

Synchronizing the JIRA Fix/Affects Version attributes requires that the value "" must be explicitly mapped if resetting the selection is needed. e.g:

        <attribute-mapping>
            <attribute id="category" caster="value-map">
                <caster-configuration>
                    <map>
                        <entry key="" value="Unassigned Project in non-JIRA repository"/>
                    </map>
                </caster-configuration>
            </attribute>
            <attribute id="attribute.jira.affectsversions" caster="value-map">
                <caster-configuration>
                    <map>
                        <entry key="Unassigned Project in non-JIRA repository" value=""/>
                    </map>
                </caster-configuration>
            </attribute>
        </attribute-mapping>