# Linking Work Items using tags 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 [configuration file](/specsync/jira/reference/configuration.md). The links can be configured in the [`synchronization/links` section](/specsync/jira/reference/configuration/configuration-synchronization/configuration-synchronization-links.md) 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 [pull command](/specsync/jira/features/pull-features/two-way-synchronization.md). 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 [Restrict linked issue to be of a specific type](#target-type) 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 an exit code in the range of 10-19. 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" } ], ... }, ... } ``` {% hint style="info" %} 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. {% endhint %} ## 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" } ], ... }, ... } ``` {% hint style="info" %} Some Jira test case management solution does not support different link relationships. In those cases the setting should not be left unspecified. {% endhint %} {% hint style="info" %} The link type name is case sensitive and might contain spaces. {% endhint %} {% hint style="warning" %} 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](/specsync/jira/reference/command-line-reference.md). {% endhint %} ## 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. {% hint style="info" %} 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. {% endhint %} The following example allows using the `@bug:` prefix only for "Bug" issues. ``` { ... "synchronization": { ... "links": [ { "tagPrefix": "bug", "targetType": "Bug" } ], ... }, ... } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.specsolutions.eu/specsync/jira/features/common-synchronization-features/linking-work-items-with-tags.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.