Data Feed Guide: Tags

Overview

The list of tags may be created either manually in Student Success & Engagement (SS&E) or via the SIS Import/Person Datafeed. Tags can be assigned to a person in three ways: Automated Tags (assigned by SS&E system), Data-Backed Tags (assigned via SIS Import on personTag datafeed), and Manual Tags (assigned by an SS&E Administrator). This guide covers Data-Backed Tags. For more general information on Tags, see the Tagging section of the help center.

Tags in Implementation

In new implementations, two of these four data-backed tags (or sets of tags) are typically implemented as an example/template. Alternative tags may be considered on a case by case basis to meet project goals. In Design & Build, the System Admin and project team may determine that additional tags are needed, and the Data Lead may need to make adjustments throughout implementation and beyond.

Once the initial tags are implemented, the institution can replicate this process during and after implementation to continue importing additional tags into SS&E.

• Athletics
• Clubs
• Dean's List
• Academic Standing

Tag Related Feeds

The SIS Import Definitions outlines the import requirements for each of the following feeds.

• tag
  • This datafeed is optional as tags can be created in SS&E Admin. It is most useful when many tags are stored in the same table/file in the SIS, or when new tags need to be created dynamically over time (e.g. cohorts, clubs). If only a few tags will be used, it’s easier to create them in SS&E Admin > Tags.
• personTag
  • This datafeed is optional as tags can be assigned using Automated Tag Filters or manually in SS&E Admin.
  • The tagId in this feed must match the tag integration id. This is either the id provided on the tag datafeed, or it is created along with the tag in SS&E. It is called the "Source System Id" on the tag in SS&E.

ER Diagram

Example Scenario

In this example, Olivia Student (0123456) runs track and cross country and should be tagged as an athlete as well as for each individual sport. Jonathan Student (0654321) was on the basketball team last year but is taking the year off.

tag

• SIS.TAG.ATHLETE, Athlete
• SIS.TAG.WTRACK, Women’s Track
• SIS.TAG.WXC, Women’s Cross Country
• SIS.TAG.MBASKETBALL, Men’s Basketball

personTag

• 0123456*SIS.TAG.ATHLETE, 0123456, active=true, SIS.TAG.ATHLETE
• 0123456*SIS.TAG.WTRACK, 0123456, active=true, SIS.TAG.WTRACK
• 0123456*SIS.TAG.WXC, 0123456, active=true, SIS.TAG.WXC
• 0654321*SIS.TAG.ATHLETE, 0654321, active=false, SIS.TAG.ATHLETE
• 0654321*SIS.TAG.MBASKETBALL, 0654321, active=false, SIS.TAG.MBASKETBALL

Tag Removal

If a personTag record might be removed in the future (most are), the personTag record must be imported as active=false. Because of this, it may be necessary to create a personTag record for each person in the data feed and for each tag, setting active=true for only those who should have the tag.

SQL Views/Queries

Because it is often necessary to create a personTag record for each person so that tags can be removed, it may be helpful to create the personTag feed by selecting from the Person list, and joining the tag data onto the person list. This allows for a case statement to set active=true when the person should have the tag, and active=false for everyone else in the person list who should not have it.

CSV Format Examples

When setting up personTag assignments using CSV files, sometimes it’s possible to create the file exactly matching the personTag SIS Import Definitions, but the CSVs can also be set up in different ways depending on how the data is available in the SIS. The Accelerate configuration can then transform the data into the SIS Import format. Examples can be found below. Most tags can fit into Options 1 or 2.

See the five CSV Format Options in the Data-Backed Tags article for more detail. 

Option 1 - person_tag_athletes.csv

Anyone in this file will be tagged with the TAG.ATHLETE tag. Anyone who is not in this file will be marked active=false and the tag will be removed.

Note: include column headers only if your other CSV files use headers.

Option 2 - person_tag_sports.csv

Anyone in this file will be tagged with the corresponding sports team tag. Anyone without a tag association will be marked active=false and the tag will be removed.

Note: include column headers only if your other CSV files use headers.

Option 3 - person_tag_sports.csv

Anyone in this file with a true value will be tagged with the corresponding sports team tag. Anyone with a false value will be marked active=false and the tag will be removed.

Note: include column headers only if your other CSV files use headers.

Option 4 - person_tag_sports.csv

If today is between the start and end dates, the person will be tagged with the corresponding sports team tag. Anyone who is not in this file OR if today is outside the start and end dates will be marked active=false and the tag will be removed.

Note: include column headers only if your other CSV files use headers.

Option 5

See personTag format above.

Accelerate Configuration

When using the CSV Method, the Accelerate configuration must be updated to accept the person_tag.csv files. Here are examples corresponding to the CSV options above:

Option 1

select
  'SIS.TAG.ATHLETE.' || p.COLUMNS[0] as id,
  p.COLUMNS[0] as personId,
  case
    when nullif(pta.COLUMNS[0], '') is not null then 'true'
    else 'false'
  end as active,
  'SIS.TAG.ATHLETE' as tagId
from dfs.root.`person.csv` p
left outer join dfs.root.`person_tag_athletes.csv` pta on p.COLUMNS[0] = pta.COLUMNS[0]

Option 2

select
  concat('SIS.TAG.', t.tagId, '.', p.COLUMNS[0]) as id,
  p.COLUMNS[0] as personId,
  case
    when pts.COLUMNS[0] is not null then 'true'
    else 'false'
  end as active,
  concat('SIS.TAG.', t.tagId) as tagId
from dfs.root.`person.csv` p
cross join (select distinct COLUMNS[1] as tagId from dfs.root.`person_tag_sports.csv`) t
left outer join dfs.root.`person_tag_sports.csv` pts on pts.COLUMNS[0] = p.COLUMNS[0] and pts.COLUMNS[1] = t.tagId

Option 3

select
  concat('SIS.TAG.', t.tagId, '.', p.COLUMNS[0]) as id,
  p.COLUMNS[0] as personId,
  case
    when pts.COLUMNS[1] = 'true' then 'true'
    else 'false'
  end as active,
  concat('SIS.TAG.', t.tagId) as tagId
from dfs.root.`person.csv` p
cross join (select distinct COLUMNS[2] as tagId from dfs.root.`person_tag_sports.csv`) t 
left outer join dfs.root.`person_tag_sports.csv` pts on pts.COLUMNS[0] = p.COLUMNS[0] and pts.COLUMNS[2] = t.tagId

Option 4

select
  concat('SIS.TAG.', t.tagId, '.', p.COLUMNS[0]) as id,
  p.COLUMNS[0] as personId,
  case
    when CURRENT_DATE >= cast(pts.COLUMNS[1] as date)
      and (CURRENT_DATE <= cast(pts.COLUMNS[2] as date) or nullif(pts.COLUMNS[2],'') is null) then 'true'
    else 'false'
  end as active,
  concat('SIS.TAG.', t.tagId) as tagId
from dfs.root.`person.csv` p
cross join (select distinct COLUMNS[3] as tagId from dfs.root.`person_tag_sports.csv`) t
left outer join dfs.root.`person_tag_sports.csv` pts on pts.COLUMNS[0] = p.COLUMNS[0] and pts.COLUMNS[3] = t.tagId

Option 5

select 
  COLUMNS[0] as id,
  COLUMNS[1] as personId,
  COLUMNS[2] as active,
  COLUMNS[3] as tagId
from dfs.root.`person_tag.csv`

Adding Tags After Implementation

• When creating new personTags using SQL Views, ensure that the Accelerate Configuration (SS&E Admin > SIS Integration > Accelerate Configuration) includes the new personTag view name (if a new view was created).
• When creating new personTags using the CSV Method, ensure that the Accelerate Configuration (SS&E Admin > SIS Integration > Accelerate Configuration) includes a query to pull the file.

For Technical Services Assistance with either of these, a Medium Technical Project can be requested from the Watermark Academy.

Troubleshooting

CSV Method Connect2 Errors

Error: UNSUPPORTED_OPERATION ERROR: This query cannot be planned possibly due to either a cartesian join or an inequality join. If a cartesian or inequality join is used intentionally, set the option 'planner.enable_nljoin_for_scalar_only' to false and try again.

Solution: This error occurs when using a query with cross joins. Update Apache Drill settings to allow cross joins:

• On the Connect Server, open a browser and go to http://localhost:8047
• Navigate to the Options tab.
• Search for: planner.enable_nljoin_for_scalar_only
• Change it from true to false.
• Click the Update button next to it to save the change.

Additional Information

Additional resources related to tags in SS&E can be found here.

• Tagging
• Automated Tags
• Data-backed Tags (aka personTag)
• Create a Tag & Manual Tags
• Tags Companion Course