Learn about how to work with tags.
Tags are used to notify users based on their subscriptions. With tags, you will know the latest update to any forum, blog, or Knowledge Base (KB).
In this use case, you will learn how to work with tags and perform the following actions:
- Create a forum topic with tags
- Update a tag of a forum topic
- Add a tag to a message
- Remove the tag from the message
- Retrieve the messages associated with the tag
- Delete the tags on a node
- Replace the tags on a node
Requirements
You must have the Tags option enabled for your user account. By default, Admin and Moderators have this option enabled for their account.
Basic Steps
- Make sure that your account has the Tags option enabled.
- Generate a session key using:
with the member’s credentials.POST/authentication/sessions/login - Create a POST, GET, or PUT method to either add, retrieve, update, or replace a tag to a message through your community domain URL:
https://[COMMUNITY DOMAIN]/api/2.1/graphql - Verify that the tag action is performed.
Examples
Create a Forum Topic with Tags
In this example, we will create a forum topic with tags.
Example Request
The example request contains both the mutation and the query to create a forum topic with tags.
mutation CreateForumTopicWithTags($createInput: CreateForumTopicInput!) {
createForumTopic(createInput: $createInput) {
result {
id
tags {
edges {
cursor
node {
text
time
}
}
}
}
}
}
The mutation here initiates a CreateForumTopicWithTags function using information passed through GraphQL variables. Here is an example of the variables used to create a forum topic with tags:
{
"createInput": {
"board": {
"id": "board:<BOARD ID>"
},
"subject": "Horticulture",
"tags": {
"items": [
{"text": "tag20"},
{"text": "tag21"},
{"text": "tag31"},
{"text": "tag41"}
]
}
}
}
Example Response
Here is the response to the above request.
{
"data": {
"createForumTopic": {
"result": {
"id": "message:<MESSAGE ID>",
"tags": {
"edges": [
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDE",
"node": {
"text": "tag20",
"time": "2023-05-18T20:14:11.987-07:00"
}
},
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDI",
"node": {
"text": "tag21",
"time": "2023-05-18T20:14:11.987-07:00"
}
},
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDM",
"node": {
"text": "tag31",
"time": "2023-05-18T20:14:11.987-07:00"
}
},
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDQ",
"node": {
"text": "tag41",
"time": "2023-05-18T20:14:11.987-07:00"
}
}
]
}
}
}
}
}
Update a Tag of a Forum Topic
In this example, we will update the forum topic tags.
Example Request
The example request contains both the mutation and the query to update the forum topic with the tags.
mutation UpdateForumTopicWithTags($updateInput: UpdateForumTopicInput!, $id: ID!) {
updateForumTopic(updateInput: $updateInput, id: $id) {
result {
id
tags {
edges {
cursor
node {
text
time
}
}
}
}
}
}
The mutation here initiates a UpdateForumTopicWithTags function using information passed through GraphQL variables. Here is an example of the variables used to update a forum topic with tags:
{
"id": "message:<MESSAGE ID>",
"updateInput": {
"tags": {
"items": [
{"text": "updatetag"},
{"text": "updatetag2"}
]
}
}
}
Example Response
Here is the response to the example request.
{
"data": {
"updateForumTopic": {
"result": {
"id": "message:<MESSAGE ID>",
"tags": {
"edges": [
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDE",
"node": {
"text": "updatetag",
"time": "2023-05-18T20:21:58.733-07:00"
}
},
{
"cursor": "MjMuNnwyLjF8b3wyNXxfTlZffDI",
"node": {
"text": "updatetag2",
"time": "2023-05-18T20:21:58.733-07:00"
}
}
]
}
}
}
}
}
Add Tag to a Message
In this example, we will add a tag to an already-created message.
You must have the Add tags to any post permission to add a tag to a message.
Example Request
The example request contains both the mutation and variables to add a tag to a message.
mutation AddTagToMessage($messageId: ID!, $text: String!) {
addTagToMessage(messageId: $messageId, text: $text) {
result {
id
}
errors {
__typename
}
}
}
The mutation here initiates an AddTagToMessage function using information passed through GraphQL variables. Here is an example of the variables used to add a tag to a message:
{
"messageId": "message:<MESSAGE ID>",
"text": "addtags"
}
Example Response
Here is the response to the above request.
{
"data": {
"addTagToMessage": {
"result": {
"id": "message:<MESSAGE ID>"
},
"errors": null
}
}
}
Remove the Tag from a Message
In this example, we will remove a tag from a message.
Example Request
The example request contains both the mutation and variables to remove a tag from a message.
mutation removeTagFromMessage($messageId: ID!, $text: String!) {
removeTagfromMessage(messageId: $messageId, text: $text) {
result {
id
}
errors {
__typename
}
}
}
The mutation here initiates a RemoveTagFromMessage function using information passed through GraphQL variables. Here is an example of the variables used to remove a tag from a message:
{
"messageId": "message:<MESSAGE ID>",
"text": "addtags"
}
Example Response
Below is the response to the above request.
{
"data": {
"removeTagFromMessage": {
"result": {
"id": "message:<MESSAGE ID>"
},
"errors": null
}
}
}
Retrieve the Messages associated with the Tag
In this example, we will retrieve the messages which are associated with the tag.
Example Request
The example request contains the query and the variables to retrieve the messages related to the tag.
query getMessage($MessageConstraints:MessageConstraints){
messages(constraints:$MessageConstraints){
edges{
node{
id
kudos {
edges {
node {
id
}
}
}
}
}
totalCount
}
}
The variables contain the criteria to retrieve the messages for the tag.
{
"MessageConstraints": {
"tagsText": {
"eq": "addtag"
}
}
}
Example Response
Below is the response to the above request.
{
"data": {
"messages": {
"edges": [
{
"node": {
"id": "message:<MESSAGE ID>",
"kudos": {
"edges": []
}
}
},
{
"node": {
"id": "message:<MESSAGE ID>",
"kudos": {
"edges": []
}
}
}
],
"totalCount": 2
}
}
}
Delete the Tags from messages in a Node
In this example, we will delete a tag from messages in a node.
Note: Users who have Manage tags permission can delete the tag.
Example Request
In this example, as an administrator, I will delete the tag from messages present in a board.
The example request contains both the mutation and variables to delete the tag from messages in a board node.
mutation deleteTagsOnNode ($updateTagInput: UpdateTagInput, $nodeId: ID, $tag: String!) {
deleteTagsOnNodeForUser(updateTagInput: $updateTagInput, nodeId: $nodeId, tag: $tag) {
errors {
message
}
}
}
The mutation here initiates a deleteTagsOnNode function using information passed through GraphQL variables.
Using this mutation, the tag added by a user to messages can also be deleted.
Here is an example:
ATLAS
Comments