# customizations This configuration section contains settings for configuring customizations. {% hint style="info" %} The customizations described here are [Enterprise features](/specsync/licensing.md). {% endhint %} The following example shows the available options within this section. ```javascript { ... "customizations": { "fieldDefaults": { "enabled": true, "defaultValues": { "MyCompany.MyCustomField": "Default 1", "MyCompany.OtherCustomField": "Default 2" } }, "customFieldUpdates": { "enabled": true, "updates": { "System.Description": "Synchronized from feature {feature-name}{br}{feature-description}" } }, "ignoreTestCaseSteps": { "enabled": true, "ignoredPrefixes": [ "COMMENT" ] }, "ignoreTestCaseTags": { "enabled": true, "tags": [ "mytag", "ado-tag*" ] }, "ignoreNotSupportedLocalTags": { "enabled": true, "supportedTags": [ "@myTag", "@otherTag" ] } "tagTextMapTransformation": { "enabled": true, "textMap": { "_": " " } }, "requirementSynchronization": { "enabled": true, "requirements": [ { "targetType": "User Story", "condition": "$sourceFile ~ **/*.requirement.feature", "tagPrefix": "req", "linkFolderTests": true } ] }, "multiSuitePublishTestResults": { "enabled": true, "testPlan": "My Plan", "suites": [ "SuiteA", "SuiteB", "#3456" ], "includeSubSuites": true, "publishToRequirementBasedTestSuites": true, "linkTagPrefixes": [ "bug" ] }, "resetTestCaseState": { "enabled": true, "state": "Ready", "condition": "@ready" }, "addTestCasesToSuites": { "enabled": true, "testSuites": [ { "name": "Important Logic", "condition": "@important and not @external" } ] }, "branchTag": { "enabled": true, "prefix": "tc.mybranch" }, "linkOnChange": { "enabled": true, "links": [ { "targetId": "{env:CURRENT_STORY}", } ] }, "synchronizeLinkedResourceTitles": { "enabled": true, "linkTagPrefixes": [ "story" ] }, "doNotSynchronizeTitle": { "enabled": true } } ... } ``` ## Available customizations ### fieldDefaults Enables setting default values to test case fields. Useful for custom Azure DevOps process templates. See [Customization: Setting Test Case fields with default values](/specsync/features/push-features/customization-setting-test-case-fields-with-default-values.md) for details. | Setting | Description | Default | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `fieldDefaults/enabled` | Enables the customization. | `false` | | `fieldDefaults/defaultValues` | A list of key-value pair, where the key is the canonical name of the field to be updated (e.g. `System.Description`) and the value is the default value to be used when the test case is created. | mandatory | The `fieldDefaults` customization setting is a shortcut for configuring the [`synchronization/fieldUpdates` section](https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization-fieldupdates.md). The example above is equivalent to the following `fieldUpdates` setting: ```javascript { "synchronization": { "fieldUpdates": { "MyCompany.MyCustomField": { "value": "Default 1", "update": "onCreate" }, "MyCompany.OtherCustomField": { "value": "Default 2", "update": "onCreate" } } }, } ``` ### customFieldUpdates Enables updating test case fields that are normally not changed by SpecSync. See [Customization: Update custom Test Case fields on push](/specsync/features/push-features/customization-update-custom-test-case-fields-on-push.md) for details. | Setting | Description | Default | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `customFieldUpdates/enabled` | Enables the customization. | `false` | | `customFieldUpdates/updates` | A list of key-value pair, where the key is the canonical name of the field to be updated (e.g. `System.Description`) and the value is the template to be used to update the field. The template can contain placeholders listed in the [reference](/specsync/reference/configuration/configuration-synchronization/configuration-synchronization-fieldupdates.md#update-placeholders). | mandatory | The `customFieldUpdates` customization setting is a shortcut for configuring the [`synchronization/fieldUpdates` section](https://github.com/specsolutions/specsync-for-tfs-documentation/blob/master/reference/configuration/configuration-synchronization-fieldupdates.md). The example above is equivalent to the following `fieldUpdates` setting: ```javascript { "synchronization": { "fieldUpdates": { "System.Description": { "value": "Synchronized from feature {feature-name}{br}{feature-description}" } } }, } ``` ### ignoreTestCaseSteps Can ignore (leave unchanged) test case steps with a specific prefix. See [Customization: Ignoring marked Test Case steps](/specsync/features/push-features/customization-ignoring-marked-test-case-steps.md) for details. | Setting | Description | Default | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `ignoreTestCaseSteps/enabled` | Enables the customization. | `false` | | `ignoreTestCaseSteps/ignoredPrefixes` | An array of prefixes. The test case steps that start with any of the listed prefixes (case-insensitive) will be ignored by the synchronization. | mandatory | ### ignoreTestCaseTags Can ignore (leave unchanged) test case tags. See [Customization: Ignoring Test Case Tags](/specsync/features/push-features/customization-ignoring-test-case-tags.md) for details. | Setting | Description | Default | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `ignoreTestCaseTags/enabled` | Enables the customization. | `false` | | `ignoreTestCaseTags/tags` | An array of tag specifiers. The tag specifier can be a tag (e.g. `mytag`) or a tag prefix with tailing wildcard (e.g. `ado-tag*` - ignores tags like `ado-tag-important`). The test case tags that match to any of the listed tag specifiers will be ignored by the synchronization. | mandatory | ### ignoreNotSupportedLocalTags Can be used to specify supported tags. SpecSync will only synchronize the supported tags and ignore all others. See [Customization: Ignore non-supported local tags](/specsync/features/push-features/customization-ignore-non-supported-local-tags.md) for details. | Setting | Description | Default | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `ignoreNotSupportedLocalTags/enabled` | Enables the customization. | `false` | | `ignoreNotSupportedLocalTags/supportedTags` | The list of local (scenario) tags that can be synchronized to Azure DevOps. The list can contain full tag names (e.g. `@my-tag1`) or tag name patterns with wildcards (e.g. `@my-tag*`, `@area-*-enabled`). | empty (no tags are supported) | | `ignoreNotSupportedLocalTags/notSupportedTags` | The list of local (scenario) tags that cannot be synchronized to Azure DevOps. This setting cannot be used together with 'supportedTags'. The list can contain full tag names (e.g. `@my-tag1`) or tag name patterns with wildcards (e.g. `@my-tag*`, `@area-*-enabled`). | `supportedTags` setting is used | ### tagTextMapTransformation Can substitute characters or sub-strings in tags when synchronizing to Azure DevOps. E.g. underscores (`_`) in scenario tags can be represented with spaces in Test Case tags. See [Customization: Mapping tags](/specsync/features/push-features/customization-mapping-tags.md) for details. | Setting | Description | Default | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `tagTextMapTransformation/enabled` | Enables the customization. | `false` | | `tagTextMapTransformation/textMap` | Character or substring replacement rules in 'X':'Y' format, where 'X' is a substring in Gherkin tag and 'Y' is a substring in Azure DevOps tag. | mandatory | ### multiSuitePublishTestResults Allows publishing test results to multiple Test Suites. See [Customization: Publishing test results to multiple Test Suites](/specsync/features/test-result-publishing-features/customization-publishing-test-results-to-multiple-test-suite.md) for details. | Setting | Description | Default | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `multiSuitePublishTestResults/enabled` | Enables the customization. | `false` | | `multiSuitePublishTestResults/testPlan` | The name or ID of the test plan to search the test suites in, e.g. `My Plan` or `#567`. | mandatory | | `multiSuitePublishTestResults/publishToAllSuites` | When set to `true` SpecSync will publish the results to all test suites within the specified test plan. | `false` | | `multiSuitePublishTestResults/suites` | The list of test suites to additionally publish the test results to. | empty list | | `multiSuitePublishTestResults/suites[]/name` | The name of the Test Suite | either `name`, `id` or `path` is mandatory | | `multiSuitePublishTestResults/suites[]/id` | The ID of the Test Suite | either `name`, `id` or `path` is mandatory | | `multiSuitePublishTestResults/suites[]/path` | The path of the Test Suite from the root of the Test Plan, separated by `/` (e.g. `Ordering/Card Payment`). | either `name`, `id` or `path` is mandatory | | `multiSuitePublishTestResults/suites[]/testPlan` | The name or ID of the Test Plan to search or create the test suite in, e.g. `My Plan` or `#1234`. (Optional, improves performance) | not specified | | `multiSuitePublishTestResults/includeSubSuites` | When set to `true`, the results will be published not only to the specified suites, but also their direct or indirect sub-suites. | `false` | | `multiSuitePublishTestResults/publishToRequirementBasedTestSuites` | When set to `true`, the results will also be published to the requirement-based suites of the work items linked to the test case. The considered link prefixes can be restricted using the `linkTagPrefixes` setting. | `false` | | `multiSuitePublishTestResults/linkTagPrefixes` | Restricts the work item links to be considered for `publishToRequirementBasedTestSuites`. | all links are considered | ### resetTestCaseState Allows resetting Test Case state after change as a separate work item update based on tags. See [Customization: Reset Test Case state after change](/specsync/features/push-features/customization-reset-test-case-state-after-change.md) for details. | Setting | Description | Default | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | | `resetTestCaseState/enabled` | Enables the customization. | `false` | | `resetTestCaseState/state` | A state value (e.g. `Ready`) to set test case state to after updating a test case as a separate update. | mandatory | | `resetTestCaseState/condition` | A [local test case condition](/specsync/features/general-features/local-test-case-conditions.md) of scenarios that should be included for state change (e.g. `@ready`, `not @inprogress`). | all scenarios included for state change | ### requirementSynchronization Synchronizes requirement source documents (e.g. feature files) to Azure DevOps work items and optionally links nearby scenarios to those requirements. See [Customization: Requirement Synchronization](/specsync/features/push-features/customization-requirement-synchronization.md) for details. | Setting | Description | Default | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `requirementSynchronization/enabled` | Enables the customization. | `false` | | `requirementSynchronization/requirements[]/targetType` | Work item type created for the requirement (e.g. `User Story`). | mandatory | | `requirementSynchronization/requirements[]/condition` | Filter that selects requirement sources (for example `$sourceFile ~ **/*.requirement.feature`). | mandatory | | `requirementSynchronization/requirements[]/tagPrefix` | Tag prefix used to store the requirement ID in the source (e.g. `@req-id:1234`). | mandatory | | `requirementSynchronization/requirements[]/source` | Source node to synchronize as requirement: `Feature` or `Rule`. | `Feature` | | `requirementSynchronization/requirements[]/acceptanceCriteriaSeparator` | Separator text in the description that splits acceptance criteria from the main description. | not parsed, but the entire description is used | | `requirementSynchronization/requirements[]/linkFolderTests` | Automatically link scenarios in the same folder (and sub-folders) as the requirement to the requirement work item. | `false` | | `requirementSynchronization/requirements[]/linkContainerTests` | Automatically link scenarios in the same source document to the requirement work item. | `false` | | `requirementSynchronization/requirements[]/branchTagPrefix` | Branch-specific tag prefix used together with `customizations/branchTag` when synchronizing on feature branches. | not specified | | `requirementSynchronization/requirements[]/links` | Optional link rules (same structure as `synchronization/links`) to control how tags on the requirement document create links to other work items. | no extra links | | `requirementSynchronization/requirements[]/fieldUpdates` | Field update rules applied to the requirement work item (same syntax as `synchronization/fieldUpdates`). | none | | `requirementSynchronization/requirements[]/linkOnChange/enabled` | Enables linking changed requirements to another work item or pull request. | `false` | | `requirementSynchronization/requirements[]/linkOnChange/links` | Link definitions used when `linkOnChange` is enabled (same structure as `customizations/linkOnChange/links`). | mandatory when `linkOnChange/enabled` is `true` | ### addTestCasesToSuites {% hint style="warning" %} Deprecated: `addTestCasesToSuites` has been replaced by `hierarchies`. Please use the [hierarchies configuration](/specsync/features/common-synchronization-features/synchronizing-test-case-hierarchies.md) for new setups. You can automatically migrate your existing configuration by running the [`specsync upgrade` command](/specsync/features/general-features/configuration-wizards.md#upgrade-wizard). The legacy *Add Test Cases to Suites* customization remains supported for backward compatibility but will be removed in a future major release. {% endhint %} Allows including the synchronized Test Cases into various static Test Suites based on conditions. See [Customization: Add Test Cases to Suites](/specsync/features/push-features/customization-add-test-cases-to-suites.md) for details. | Setting | Description | Default | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `addTestCasesToSuites/enabled` | Enables the customization. | `false` | | `addTestCasesToSuites/testPlan` | The name or ID of the default Test Plan to search or create the test suites in. Can be overridden for specific suites. E.g. `My Plan` or `#1234`. | all test plans are scanned through | | `addTestCasesToSuites/testSuites[]/name` | The name of the Test Suite | either `name`, `id` or `path` is mandatory | | `addTestCasesToSuites/testSuites[]/id` | The ID of the Test Suite | either `name`, `id` or `path` is mandatory | | `addTestCasesToSuites/testSuites[]/path` | The path of the Test Suite from the root of the Test Plan, separated by `/` (e.g. `Ordering/Card Payment`). | either `name`, `id` or `path` is mandatory | | `addTestCasesToSuites/testSuites[]/testPlan` | The name or ID of the Test Plan to search or create the test suite in, e.g. `My Plan` or `#1234`. (Optional, improves performance) | not specified | | `addTestCasesToSuites/testSuites[]/condition` | A [local test case condition](/specsync/features/general-features/local-test-case-conditions.md) of scenarios for which the linked Test Case should be included in the Suite (e.g. `@ready`, `not @inprogress`). | all scenarios are considered | ### branchTag Supports synchronization of scenarios on feature branches. See [Customization: Synchronizing scenarios from feature branches](/specsync/features/push-features/customization-support-synchronizing-scenarios-from-a-branch.md) for details. | Setting | Description | Default | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `branchTag/enabled` | Enables the customization. | `false` | | `branchTag/prefix` | The tag prefix to be used for linking scenarios that are updated on a branch. E.g. the prefix `tc.mybranch` will generate tags, like `@tc.mybranch:1234`. | mandatory | ### linkOnChange Allows linking changed Test Cases to a work item or pull request, related to the change. See [Customization: Automatically link changed Test Cases](/specsync/features/push-features/customization-automatically-link-changed-test-cases.md) for details. | Setting | Description | Default | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | | `linkOnChange/enabled` | Enables the customization. | `false` | | `linkOnChange/links[]/targetId` | The ID of the work item or pull request to link the Test Case to. Placeholders, like `{env:ENVIRONMENT_VARIABLE}` can be used. | mandatory | | `linkOnChange/links[]/targetType` | The type of the Azure DevOps work item the link refers to. It is verified at the time the link is established. | can link to any work item type | | `linkOnChange/links[]/relationship` | Specify the relationship for the created link. E.g. specifying `Parent` means that the linked work item will be the parent of the test case work item. For linking Pull Requests it has to be set to `Pull Request` and `GitHub Pull Request` for GitHub Pull Requests (see details in our [guide](/specsync/important-concepts/how-to-link-github-pull-requests.md#linking-github-pull-requests-when-the-test-case-changes)). | `Tests` | | `linkOnChange/links[]/linkTemplate` | Specifies the HTTP link template of the related artifact (for `GitHub Pull Request` relationship). The link template can use the specified value using the `{id}` placeholder. | no template used | ### synchronizeLinkedResourceTitles Allows synchronizing linked artifact (work item) titles back to the local test case tags in `@story:123;This_is_the_story_title` format. See [Customization: Synchronize linked resource titles](/specsync/features/push-features/customization-sync-linked-artifact-titles.md) for details. | Setting | Description | Default | | ------------------------------------------------- | ----------------------------------------------- | --------- | | `synchronizeLinkedResourceTitles/enabled` | Enables the customization. | `false` | | `synchronizeLinkedResourceTitles/linkTagPrefixes` | Specifies the work item links to be considered. | mandatory | ### doNotSynchronizeTitle Skips synchronizing the Test Case title field (`System.Title`). See [Customization: Do not synchronize title](/specsync/features/push-features/customization-do-not-synchronize-title.md) for details. | Setting | Description | Default | | ------------------------------- | -------------------------- | ------- | | `doNotSynchronizeTitle/enabled` | Enables the customization. | `false` | {% content-ref url="/pages/-LVwFCLiKB3ACJLwVZGP" %} [Configuration reference](/specsync/reference/configuration.md) {% endcontent-ref %} --- # 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/reference/configuration/configuration-customizations.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.