# Tags

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

{% hint style="info" %}
A tag belongs to a single course but a course can have multiple tags. \
Tags and students are a many-to-many relationship.
{% endhint %}

## 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](https://graphdoc.eduflow.com/tag.doc.html). 

The `Tag.students` field is a GraphQL connection. Read how to paginate a connection in the [dedicated guide](https://docs.eduflow.com/graphql/pagination). 

{% tabs %}
{% tab title="Query" %}

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

```

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "data": {
    "course": {
      "tags": [
        {
          "label": "Stark",
          "color": "#EB5757FF",
          "students": {
            "edges": [
              {
                "node": {
                  "name": "Sansa Stark",
                  "email": "sansa@example.com"
                }
              },
              {
                "node": {
                  "name": "Ned Stark",
                  "email": "ned@starks.com"
                }
              }
            ]
          }
        },
        {
          "label": "Lannister",
          "color": "#2F80EDFF",
          "students": {
            "edges": [
              {
                "node": {
                  "name": "Jaime Lannister",
                  "email": "jaime@example.com"
                }
              }
            ]
          }
        }
      ]
    }
  }
}
```

{% endtab %}
{% endtabs %}

### 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.

{% tabs %}
{% tab title="Query" %}

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

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "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"
                }
              ]
            }          
          }
        ]
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

## Mutations

### Create tag

You can create tags via the `createTag` mutation

{% hint style="info" %}
The tag color should be in `#RRGGBBAA` format
{% endhint %}

{% tabs %}
{% tab title="Mutation" %}

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

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

### 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.

{% hint style="info" %}
Based on the tag id, only student ids from tag's course are accepted
{% endhint %}

{% tabs %}
{% tab title="Mutation" %}

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

```

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}