Import Tags with Unique Attributes

As outlined in What are tags?, Tags can contain additional data (attributes), which can be uniquely set for each entity-tag (i.e. Tag applied to a person or a team). This is useful if you seek to have common Tag names, but “data” (i.e. attributes) that is unique to the person/team to which a tag is applied.

This pages defines how to load unique entity-tag attributes.

Note: this is a special case of Tags With Attributes use. For more about importing Tags with Attributes, see: Bulk import Tags with attributes (common attributes).

About unique attributes for tags

Enabling attributes for tags

Tags attributes needs to be enabled by a TeamForm consultant via admin devtools, using the workspace feature flags “enableEntityTagAttributes.”

Tags with Unique Attributes to an Entity can then be added via tag type settings (manage tags):

Configuring tags attributes

Tags attributes can be configured from Settings > Manage tags.

Users can then associate values to the attributes when editing tags applied to a group or person. Navigate to a group or person page then select Edit tag.

Interaction Options for Unique Attributes

Optional - The attribute is not required, its value can be edited from the directory
~~Editable~~ - not currently in use
Mandatory - The attribute must be provided when tagging a group or person, can be edited from the directory
Readonly - The attribute value cannot be edited from the directory

Importing tags and their unique attributes

Importing unique attributes along with a tag import can be done using specific pre-processing instruction using the normal integration for tag import.
An example of CSV file and JSON field map is provided below.

JSON Field Map

The following example tags a

Required configuration for the import

Your field map requires to include the following configuration:

"entityType": "person", “group” or “both”
"preprocessor": "phoenixGenericTags"
"skipRemoveTagsFromEntity": false
"removeExistingEntityTags": false
"forceUpdateSameTag": true
"importShadowTag":false

Mapping of the primary key in your CSV file

"headerRowIdentifier"
"idType"
"idColumnName"

Detailed mapping to match your tag attributes

"tagTypes" an array of tag types which individually can contain:
- "tagValueColumnNames" an array of column names that will be concatenated into a tag value using the next identifier "separator" –if creating value from a single column, concatenation and separators are skipped
- "separator" the text to be used when concatenating values from several value column names –ignored if creating value from a single column
- "tagType" the name of the column containing tag type –Will be used as value if the column doesn’t exist
- "entityTagAttributes" an array of tag attributes which individually can contain:
  - "attrValueColumnName"
  - "label"

Sample CSV file

Person ID,Tags,FTE
33947582,Funding source XXX,0.8

Sample JSON Field Map

{
  "entityType": "person",
  "preprocessor": "phoenixGenericTags",
  "skipRemoveTagsFromEntity": false,
  "removeExistingEntityTags": false,
  "forceUpdateSameTag": true,
  "importShadowTag": false,
  
  "headerRowIdentifier": "Person ID",
  "idType": "internalId",
  "idColumnName": "Person ID",
  
  "tagTypes": [
    {
      "tagValueColumnNames": [
        "Tags"
      ],
      "separator": "_"
      "tagType": "FUNDING_SOURCE",
      "entityTagAttributes": [
        {
          "attrValueColumnName": "FTE",
          "label": "FTE"
        }
      ],
    }
  ]
}

Advanced example

Sample advanced JSON Fields Map

Downloadable file

Sample JSON Field Map (in file above)

{
  "entityType": "group",
  "skipRemoveTagsFromEntity": true,
  "preprocessor": "phoenixGenericTags",
  "headerRowIdentifier": "Organization Ref ID",
  "idColumnName": "Organization Ref ID",
  "idType": "externalId",
  "tagTypes": [
    {
      "tagValueColumnNames": ["Employee ID"],
      "separator": "_",
      "tagTypeColumnName": "Role Name",
      "tagTypeNamesMap": {
        "Project Hierarchy Manager": "Group Owner",
        "Project Manager": "Product Owner",
        "Project Hierarchy Performance Lead": "GPL"
      },
      "attributes": {
        "entityTag": [
          {
            "action": "optional",
            "associatedValue": "",
            "defaultValue": "",
            "label": "Country",
            "attrValueColumnName": "Country",
            "type": "text"
          },
          {
            "id": "bcd123",
            "action": "optional",
            "associatedValue": "",
            "defaultValue": "",
            "label": "Group Manager",
            "attrValueColumnName": "Group Manager",
            "type": "person"
          }
        ],
        "others": [
          {
            "action": "optional",
            "associatedValue": ["Agile Group"],
            "label": "Group name",
            "type": "groupType"
          }
        ],
        "values": [
          {
            "action": "optional",
            "associatedValue": "",
            "defaultValue": "",
            "label": "Supervisory Manager",
            "attrValueColumnName": "Manager ID",
            "type": "person"
          },
          {
            "id": "abc123",
            "action": "optional",
            "associatedValue": "",
            "defaultValue": "",
            "label": "Manager group lead",
            "attrValueColumnName": "Manager Group Lead",
            "type": "person"
          }
        ]
      }
    }
  ],
  "importShadowTag": false
}