Package {jirar}

jirar: Modern R Client for the Jira REST API

Description

A modern, tidy interface to the Jira REST API for both Jira Cloud and Jira Server / Data Center. Authenticate once, query issues with the Jira Query Language (JQL), and retrieve projects, fields, dashboards and more as tibbles. Built on httr2 with automatic pagination, informative errors and support for API tokens and personal access tokens.

Author(s)

Maintainer: Jan-Hendrik Weinert janhendrikweinert@gmail.com

Authors:

• Jan-Hendrik Weinert janhendrikweinert@gmail.com

See Also

Useful links:

• GitHub repository

Connect to Jira and register the default connection

Description

jira_connect() creates a jira_connection(), verifies it by requesting the current user (unless check = FALSE), and stores it as the session default so other ⁠jira_*()⁠ functions can be called without passing connection explicitly. This is the modern replacement for JirAgileR's save_jira_credentials().

Usage

jira_connect(
  url = NULL,
  user = NULL,
  token = NULL,
  deployment = c("auto", "cloud", "server"),
  check = TRUE,
  set_default = TRUE
)

Arguments

Value

The jira_connection, invisibly.

Examples

## Not run: 
# Reads JIRA_URL, JIRA_USER and JIRA_TOKEN from the environment:
jira_connect()

# Or pass values directly:
jira_connect(
  url = "https://example.atlassian.net",
  user = "me@example.com",
  token = Sys.getenv("MY_TOKEN")
)

## End(Not run)

Create a connection to a Jira instance

Description

jira_connection() builds (but does not verify) a connection object that describes how to reach a Jira instance and how to authenticate. Most users should call jira_connect() instead, which additionally verifies the credentials and registers the connection as the session default.

Usage

jira_connection(
  url = NULL,
  user = NULL,
  token = NULL,
  deployment = c("auto", "cloud", "server"),
  auth = c("auto", "basic", "bearer"),
  api_version = NULL
)

Arguments

Details

Authentication differs by deployment:

• Jira Cloud (⁠*.atlassian.net⁠) uses HTTP basic authentication with your account email as user and an API token as token. Create a token at https://id.atlassian.com/manage-profile/security/api-tokens.

• Jira Server / Data Center uses a Personal Access Token sent as a bearer token (supply token and leave user empty), or basic authentication with a username and password (supply both user and token).

Any argument left as NULL falls back to an environment variable: JIRA_URL, JIRA_USER and JIRA_TOKEN.

Value

A jira_connection object.

Examples

conn <- jira_connection(
  url = "https://example.atlassian.net",
  user = "me@example.com",
  token = "secret-api-token"
)
conn

Count the issues matching a JQL query

Description

Returns the number of issues matching a JQL query without retrieving them. On Jira Cloud this uses the approximate-count endpoint (the result is an estimate for large result sets); on Jira Server / Data Center it returns the exact total.

Usage

jira_count_issues(jql = NULL, connection = jira_get_connection())

Arguments

Value

A single integer count.

Examples

## Not run: 
jira_count_issues("project = ABC AND created >= -7d")

## End(Not run)

Retrieve Jira dashboards

Description

Returns the dashboards visible to the authenticated user as a tibble. Pagination is handled automatically.

Usage

jira_dashboards(
  filter = NULL,
  max_results = Inf,
  connection = jira_get_connection()
)

Arguments

Value

A tibble of dashboards, one row per dashboard.

Examples

## Not run: 
jira_connect()
jira_dashboards()
jira_dashboards(filter = "favourite")

## End(Not run)

Default and supported JQL fields

Description

jira_default_fields() returns the fields requested by jira_issues() when none are supplied: a compact, broadly useful set. jira_supported_fields() returns the set of well-known system fields that flatten cleanly into columns, mirroring the fields supported by the JirAgileR package.

Usage

jira_default_fields()

jira_supported_fields()

Value

A character vector of field names.

Examples

jira_default_fields()
jira_supported_fields()

Retrieve the fields defined on a Jira instance

Description

Returns all system and custom fields, including the mapping between custom field ids (e.g. customfield_10010) and their human-readable names and JQL clause names. Useful for discovering field ids to pass to jira_issues().

Usage

jira_fields(connection = jira_get_connection())

Arguments

Value

A tibble of fields, one row per field.

Examples

## Not run: 
jira_connect()
jira_fields()

## End(Not run)

Get or set the default Jira connection

Description

jira_get_connection() returns the connection registered by jira_connect(); it errors if none has been set. jira_set_connection() registers a connection as the session default. These power the connection = jira_get_connection() default of the other ⁠jira_*()⁠ functions.

Usage

jira_get_connection()

jira_set_connection(connection)

Arguments

Value

jira_get_connection() returns a jira_connection. jira_set_connection() returns the previous default invisibly.

Retrieve Jira groups

Description

Returns Jira groups as a tibble. The endpoint used depends on the deployment and whether query is supplied:

Usage

jira_groups(
  query = NULL,
  max_results = Inf,
  connection = jira_get_connection()
)

Arguments

Details

• Jira Cloud, query = NULL: all groups are listed via the paginated bulk endpoint (group/bulk), honouring max_results.

• Jira Cloud with a query, or any Jira Server / Data Center call: a name search is performed via the group picker (groups/picker), which the API caps at 1000 results.

Value

A tibble of groups, one row per group.

Examples

## Not run: 
jira_connect()
jira_groups()
jira_groups(query = "admin")

## End(Not run)

Retrieve Jira issues with a JQL query

Description

Runs a Jira Query Language (JQL) query and returns the matching issues as a tibble, one row per issue. Pagination is handled automatically: token-based (nextPageToken) on Jira Cloud and offset-based (startAt) on Jira Server / Data Center.

Usage

jira_issues(
  jql = NULL,
  fields = jira_default_fields(),
  expand = NULL,
  max_results = Inf,
  page_size = NULL,
  parse = TRUE,
  connection = jira_get_connection()
)

Arguments

Details

On Jira Cloud the search endpoint only returns the issue id and key unless fields are requested explicitly, so always pass the fields you need (or the sentinels "*all" / "*navigable"). Nested fields are flattened to snake_case columns (e.g. status_name, assignee_displayname, components_name), datetimes are parsed to POSIXct, and rich-text (Atlassian Document Format) bodies such as description are converted to plain text.

Note that array fields (e.g. components, labels, fixVersions) are collapsed to comma-separated strings, which loses the association between an object's sub-fields. For structured access to such fields, use parse = FALSE and work with the raw issue list.

Value

A tibble with one row per issue. Always includes issue_id and key; the remaining columns depend on fields and are named after the (possibly nested) field, e.g. summary, status_name, assignee_displayname. Returns the raw list when parse = FALSE.

Examples

## Not run: 
jira_connect()

# All issues you can see (no JQL needed)
jira_issues()
jira_issues(max_results = 200)

# Or filter with JQL
jira_issues("project = ABC AND statusCategory != Done")
jira_issues(
  "assignee = currentUser() ORDER BY updated DESC",
  fields = c("summary", "status", "updated"),
  max_results = 100
)

## End(Not run)

Check the current user's permissions

Description

Returns, for each requested permission, whether the authenticated user holds it (optionally within a project or issue context). On Jira Cloud the permissions argument is required by the API; if omitted, jirar fills it with the full permission catalogue from jira_permissions().

Usage

jira_my_permissions(
  permissions = NULL,
  project_key = NULL,
  issue_key = NULL,
  connection = jira_get_connection()
)

Arguments

Value

A tibble of permissions with a havepermission column.

Examples

## Not run: 
jira_connect()
jira_my_permissions(c("BROWSE_PROJECTS", "CREATE_ISSUES"))
jira_my_permissions("EDIT_ISSUES", project_key = "ABC")

## End(Not run)

Get the currently authenticated user

Description

Returns the account that the connection authenticates as. This is the lightest possible call and is used by jira_connect() to verify credentials. On Jira Cloud the user is identified by accountid; on Server / Data Center by name (username).

Usage

jira_myself(connection = jira_get_connection())

Arguments

Value

A one-row tibble describing the current user.

Examples

## Not run: 
jira_connect()
jira_myself()

## End(Not run)

Retrieve all Jira permissions

Description

Returns the catalogue of permissions the Jira instance knows about (global and project permissions), one row per permission.

Usage

jira_permissions(connection = jira_get_connection())

Arguments

Value

A tibble of permissions.

Examples

## Not run: 
jira_connect()
jira_permissions()

## End(Not run)

Retrieve Jira projects

Description

Returns the projects visible to the authenticated user as a tibble. On Jira Cloud this uses the paginated project/search endpoint; on Jira Server / Data Center it uses project (a non-paginated array).

Usage

jira_projects(
  query = NULL,
  max_results = Inf,
  connection = jira_get_connection()
)

Arguments

Value

A tibble of projects, one row per project.

Examples

## Not run: 
jira_connect()
jira_projects()
jira_projects(query = "platform")

## End(Not run)

Get information about the Jira instance

Description

Returns instance metadata, including deploymenttype (Cloud, Server or DataCenter), version and base URL.

Usage

jira_server_info(connection = jira_get_connection())

Arguments

Value

A one-row tibble of server information.

Examples

## Not run: 
jira_connect()
jira_server_info()

## End(Not run)