Synchronization Workitems JIRA V2 - techtalk/SpecLog-Resources GitHub Wiki

Warning: SpecLog provides two different plugins for synchronising issues with JIRA. Migrating from SpecLog.JiraPlugin.V1 to SpecLog.JiraPlugin.V2 is currently unsupported. If you have a project using the SpecLog.JiraPlugin.V1, do not change the JIRA plugin to SpecLog.JiraPlugin.V2. Support for migrating between plugin versions is planned in a future release.

The following core fields are required in the JIRA template to synchronise SpecLog requirements with JIRA:

• Summary: Synchronised with the field specified as the header in the card template
• Description: Synchronised with the fields and prefixes specified in the card template to be displayed on the card
• The user used by the plugin to perform the synchronisation with JIRA requires jira-developers membership for the project.

For example, a requirement synchronised with an issue looks like this in the JIRA client:

Once a requirement in SpecLog has been synchronised with an issue in JIRA, the link is remembered and stored in the database to ensure that the same issue is not duplicated if it is modified.

• The field selected as the Header in the SpecLog requirement is transferred to the Summary field in JIRA
• All fields in the SpecLog requirement are formatted according to the requirement's card template and transferred to the Description field in JIRA
• All the requirement's acceptance criteria are also transferred to the Description field after the requirement fields. Acceptance criteria are delineated using separators.
• The following formatting in acceptance criteria is synchronised:
  • Bold
  • Bulleted lists

SpecLog expects the Description field in JIRA to contain the following sections:

1. The requirements, which are identified based on the prefix defined in the card template in SpecLog
2. Acceptance criteria, with each acceptance criteria delineated by a separator (4 or 5 dashes on an otherwise empty line)

Requirements in the Description field in JIRA are assigned to SpecLog fields based on the prefix defined in the card template in SpecLog as follows.

1. Starting from the first line in the Description field, the plugin compares the beginning of each line to the prefixes defined in SpecLog. If a matching prefix is found, the data after the prefix in the Summary field is transferred to the corresponding field in SpecLog. Each requirement needs to be defined on a separate line.
2. If a line does not contain a prefix, it is treated as the start of the acceptance criteria section (see below).
3. If no suitable prefix is found, the entry in the Summary field in JIRA is entered in the requirements field defined as the header in SpecLog.

Warning: You cannot add or remove acceptance criteria in JIRA due to how they are formatted in JIRA as plain text. Doing so can cause issues with the allocation of attachments to acceptance criteria in SpecLog. Acceptance criteria must be added or removed in SpecLog. You can however edit the contents of previously synchronised acceptance criteria in JIRA.

Acceptance criteria in the Description field are transferred to SpecLog as follows:

1. The first line following the requirements fields that is neither empty (only white space) nor a separator is treated as the start of the acceptance criteria. Separators must also be used to separate individual acceptance criteria. The following separators are permitted:

• 4 dashes (----)
• 5 dashes (-----)

1. Acceptance criteria consist of two sections: the title and the body:

• The first line containing data is transferred to the title field in SpecLog. Empty lines (containing only white space) following a separator are ignored and not transferred to the title field.
• All subsequent lines (including empty lines) up to the next separator are transferred to the body field.

Note: Acceptance criteria transferred from SpecLog to JIRA are formatted appropriately in JIRA.

The following formatting in acceptance criteria is transferred to SpecLog:

• Bold

To configure synchronisation with JIRA:

1. Copy the service plugin assembly to the server's /Plugins folder (note: JIRA plugins are already there after installation).
2. Select Manage repositories from the menu and connect to the server.
3. Select Configure plugins for the repository you want to synchronise work items with:
   
4. Select Configure for the plugin you want to configure from the menu on the right:
   
5. Enter the necessary information to allow the service to access the JIRA project:
   

• Server URL: The base URL of the JIRA service
• Project code: The JIRA Key of the project (project page: Summary, Description - Key)
• Issue type: The type of the issue SpecLog requirements should be synchronised as (e.g. Story)
• Update interval: Interval in minutes, which the plugin uses for synchronising changes back from JIRA into SpecLog. See Work Item Synchronization Mechanisms for further details.
• User name: The user name and password used by the plugin to connect to JIRA. This user requires jira-developers membership for the project.
• Enable back-synchronization from JIRA: If enabled, the plugin tries to synchronise changes to linked issues back to SpecLog from JIRA.
  • Create requirements from new JIRA Work Items: If enabled, the plugin creates new requirements in SpecLog for each issue created in JIRA (using the Issue type specified above)
    • Card template for created requirements: The requirement type used by the plugin to create requirements from new issues in JIRA.
      The default setting is UserStory, meaning that a new user story is created in SpecLog for each issue created in JIRA. Enter the ID of the requirement type (e.g. UserStory), which is displayed in the repository's card templates. Note that if you change the template's ID in the repository, you need to update the value here as well.

If a requirement is linked to an issue in JIRA, a link icon is displayed on requirement cards. Click on the link to open the linked issue in the JIRA web interface: