Movatterモバイル変換

Type:	Package
Title:	Interface to the 'Request Tracker' API
Description:	Provides a programmatic interface to the 'Request Tracker' (RT) HTTP APIhttps://rt-wiki.bestpractical.com/wiki/REST. 'RT' is a popular ticket tracking system.
Version:	1.1.0
URL:	https://github.com/nceas/rt
BugReports:	https://github.com/nceas/rt/issues
Maintainer:	Bryce Mecum <mecum@nceas.ucsb.edu>
License:	MIT + file LICENSE
Imports:	httr, stringr
Suggests:	askpass, knitr, rmarkdown, testthat, tibble
RoxygenNote:	7.1.1
VignetteBuilder:	knitr
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2021-05-14 22:08:58 UTC; bryce
Author:	Bryce Mecum [aut, cre], Irene Steves [ctb], National Center for Ecological Analysis and Synthesis [cph]
Repository:	CRAN
Date/Publication:	2021-05-15 04:10:03 UTC

Check that the login request was successful or not

Description

Check that the login request was successful or not

Usage

check_login(response)

Arguments

Value

(logical) TRUE if login was successful, errors out otherwise

Compact list.

Description

Remove all NULL entries from a list. Fromplyr::compact().

Usage

compact(l)

Arguments

Construct a string for params suitable for passing into an RT request

Description

RT's API, in a few cases, takes a body of key value pairs that are colonseparated and each key value pair is newline separated. Each pair is alsorun throughcompact to removeNULL elements.

Usage

construct_newline_pairs(params)

Arguments

Value

(character)

Parse typical RT properties as contained in an RT response body

Description

The code gives a basic idea of the format but it's basicallynewline-separated key-value pairs with a ': ' between them. e.g.,

Usage

parse_rt_properties(body)

Arguments

Details

id: queue/1Name: General

Value

List of properties

Parse an RT ticket create response body and return the ticket ID

Description

This function essential parses the text:"# Ticket 1 created."

Usage

parse_ticket_create_body(body)

Arguments

Value

(numeric) The ticket ID

Parse the response body from a call tort_user_create

Description

Parse the response body from a call tort_user_create

Usage

parse_user_create_body(body)

Arguments

Value

(numeric) The user ID

Print anrt_api object

Description

Print anrt_api object

Usage

## S3 method for class 'rt_api'print(x, ...)

Arguments

Thert package

Description

rt provides a programming interface to theRequest Tracker API.

Details

Everything should be implemented and all functions should return a reasonablyuseful result that's suitable for integrating into your workflows.

Setup

Before you can do anything useful with this package, you'll need to do threethings:

1. Determine your base URL and set it using⁠Sys.setenv(RT_BASE_URL="your url here)⁠. In most cases, this will be thesame as the URL of the page you use to log in to RT.

2. Determine and set your credentials. You can skip setting them if you likeand skip to step 3 or you can set them using theRT_USER andRT_PASSWORDenvironmental variables viaSys.setenv. Seert_login formore.

3. Log in using R by callingrt_login. Seert_login for more.

A typical flow for setting up your R session to work with RT might look likethis:

Sys.setenv(RT_BASE_URL = "http://example.com/rt",           RT_USER = "me@example.com",           RT_PASSWORD = "mypassword")

If you use RT a lot, you might consider putting code like the above in your.Renviron, minus the call tort_login() so the environmental variables areavailable but you aren't logging into RT every time you start R. See ?Startupfor more information.

Available Functions

General

• rt_login

• rt_logout

Tickets

• rt_ticket_search

• rt_ticket_create

• rt_ticket_edit

• rt_ticket_history

• rt_ticket_history_comment

• rt_ticket_history_reply

• rt_ticket_links

• rt_ticket_links_edit

• rt_ticket_merge

• rt_ticket_properties

• rt_ticket_attachments

• rt_ticket_attachment

• rt_ticket_attachment_content

Users

• rt_user_create

• rt_user_edit

• rt_user_properties

Queues

• rt_queue_properties

Get an RT response

Description

Get an RT response and format it into an S3 object

Usage

rt_GET(url, raw = FALSE, ...)

Arguments

Value

(rt_api) The parsed response from RT

POST an RT request

Description

POST an RT request

Usage

rt_POST(url, raw = FALSE, ...)

Arguments

Value

(rt_api) The parsed response from RT

Actually do the logging in part of logging in

Description

Called byrt_login andrt_login_interactive todo the work of logging in

Usage

rt_do_login(user, password, ...)

Arguments

Value

(logical) Either returnsTRUE if successful or errors out

Log in to RT

Description

Use this to log into RT at the start of your session. Once you call thisfunction and successfully log in, calls of other functions within thispackage will re-use your login information automatically.

Usage

rt_login(  user = Sys.getenv("RT_USER"),  password = Sys.getenv("RT_PASSWORD"),  ...)

Arguments

Details

The value ofrt_base_url should be the same address you use in yourweb browser to log into RT (i.e., the address of the log in page).

Value

EitherTRUE, invisibly, if logged in, or throws an error.

Examples

## Not run: # You can setup the location of your RT installation and the values for# your credentials as environmental variablesSys.setenv("RT_USER" = "user",           "RT_PASSWORD" = "password",           "RT_BASE_URL" = "https://demo.bestpractical.com")# And then log in directly likert_login()# You can also skip setting `RT_USER` and `RT_PASSWORD` and specify them# directlyrt_login("user", "password")# Note that you still need to set `RT_BASE_URL`## End(Not run)

Log in to RT interactively

Description

Wrapper forrt_login to interactively log into RT at the startof your session. Keeps your log-in information private.

Usage

rt_login_interactive(rt_base_url = Sys.getenv("RT_BASE"), ...)

Arguments

Examples

## Not run: Sys.setenv(RT_BASE_URL = "https://demo.bestpractical.com")rt_login_interactive()## End(Not run)

Log out of RT

Description

Use this to log out of RT at the end of your session.Note: restarting your R session will also log you out.

Usage

rt_logout(...)

Arguments

Value

(rt_api) The parsed response from RT

Examples

## Not run: # First, log inrt_login()# Then logoutrt_logout()## End(Not run)

Parse an RT response in its parts as a list

Description

The RT API uses overrides default HTTP behavior with their own set of statuscodes, messages, and response formats. This function parses that customimplementation and presents it into something that's easier to build apackage with.

Usage

rt_parse_response(response, verbose = FALSE)

Arguments

Details

For example, a response like:

"RT/4.4.3 200 Ok# Ticket 2 created.

is turned into the list:

$status[1] 200$message[1] "Ok"$body[1] "# Ticket 2 created."

Value

(list) List with named elements status, message, and body

Get the properties of a queue

Description

Get the properties of a queue

Usage

rt_queue_properties(queue, ...)

Arguments

Value

(list) A list of queue properties

Examples

## Not run: # By default, RT installations come with a General queue# We can get its properties like thisrt_queue_properties("General")## End(Not run)

Get a ticket's attachment

Description

Retrieves attachment metadata. To get the attachment itself, seert_ticket_attachment_content.

Usage

rt_ticket_attachment(ticket_id, attachment_id, ...)

Arguments

Value

(rt_api) Anrt_api object with the response

Examples

## Not run: # Before running rt_ticket_attachment, you'll probably want to get a list of# the attachments for a given ticket, like:attachments <- rt_ticket_attachments(1) # Ticket ID 1# And then you can get information about a specific attachment:rt_ticket_attachment(1, 3) # Attachment 3 on ticket 1## End(Not run)

Get the content of an attachment

Description

Gets the content of the specified attachment for further processing ormanipulation. You'll almost always want to call a second function likecontent to make the content of theattachment usable from R.

Usage

rt_ticket_attachment_content(ticket_id, attachment_id, ...)

Arguments

Value

(rt_api) Anrt_api object with the response

Examples

## Not run: # First, get the attachment content which gives is the raw responseatt <- rt_ticket_attachment_content(2, 1)# Then process it directly in Rhttr::content(att)# Or write it to diskout_path <- tempfile()writeBin(httr::content(x, as = 'raw'), out_path)## End(Not run)

Get a ticket's attachments

Description

Retrieves attachment metadata for a ticket in a tabular form.

Usage

rt_ticket_attachments(ticket_id, ...)

Arguments

Value

Either adata.frame ortibble of the attachments.

Examples

## Not run: # Given a ticket exists with id '2', we can get its attachments as a tablert_ticket_attachments(2)## End(Not run)

Create a ticket

Description

Create a ticket

Usage

rt_ticket_create(  queue,  requestor = NULL,  subject = NULL,  cc = NULL,  admin_cc = NULL,  owner = NULL,  status = NULL,  priority = NULL,  initial_priority = NULL,  final_priority = NULL,  time_estimated = NULL,  starts = NULL,  due = NULL,  text = NULL,  custom_field = NULL,  ...)

Arguments

Value

(numeric) The ID of the ticket

Examples

## Not run: # We can create an empty ticketrt_ticket_create("General")# Or we can provide some of the fieldsrt_ticket_create("General",                 requestor = "requestor@example.com",                 subject = "An example ticket")## End(Not run)

Edit a ticket

Description

Updates an existing ticket with new information.

Usage

rt_ticket_edit(  ticket_id,  queue = NULL,  requestor = NULL,  subject = NULL,  cc = NULL,  admin_cc = NULL,  owner = NULL,  status = NULL,  priority = NULL,  initial_priority = NULL,  final_priority = NULL,  time_estimated = NULL,  starts = NULL,  due = NULL,  text = NULL,  custom_field = NULL,  ...)

Arguments

Value

(numeric) The ID of the ticket

Examples

## Not run: # First, create a ticketticket <- rt_ticket_create("General")# Then we can update its fieldsrt_ticket_edit(ticket,               requestor = "me@example.com",               subject = "My subject")## End(Not run)

Get a ticket's history

Description

Get a ticket's history

Usage

rt_ticket_history(ticket_id, format = "l", ...)

Arguments

Value

(rt_api) Anrt_api object with the response

Examples

## Not run: # Get the full ticket history for ticket 992rt_ticket_history(992)# Get just the ticket ID and subject for ticket 992rt_ticket_history(992, format = "s")## End(Not run)

Comment on a ticket

Description

Comment on a ticket

Usage

rt_ticket_history_comment(ticket_id, comment_text, ...)

Arguments

Value

(numeric) The ID of the ticket

Examples

## Not run: rt_ticket_history_comment(1, "Your comment here...")## End(Not run)

Gets the history information for a single history item

Description

Gets the history information for a single history item

Usage

rt_ticket_history_entry(ticket_id, history_id, ...)

Arguments

Value

(rt_api) Anrt_api object with the response

Examples

## Not run: # Get the history entry for ticket 992 and history id 123rt_ticket_history(992, 123)## End(Not run)

Reply to a ticket

Description

Reply to a ticket

Usage

rt_ticket_history_reply(  ticket_id,  text,  cc = NULL,  bcc = NULL,  time_worked = "0",  attachment_path = NULL,  ...)

Arguments

Value

(numeric) The ID of the ticket

Examples

## Not run: # Reply to ticket 11 with a courteous messagert_ticket_history_reply(11,                        "Thank you.                        Have a great day!")## End(Not run)

Get a ticket's links

Description

Gets the ticket links for a single ticket. If applicable, the followingfields will be returned:HasMember,ReferredToBy,DependedOnBy,MemberOf,RefersTo,andDependsOn.

Usage

rt_ticket_links(ticket_id, ...)

Arguments

Value

(rt_api) Anrt_api object with the response

Examples

## Not run: # Assuming have a ticket with id 1007, we can get it links by callingrt_ticket_links(1007)## End(Not run)

Edit the links on a ticket

Description

Edit the links on a ticket

Usage

rt_ticket_links_edit(  ticket_id,  referred_to_by = NULL,  depended_on_by = NULL,  member_of = NULL,  refers_to = NULL,  depends_on = NULL,  ...)

Arguments

Value

(numeric) The ID of the ticket

Examples

## Not run: # Assuming we have tickets 20 and 21, we can make ticket 20 depend on ticket# 21rt_ticket_links_edit(20, depends_on = 21)## End(Not run)

Merge two tickets

Description

Merge two tickets

Usage

rt_ticket_merge(origin, into)

Arguments

Value

(numeric) The ID of ticket both tickets were merged into

Examples

## Not run: # First, create two ticketsticket_one <- rt_ticket_create("General")ticket_two <- rt_ticket_create("General")# Then merge them togetherticket_merge(ticket_one, ticket_two)## End(Not run)

Get a ticket's properties

Description

Retrieves ticket properties

Usage

rt_ticket_properties(ticket_id, ...)

Arguments

Value

(list) A list of the ticket's properties

Examples

## Not run: rt_ticket_properties(15)## End(Not run)

Search for tickets

Description

Search RT for tickets using RT's query syntax which is documented athttps://docs.bestpractical.com/rt/4.4.4/query_builder.html.

Usage

rt_ticket_search(query, orderby = NULL, format = "l", fields = NULL, ...)

Arguments

Details

Thequery parameter conforms to RT'squery syntaxand requires you to build the query yourself. A query will have one or moreparameters of the form⁠$FIELD='$VALUE'⁠ where⁠$FIELD⁠ is an RT ticketproperty like Subject, Requestor, etc and⁠$VALUE⁠ (surrounded by singlequotes) is the value to filter by. See Examples for examples.

Value

Either adata.frame ortibble (when format isl ors) or anumeric vector when it'si.

Examples

## Not run: # To return all un-owned tickets on a queue:rt_ticket_search("Queue='General' AND (Status='new')")# We can sort by date created, increasingrt_ticket_search("Queue='General' AND (Status='new')",                 orderby = "+Created")# If we just need a vector of ticket idsrt_ticket_search("Queue='General' AND (Status='new')",                 orderby = "+Created",                 format = "i")## End(Not run)

Generate an RT API URL

Description

Create an RT API URL based on the server URL and any arguments provided

Usage

rt_url(..., query_params = NULL, base_url = Sys.getenv("RT_BASE_URL"))

Arguments

Get the user agent for the package.

Description

This is used byrt_GET andrt_POST to provideHTTP requests with an appropriate user agent.

Usage

rt_user_agent()

Value

(character) The user agent string for the package

Create a user

Description

Create a user

Usage

rt_user_create(  name,  password = NULL,  email_address = NULL,  real_name = NULL,  organization = NULL,  privileged = NULL,  disabled = NULL,  ...)

Arguments

Value

(numeric) The ID of the newly-created user

Examples

## Not run: # Create a barebones user with just a namert_user_create("Some Person")# Create user that also has an email addressrt_user_create("Person", email_address = "person@example.com")## End(Not run)

Edit a user

Description

Edit a user's information.

Usage

rt_user_edit(  user_id,  password = NULL,  name = NULL,  email_address = NULL,  real_name = NULL,  organization = NULL,  privileged = NULL,  disabled = NULL,  ...)

Arguments

Value

The ID of the edited user

Examples

## Not run: # First, create a useruser_id <- rt_user_create("Example", "password", "me@example.com")# Then we can edit itrt_user_edit(user_id, real_name = "Example User")## End(Not run)

Get a user's properties

Description

Get a user's properties

Usage

rt_user_properties(user_id, ...)

Arguments

Value

(list) A list of the user's properties

Examples

## Not run: # Assuming we have a user with id 1, we can get its propertiesrt_user_properties(1)## End(Not run)

Get the version of the currently installed version of this package as acharacter vector

Description

Get the version of the currently installed version of this package as acharacter vector

Usage

rt_version_string()

Value

(character) The version is a character vector, e.g. "1.2.3"

Throw an error if the RT status code is an error status

Description

Throw an error if the RT status code is an error status

Usage

stopforstatus(response)

Arguments

Value

Either nothing, or throws an error

tidy_long_search_result

Description

tidy_long_search_result

Usage

tidy_long_search_result(result)

Arguments

Value

Adata.frame ortibble

Try to make a tibble

Description

Try to make a tibble

Usage

try_tibble(df, coerce = TRUE)

Arguments

Value

Either adata.frame or atibble

Warn if a user edit response body contains warnings

Description

Warn if a user edit response body contains warnings

Usage

warn_user_edit_warnings(body)

Arguments

Value

None.