connectapi Tags
In connectapi: Utilities for Interacting with the 'Posit Connect' Server API

knitr::opts_chunk$set(echo = TRUE)
library(connectapi)
client <- connect(prefix = "TEST_1")
options("connectapi_disable_experimental_warnings" = TRUE)

Getting Started

To understand how tags work with connectapi, you must first understand tags in RStudio Connect.

Tags in RStudio Connect consist of multiple "tag trees," each with a "Category" as its parent.
The tag hierarchy / structure is created by administrators
Publishers and administrators can associate any non-Category tag with content
A tag being a member of a "child" tag doe not automatically make it a member of the "parent" tag

As always, get started by defining the CONNECT_SERVER and CONNECT_API_KEY variables, then initialize an API client.

library(connectapi)
client <- connect()

NOTE: This example report will create a few tag hierarchies and then use them. As a result, to use this example verbatim requires admin privileges and will create tags on your server.

Create the Tag Tree(s)

To get started, we will create a tag tree to show how things work. The create_tag() helper allows you to create a singular tag (by specifying its parent, etc.). For our purposes, create_tag_tree() is easier, since it creates the entire tree specified at once.

start_tags <- get_tags(client)
start_tags

# Protect against tags already existing
if ("DemoProject" %in% names(start_tags) || "DemoAudience" %in% names(start_tags))
  stop("ERROR: One of the demo tags already exist for you! Beware lest they be deleted by this demo")

tree_project_1 <- create_tag_tree(client, "DemoProject", "project_1")
tree_project_1

tmp_tags <- get_tags(client)

tree_project_2 <- create_tag(client, name = "project_2", parent = tmp_tags$DemoProject)
tree_project_2

tree_audience_1 <- create_tag_tree(client, "DemoAudience", "Sales")
tree_audience_2 <- create_tag_tree(client, "DemoAudience", "Finance")

get_tags(client)

Content tags

In order to show how tags work, we need some content to work with.

bnd <- bundle_static(system.file("logo.png", package = "connectapi"))

content_1 <- deploy(client, bnd)
content_2 <- deploy(client, bnd)

Set Tags

Content 1 is for project_1 and Sales, so let's set the tags! There are a few ways to do so.

all_tags <- get_tags(client)

set_content_tag_tree(content_1, "DemoProject", "project_1")

set_content_tags(content_1, all_tags$DemoAudience$Sales)

Content 2 is for project_2 and both Audiences (Sales and Finance).

set_content_tags(
  content_2, 
  all_tags$DemoProject$project_2, 
  all_tags$DemoAudience$Sales,
  all_tags$DemoAudience$Finance
  )

See the tags associated with content

In order to see the tags associated with content, use get_content_tags(). The data structure is the same as get_tags(), but the "whole list" is filtered to only the tags that are associated with a piece of content.

c1_tags <- get_content_tags(content_1)
c1_tags

c2_tags <- get_content_tags(content_2)
c2_tags

List all content associated with a tag

Once tags have been defined, you can also search for all of the content associated with a tag.

content_list_by_tag(client, all_tags$DemoAudience$Sales)

content_list_by_tag(client, all_tags$DemoProject$project_1)

content_list_by_tag(client, all_tags$DemoProject)

Cleanup

Now we will clean up the demo tags that we created.

# Protect against tags already existing
if ("DemoProject" %in% names(start_tags) || "DemoAudience" %in% names(start_tags))
  stop("ERROR: One of the demo tags already exist for you! Beware lest they be deleted by this demo")

latest_tags <- get_tags(client)
delete_tag(client, latest_tags$DemoProject)
delete_tag(client, latest_tags$DemoAudience)

# TODO: delete content