Tags

Instructors can create course tags and assign them to students. Tags are used in features like activity subsetting or groups.

A tag belongs to a single course but a course can have multiple tags. Tags and students are a many-to-many relationship.

Querying

Course tags

Course tags can be listed by using the Course.tags field. This returns a list of Tag models that contain information like label, color or the assigned students. For more details, check out the Tag model in the API Reference.

The Tag.students field is a GraphQL connection. Read how to paginate a connection in the dedicated guide.

Query

{
  course(id: "00000000-5945-95c7-65fc-a9747b200320") {
    tags {
      label
      color
      students {
        edges {
          node {
            name
            email
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "course": {
      "tags": [
        {
          "label": "Stark",
          "color": "#EB5757FF",
          "students": {
            "edges": [
              {
                "node": {
                  "name": "Sansa Stark",
                  "email": "[email protected]"
                }
              },
              {
                "node": {
                  "name": "Ned Stark",
                  "email": "[email protected]"
                }
              }
            ]
          }
        },
        {
          "label": "Lannister",
          "color": "#2F80EDFF",
          "students": {
            "edges": [
              {
                "node": {
                  "name": "Jaime Lannister",
                  "email": "[email protected]"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Participant tags

Tags can also be queried from the Participant model. The Participant.tags field lists all the tags the student was assigned within the course.

Tags can only be applied to students so other participant types will have a null value when querying for the Participant.tags field. For students, the API will always return a list.

Query

{
  course(id: "00000000-5945-95c7-65fc-a9747b200320") {
    participants {
      edges {
        node {
          user {
            name
          }
          participantType
          tags {
            label
            color
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "course": {
      "participants": {
        "edges": [
          {
            "node": {
              "user": {
                "name": "Ned Stark"
              },
              "participantType": "Owner",
              "tags": null
            }
          },
          {
            "node": {
              "user": {
                "name": "Arya Stark"
              },
              "participantType": "Student",
              "tags": [
                {
                  "label": "House Stark",
                  "color": "#EB5757FF"
                }
              ]
            }
          },
          {
            "node": {
              "user": {
                "name": "Bran Stark"
              },
              "participantType": "Student",
              "tags": [
                {
                  "label": "House Stark",
                  "color": "#EB5757FF"
                },
                {
                  "label": "King of the Six Kingdoms",
                  "color": "#AA1212FF"
                }
              ]
            }          
          }
        ]
      }
    }
  }
}

Mutations

Create tag

You can create tags via the createTag mutation

The tag color should be in #RRGGBBAA format

Mutation

mutation {
  createTag(
    courseId: "00000000-5945-95c7-65fc-a9747b200320",
    label: "Westeros",
    color: "#A32533AB"
  ) {
    tag {
      label
			color
    }
  }
}

Response

{
  "data": {
    "createTag": {
      "tag": {
        "label": "Westeros",
        "color": "#112233FF"
      }
    }
  }
}

Add students to tag

You can add students to a tag via the addStudentsToTag mutation. The mutation returns the updated tag so details like the complete list of students can be fetched. The studentIds are Participant.id values that can be fetched from the Course.participants connection.

Based on the tag id, only student ids from tag's course are accepted

Mutation

mutation {
  addStudentsToTag(
    tagId: "de1bf57b-aa1d-4736-987e-dc0c4d3620d5", 
    studentIds: ["21b26c40-83ea-43a2-9c4b-f88722e0b9be"]
  ) {
    tag {
      label
      students {
        edges {
          node {
            name
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "addStudentsToTag": {
      "tag": {
        "label": "Westeros",
        "students": {
          "edges": [
            {
              "node": {
                "name": "Tyrion Lannister"
              }
            },
            {
              "node": {
                "name": "Ser Jorah"
              }
            },
            {
              "node": {
                "name": "Hodor"
              }
            }
          ]
        }
      }
    }
  }
}