Creating Tags

Problem

You want to organize content using tags.

Solution

Create tags, which can then be assigned to content items (see Assigning tags).

Warning

You must have administrator privileges to create tags.

First, create a tag category.

Tip

A tag created without a parent reference is considered a tag category. Tag categories serve as the top-level category for organizing content. We cannot directly assign a tag category to content. Instead, we can use a tag category as the parent for an individual tag. This approach allows for grouping tags that are related together.

Python
R

from posit import connect

TAG_CATEGORY_NAME = "Departments"

client = connect.Client()
response = client.post("/v1/tags", json={
    "name": "Departments",
})

departments = response.json()

The departments object contains additional information about the tag category, including the id field. We will use the id field to create a tag in the next step.

>>> import polars as pl
>>> pl.DataFrame(tag_category)
shape: (1, 5)
┌─────┬─────────────┬───────────┬──────────────────────┬──────────────────────┐
│ id  ┆ name        ┆ parent_id ┆ created_time         ┆ updated_time         │
│ --- ┆ ---         ┆ ---       ┆ ---                  ┆ ---                  │
│ str ┆ str         ┆ null      ┆ str                  ┆ str                  │
╞═════╪═════════════╪═══════════╪══════════════════════╪══════════════════════╡
│ 100 ┆ Departments ┆ null      ┆ 2024-06-20T14:25:20Z ┆ 2024-06-20T14:25:20Z │
└─────┴─────────────┴───────────┴──────────────────────┴──────────────────────┘

library(connectapi)

TAG_CATEGORY_NAME = "Departments"

client <- connect()
create_tag(client, "TAG_CATEGORY_NAME")

Then get the tag information using the get_tags function.

tags <- get_tags(client)
departments <- tags$Departments

We can print the departments object to view the tag tree.

> departments
Posit Connect Tag Tree (filtered)
└── Departments

Next, create a tag and assign it to the tag category.

Tip

See Viewing Tag Information for information on obtaining the id field for an existing tag.

Tip

You can repeat the following example multiple times to create sub-categories of an arbitrary depth. Try creating another tag named “Human Resources” with the parent “Administrative”.

Python
R


PARENT_TAG_ID = departments['id']
TAG_NAME = "Administrative"

res = client.post("/v1/tags", json={
    "name": TAG_NAME,
    "parent_id": PARENT_TAG_ID
})

administrative = response.json()

The administrative object contains a unique identifier (id) and and a parent_id, which is a reference to the parent via the provided PARENT_TAG_ID.

>>> pl.DataFrame(administrative)
shape: (1, 5)
┌─────┬────────────────┬───────────┬──────────────────────┬──────────────────────┐
│ id  ┆ name           ┆ parent_id ┆ created_time         ┆ updated_time         │
│ --- ┆ ---            ┆ ---       ┆ ---                  ┆ ---                  │
│ str ┆ str            ┆ str       ┆ str                  ┆ str                  │
╞═════╪════════════════╪═══════════╪══════════════════════╪══════════════════════╡
│ 200 ┆ Administrative ┆ 100       ┆ 2024-06-20T14:27:22Z ┆ 2024-06-20T14:27:22Z │
└─────┴────────────────┴───────────┴──────────────────────┴──────────────────────┘

We use the parent argument to assign the new tag to the departments tag category.

TAG_NAME = "Administrative"
create_tag(client, name = TAG_NAME, parent = departments)

Get the tag information again using the get_tags function to view the updated tag tree.

> tags <- get_tags(client)
> tags$Departments
Posit Connect Tag Tree (filtered)
Departments
└── Administrative
> tags$Departments$Administrative
Posit Connect Tag Tree (filtered)
└── Administrative

Next, see Assigning Tags to learn how to assign a tag to content.

Problem

Solution

See also