# 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](/graphql/pagination.md). 

{% 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eduflow.com/guides/tags.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.