Thanks to Ajit @alondhe for supporting the initiative

Notes:

• the new functionality is available for Concept Sets, Cohort Definitions, Cohort Characterizations, Incidence Rates, Cohort Pathways ("Assets") and might be added for the other entities in the future
• as there is no UI designed to create Tags / Tag Groups a database script should be prepared to define an hierarchy

Data Model

Tag is an entity which encompasses the following attributes:

• ID
• label
• description
• created by
• created at
• modified by
• modified at
• origin (predefined, free-form / manual entry, external system)
• tag group IDs - a list of Tag Groups into which the given Tag belongs to - for the initial implementation there will be only one Tag Group specified for each Tag
• protected flag - if specified this Tag can be assigned for an Asset only by user roles with a specific permission assigned
• active / inactive flag - might be used for soft deletion purposes, when Tags were deleted but still should be present for auditing purposes (ineffective for the initial implementation)

Tags with the same group ID form a Tag Group which has the following attributes:

• ID
• label
• description
• created by
• created at
• modified by
• modified at
• parent group ID - in case of necessity Tag Groups can be nested; there are no limitations how deep are the nested levels (for the initial implementation the nested level is 1); if the value is omitted (NULL or a specific constant to be defined) it is a top-level Tag Group
• maximum number of assigned Tags - when specified it defines the threshold not to exceed while tagging for the given Tag Group (for the initial implementation it should be set to 1 - so that it should not be allowed to assign two Tags from the same Tag Group on a specific Asset)
• mandatory flag - when specified a validation business rule is effective for the given Tag Group so that an error message is displayed in the “Messages” tab if none of the Tags from the given Tag Group were assigned
• active / inactive flag - see “Tag - active / inactive flag“
• display in listings flag - by default it should be “false“, if set to “true“ the Tag Group column will be present when an Asset listing is displayed
• allow tags creation flag - when specified for the given Tag Group it is allowed to have new Tags created
• icon - the icon name to be used, if not specified the default icon should be used
• color - color code in hex format (#A52A2A, for example), if not specified the default color should be used

Asset Form UI

Each Asset's form to be extended with:

• the “Tags“ button in the Toolbar next to “Save“, “Close“, “Clone“, … buttons, after clicking on which a popup window is displayed which look and feel is similar to the “Configure access“ functionality
  -- the popup window visual area is split up into the following blocks
  --- “Tag Groups“ - a paginated tabular view with the text filtering capability displays Tag Groups defined, each row has a description and an action control “Show tags“ to display Tags which belong to a particular Tag Group
  --- “Tags“ (not visible all the times) - a paginated tabular view with the text filtering capability displays Tags which belong to a particular Tag Group with a possibility to assign/unassign them to an Asset
  ---- if a Tag is assigned the appropriate row is decorated with the tag icon
  ---- there is also information about when and by whom a Tag has been created in addition to the Tag’s description
  ---- when a user clicks on the “Assign“ link the corresponding Tag is assigned for the given Asset
  ---- when a user clicks on the “Unassign“ link the corresponding Tag is unassigned from the given Asset
  ---- when Tags are assigned there is an additional validation logic not allowing to exceed the maximum number of assigned Tags from a specific Tag Group, if such limitation reached the following message “The maximum number of assigned tags in the tag group "" is . The tag "" will be unassigned. Proceed?“ is displayed with a possibility to proceed or cancel
  ---- an area to create free-form Tags with a possibility to choose a Tag Group into which the newly created Tag should be added
• additionally a new block next to the Asset’s title to be added where currently assigned Tags are visually available all the times. A Tag Group of each Tag is displayed via a tooltip when a Tag control is hovered. For long-text Tags there will be a limitation - 20 symbols after which “…“ are displayed, the whole Tag name will be visible in the tooltip specified earlier

Assets Listings Extensions

Additionally to the existing filtering groups (“Created“, “Updated“, “Author“, “Designs“, …) in the list views of Assets the Tag Groups should be added to allow grouping visualization and filtering capabilities by Tags / Tag Groups. Existing UI controls should be used to achieve that

The “Untagged“ item to be added for each Tag Group so that a user will be able to easily identify Assets which are not tagged with any Tag from the given Tag Group

By default each listing will be extended with Tag Group columns being configured with the “display in listings“ attribute. The existing table functionality allows adding/hiding table columns based on the user needs

API

A common method for creating, updating, deleting and fetching Tags is placed in TagController under the ”/tag/” context

Methods for assigning Tags are placed in the respective Asset controllers, four methods for each:

• POST /{assetType}/{id}/tag/ - assign a common Tag
• DELETE /{assetType}/{id}/tag/ - unassign a common Tag
• POST /{assetType}/{id}/protectedtag/ - assign a protected Tag
• DELETE /{assetType}/{id}/protectedtag/ - unassign a protected Tag

An attempt to assign/unassign a protected Tag via "/tag/" methods instead of the "protectedtag" ones results in an error 403 Forbidden. By default, only the "admin" role has permissions to call "protectedtag" methods

Creating tags

For now, tags structure can only be created directly in DB. Examples:

-- Schema name used for examples: ohdsi

-- Tag Groups and Tags stored in 'tag' table
-- Hierarchy between Tag Groups and Tags is defined in 'tag_group' table

-- Create Tag Group
-- name
-- show_group - defines if the tag group column is visible (by default) in assets table on the UI
-- icon - icon font-awesome class
-- color - tag color
-- multi_selection - if true, multiple tags of this group can be assigned to an asset. otherwise - only one
-- mandatory - if true, a warning will appear in 'warnings' tab, if no tags of this group are assigned to asset
-- allow_custom - allows creation of custom tags in this group
-- description
INSERT INTO ohdsi.tag (name, show_group, icon, color, multi_selection, mandatory, allow_custom, description)
VALUES ('Status', true, 'fa fa-bullseye' , '#cbffcf', false, true, false, 'description');

-- Create Tag
INSERT INTO ohdsi.tag (name, description)
VALUES ('New research', 'New research tag description');

-- tag will inherit icon and color from it's group, or you can override them for a specific tag.
-- permission_protected flag is for tags that can only be assigned by the role with these permissions (admin role by default):
--     'cohortdefinition:*:protectedtag:post',
--     'cohortdefinition:*:protectedtag:*:delete',
--     'conceptset:*:protectedtag:post',
--     'conceptset:*:protectedtag:*:delete',
--     'cohort-characterization:*:protectedtag:post',
--     'cohort-characterization:*:protectedtag:*:delete',
--     'ir:*:protectedtag:post',
--     'ir:*:protectedtag:*:delete',
--     'pathway-analysis:*:protectedtag:post',
--     'pathway-analysis:*:protectedtag:*:delete'
INSERT INTO ohdsi.tag (name, color, description, permission_protected)
VALUES ('Protected tag', '#efdd0b','Protected tag description', true);

-- Define hierarchy
INSERT INTO ohdsi.tag_group (group_id, tag_id)
SELECT tg.id, t.id
FROM ohdsi.tag tg, ohdsi.tag t
WHERE tg.name = 'Status' and t.name = 'New research';

INSERT INTO ohdsi.tag_group (group_id, tag_id)
SELECT tg.id, t.id
FROM ohdsi.tag tg, ohdsi.tag t
WHERE tg.name = 'Status' and t.name = 'Protected tag';