SpecSync Documentation
Jira
Jira
  • Introduction to SpecSync for Jira
  • Getting started
    • Getting started using SpecFlow
    • Getting started using Cucumber or other Gherkin-based BDD tool
  • Installation & Setup
    • Install as .NET tool
    • Install as .NET Console App
    • Install as native binaries for Linux or macOS
    • Install as Docker image
    • Setup and Configure
  • Features
    • Push features
      • Pushing scenario changes to Test Cases
      • Configuring the format of the synchronized test cases
      • Synchronizing Scenario Outlines
      • Update Test Case fields
      • Attach files to Test Cases using tags
      • Customization: Setting Test Case fields with default values
      • Customization: Update custom Test Case fields on push
      • Customization: Ignoring marked Test Case steps
      • Customization: Ignoring Test Case Tags
      • Customization: Ignore non-supported local tags
      • Customization: Mapping tags
      • Customization: Synchronizing scenarios from feature branches
      • Customization: Automatically link changed Test Cases
      • Customization: Synchronize linked artifact titles
      • Customization: Do not synchronize title
    • Pull features
      • Pulling Test Case changes to local scenarios
    • Common synchronization features
      • Configuration key
      • Remote scope
      • Linking Work Items using tags
      • Synchronizing Test Case hierarchies
      • Excluding scenarios from synchronization
      • Synchronization conflict resolution
    • Test result publishing features
      • Publishing test result files
    • General features
      • Jira authentication options
      • Configuration file
      • Hierarchical configuration files
      • Local test case conditions
      • Configuration wizards
      • SpecSync plugins
    • Customizations
    • Plugin list
  • Licensing
  • Guides
    • What is my Jira server URL?
    • Jira Test Case Management (TCM) solution
    • How to define the local feature-set to be synchronized
    • Filters and scopes
    • How to use SpecSync from build or release pipeline
    • How to upgrade to a newer version of SpecSync
    • How to attach files to test results
    • Using SpecSync with Cucumber
    • Using SpecSync with Cypress
    • Using SpecSync with Postman
    • Using SpecSync with TestNG
    • Using SpecSync on macOS or Linux
    • Using SpecSync inside a Docker container
    • Migrating from SpecSync v1 to v5
  • Changelog
  • Release Model and Roadmap
  • Downloads
  • Reference
    • Command line reference
      • init
      • upgrade
      • push
      • pull
      • publish-test-results
      • version
    • Configuration reference
      • toolSettings
      • local
      • remote
      • jira
      • knownRemotes
      • synchronization
        • push
        • pull
        • links
        • attachments
        • format
        • fieldUpdates
      • hierarchies
      • publishTestResults
      • specFlow
      • customizations
    • Compatibility
    • Older versions
  • Contact
    • SpecSync Support
    • Troubleshooting
    • FAQ
  • Project Website
Powered by GitBook
On this page
  • The issue tags
  • Using multiple tag prefixes
  • Link types
  • Restrict linked issue to be of a specific type

Was this helpful?

  1. Features
  2. Common synchronization features

Linking Work Items using tags

PreviousRemote scopeNextSynchronizing Test Case hierarchies

Last updated 5 months ago

Was this helpful?

SpecSync can synchronize the scenarios with Jira Test Cases. In order to be able to use these Test Cases in Jira, you might want to link them to other issues. For example, if the scenario is describing the behavior of the User Story #P01-123, you make a link between the Test Case synchronized from the scenario and the story. This gives you a better traceability and allows you to create queries, like all Test Cases (scenarios) that are related to User Story #P01-123.

Although you can establish these links manually, once SpecSync has created the test cases from the scenarios, it is an error-prone manual process. A better way to do this is to mark the relation of the scenarios to other issues via tags and let SpecSync create the necessary links between the issues.

For that you need to mark the scenarios with tags, like @story:P01-123, and specify the tag prefix (in this case story) in the SpecSync . The links can be configured in the of the configuration.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story"
      }
    ],
    ...
  },
  ...
}

This will synchronize the scenario with the Jira test case and establish a link between the test case and the user story #P01-123 issue.

The links created by SpecSync are by default are "tracked". This means that the links are removed when the tag is removed from the scenario. You can disable creation of tracked links by setting disableTracking to true in the link configuration. Non-tracked links and links created manually are never removed.

SpecSync attempts to create and maintain issue tags during . In order to choose the right tag for new Test Case link, it considers the specified target issue type (targetType setting). Therefore if you plan to use the pull command it is recommended to set the target type. See section for details.

The issue tags

The issue tags should follow the pattern @prefix:N, where prefix is a label of your choice (e.g. story, bug or wi) and N is the ID of the related issue (e.g. P01-123).

The issue tag can be specified at scenario level or feature level. In the latter case, it behaves like you would have applied the tag for all individual scenarios. This can be useful if all scenarios in the feature file are related to a feature or a user story issue.

If the issue with the specified ID does not exist or the user who performs the synchronization does not have permission for it, SpecSync will display an error message for that particular scenario. If at least one scenario has failed to synchronize, the command line tool returns with the exit code 10.

Optionally you can add an additional label to the issue tags to help the readers to understand what the referred issue is about. The additional label has to be separated by the issue number with a colon (:) character, like @bug:P01-456:argument_error_for_empty_input .

Using multiple tag prefixes

In order to distinguish between the different relations in the feature file, you can also use and synchronize multiple prefixes. E.g. you can tag a scenario with @story:P01-123 and @bug:P01-456 indicating that the scenario was related to the user story #P01-123 and it fixes the bug #P01-456.

In order to use multiple tag prefixes, you have to list multiple link type configurations within the synchronization/links section.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story"
      },
      {
        "tagPrefix": "bug"
      }
    ],
    ...
  },
  ...
}

SpecSync does not check the type of the referred issue. Specifying @bug:P01-123 will also make the link between the user story #P01-123 and the test case. Though you can establish different link types for the different prefixes.

Link types

SpecSync creates a "Tests" link type between the test cases and the other issues by default. If you want to establish another kind of relationship (e.g. Parent), you can specify the link type in the relationship setting. The specified relationship defines how the linked issue is related to the test case, e.g. specifying Parent means that the linked issue will be the parent of the test case issue.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story",
        "relationship": "Parent"
      }
    ],
    ...
  },
  ...
}

Some Jira test case management solution does not support different link relationships. In those cases the setting should not be left unspecified.

The link type name is case sensitive and might contain spaces.

Restrict linked issue to be of a specific type

By default SpecSync will not verify the type of the linked issue: any type of issues can be used. You can enforce that a certain tag prefix can only be used for a specific issue type using the targetType setting.

When the "pull" command is used, SpecSync attempts to use the best tag prefix if there are multiple available by selecting the first with matching targetType or the first of the ones without targetType otherwise.

The following example allows using the @bug: prefix only for "Bug" issues.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "bug",
        "targetType": "Bug"
      }
    ],
    ...
  },
  ...
}

Changing the link type will not trigger the re-synchronization of the scenario. If the scenario has been synchronized already, you have to to force synchronization using the .

--force command line option
configuration file
synchronization/links section
pull command
Restrict linked issue to be of a specific type