---
title: "Workflows with RT"
author: "Bryce Mecum"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The `rt` package was built to make it easier for our own team to work with RT in an automated fashion.
As a result, most functions in the package have return values suitable for passing into other functions in the `rt` package or functions from other packages.
Notably, functions are [pipeable](https://magrittr.tidyverse.org/reference/pipe.html) when possible.

Below are some example workflows you might use this package for.

## Creating tickets

You can always email your RT installations associated email address to create a ticket but you can also create one programmatically:

```r
rt_ticket_create("General", "me@example.com", "Hey, a quick question...")
```

You could also create a set of tickets from a database dump of some kind, such as an old ticket tracking system.

First, let's create some example data to work with:

```r
old_tickets <- data.frame(
  queue = "General",
  subject = c("I need some help", "about those TPS reports...", "hello!"),
  requestor = c("someone@example.com", "boss@initech.com", "user@example.com"),
  stringsAsFactors = FALSE
)
```

With some example data, creating tickets for each of those in on go is only a few lines of code:

```r
lapply(seq_len(nrow(old_tickets)), function (row) {
  do.call(rt_ticket_create, as.list(old_tickets[row,]))
})
```

We can then check our work:

```r
library(dplyr)

rt_ticket_search('Queue="General"') %>%
  select(id, Subject)
```

```
# A tibble: 3 x 2
  id    Subject
  <chr> <chr>
1 1     I need some help
2 2     about those TPS reports...
3 3     hello!
```
## Editing tickets

Each ticket has a set of properties associated with it and `rt` makes it quick to update those programmatically.

For example, we write R code to resolve a ticket.
For example, say we're ready to resolve ticket number 6:

```r
rt_ticket_edit(6, status = "resolved")
```

What if we wanted to re-assign a set of tickets?
We _could_ go about this the slow way: By looking up ticket IDs in our web browser and resolving them one by one.
Instead, we can make `rt` do the work for us:

```r
result <- rt_ticket_search("Owner = 'manager'", format = "i")
sapply(result, function (id) {
  rt_ticket_edit(id, owner = "intern")
})
```

## Comment and Replying

If you're already using RT, you're probably already familiar with commenting and replying to tickets.
You've also possibly pasted text into your web browser from another source.
`rt` can help automate some of this.

For example, what if we were calculating some statistics for a ticket and wanted to put that information in the ticket as a comment?

```r
rt_ticket_history_comment(6, paste(capture.output({summary(iris)}), collapse = "\n"))
```

Above, we used the handy `capture.output` function along with `paste` but there are many other ways to get information from R into RT.

We can look at the comment we just made like so:

```r
cat(rt_ticket_history(3)$body)
```

```
...
# 3/3 (id/47/total)

id: 47
Ticket: 3
TimeTaken: 0
Type: Comment
Field:
OldValue:
NewValue:
Data: No Subject
Description: Comments added by root

Content: Sepal.Length    Sepal.Width     Petal.Length    Petal.Width          Species
         Min.   :4.300   Min.   :2.000   Min.   :1.000   Min.   :0.100   setosa    :50
         1st Qu.:5.100   1st Qu.:2.800   1st Qu.:1.600   1st Qu.:0.300   versicolor:50
         Median :5.800   Median :3.000   Median :4.350   Median :1.300   virginica :50
         Mean   :5.843   Mean   :3.057   Mean   :3.758   Mean   :1.199
         3rd Qu.:6.400   3rd Qu.:3.300   3rd Qu.:5.100   3rd Qu.:1.800
         Max.   :7.900   Max.   :4.400   Max.   :6.900   Max.   :2.500

Creator: root
Created: 2020-03-03 01:07:45
...
```

## Piping

Many functions in `rt` return values suitable for passing into other functions, such as with the `%>%` operator from the `magrittr` package that's commonly used in the `tidyverse`.
Here's an example of how this can be used:

```r
rt_ticket_create("General") %>%
  rt_ticket_edit(owner = "some_user") %>%
  rt_ticket_history_comment("Hey, this is just a comment...")
```