Filtering work item tag proposals by using value sets
You can now filter the list of work item tags that are presented to users when editing work items. By default, the list of tag proposals that are displayed in the various Engineering Workflow Manager (EWM) work item user interfaces is the collection of all saved work item tags. If a tag is defined in one or more work items, that tag is included in the default list of tag proposals. Beginning with EWM 7.0.1, you can associate a value-set-provider script with Tags attributes to customize the list of proposals that are displayed when you add or modify work item tags.
The following section provides example scripts to demonstrate potential ways to use a tags value-set-provider. The scripts were created after creating a new work item with the following tags: bill_tag1, denylist1, denylist2, deb_tag1, ewm_701, rtc_10, allowlist1
Exclude saved tags from the tag proposals list
Over time, EWM projects might accumulate tags that are not relevant for continued usage. You can create a value-set-provider script to filter undesired tags from the returned list. You can use a tags denylist to exclude specific tags or exclude tags that match specified patterns.
The following value-set-provider script returns a filtered collection of tag names that excludes the tags in the denylistTags array.
Filter by using tag names
dojo.provide("com.example.tags.valueSetProvider.denyListTags");
(function() {
// Array of tags that should be excluded from returned tag proposals
var denylistTags = ["denylist1", "denylist2", "rtc_10" ];
dojo.declare("com.example.tags.valueSetProvider.denyListTags", null, {
getValueSet: function(attributeId, workItem, configuration) {
var result;
if (configuration) {
var tags = configuration.getWorkItemTags(attributeId);
result = dojo.filter(tags, function(tag){
var foundMatch = false;
denylistTags.forEach(function(element) {
foundMatch = foundMatch | element == tag;
});
return !foundMatch;
});
}
return result;
}
});
})();Result:
bill_tag1, deb_tag1, ewm_701, allowlist1
Filter by using tag name patterns
The following value-set-provider script returns a filtered collection of tag names that excludes the tags that match the regular expression patterns in the denylistPatterns array. By using patterns you can enable filtering of multiple tags that use a similar naming convention.
dojo.provide("com.example.tags.valueSetProvider.denyListPatterns");
(function() {
// Exclude tags that match any of these regex patterns.
var denylistPatterns = [ /^rtc_/ , /^deb_/, /denylist/ ];
dojo.declare("com.example.tags.valueSetProvider.denyListPatterns", null, {
getValueSet: function(attributeId, workItem, configuration) {
var result;
if (configuration) {
var tags = configuration.getWorkItemTags(attributeId);
result = dojo.filter(tags, function(tag){
var foundMatch = false;
denylistPatterns.forEach(function(element) {
foundMatch = foundMatch | element.test(tag);
});
return !foundMatch;
});
}
return result;
}
});
})();Result:
bill_tag1, ewm_701, allowlist1
Include only items from an allowlist in the tag proposals list
To limit the size of the returned tag proposals list, you might want to specify a collection of tags or tag patterns for inclusion. The next value-set-provider script returns an array of tags that includes only tags from the allowlist that are also associated with work items in the Project Area.
dojo.provide("com.example.tags.valueSetProvider.allowListTags");
(function() {
// Array of tags that should be included in tag proposals list if already saved in a work item
var allowlistTags = ["allowlist1", "allowlist2" ];
dojo.declare("com.example.tags.valueSetProvider.allowListTags", null, {
getValueSet: function(attributeId, workItem, configuration) {
var result;
if (configuration) {
var tags = configuration.getWorkItemTags(attributeId);
result = dojo.filter(tags, function(tag){
var foundMatch = false;
allowlistTags.forEach(function(element) {
foundMatch = foundMatch | element == tag;
});
return foundMatch;
});
return result;
}
}});
})();
Result:
allowlist1
Include a default collection of tags in the tag proposals list
For new Project Areas, it might be useful to return a list of default tags. A value-set-provider script can be coded to always return a collection of default tags even for cases when those tags are not yet associated with any work items. The list of defaults can be returned, instead of or in addition to, the previously saved tags for the Project Area.
Include a fixed collection of tags
The following value-set-provider script always returns a fixed array of tag names without considering previously saved tags.
dojo.provide("com.example.tags.valueSetProvider.defaultTags");
(function() {
// Array of tags that are returned as tag proposals. Only the default tags are returned
var defaultTags = ["allowlist1", "allowlist2" ];
dojo.declare("com.example.tags.valueSetProvider.defaultTags", null, {
getValueSet: function(attributeId, workItem, configuration) {
return defaultTags;
}
});
})();
Result:
allowlist1, allowlist2
Include a merged collection of tags
The next value-set-provider script returns an array of tag names that combines the array of default tag names with the collection of previously saved tags.
dojo.provide("com.example.tags.valueSetProvider.defaultTagsMerged");
(function() {
// Array of tags that are returned as tag proposals. The default tags are merged with previously saved tags
var defaultTags = ["default1", "default2", "allowlist1" ];
dojo.declare("com.example.tags.valueSetProvider.defaultTagsMerged", null, {
getValueSet: function(attributeId, workItem, configuration) {
var tags = configuration.getWorkItemTags(attributeId);
var result = tags.slice();
defaultTags.forEach(function(defaultTag) {
if (dojo.indexOf(tags, defaultTag) < 0) {
result.push(defaultTag);
}
});
return result;
}
});
})();
Result:
bill_tag1, denylist1, denylist2, deb_tag1, default1, default2, ewm_701, rtc_10, allowlist1
The example scripts provide simple ideas for using value-set-providers to customize tag proposals. You can introduce more specialized customization to address the requirement of filtering tags in your Project Area.
For more information about value sets, see Customization of Work Items in Rational Team Concert.
About the author
Bryan Hogan is a developer on the Engineering Workflow Management – Tracking and Planning team.
<edited 2023-04-11 by IBM to update terminology>
© Copyright IBM Corporation 2020