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 need 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

Required configuration for the import

Your field map requires to include the following configuration:

"entityType": "person", “group” or “both”
"preprocessor": "phoenixGenericTags"
"skipRemoveTagsFromEntity": false
"removeExistingEntityTags": true
"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": true,
  "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
}