Package 'okapi' reference manual

Title:	Open Data Kit (ODK)-based Computer-assisted Personal Interviewing (CAPI) Tools
Description:	Data collection using computer-assisted personal interviewing or CAPI tools is now the standard approach for conducting surveys and studies. A wide range of CAPI systems are currently being used. The ability to interface with these systems helps in the overall data process. This package provides interface functions to CAPI systems based on the Open Data Kit or ODK technology.
Authors:	Ernest Guevarra [aut, cre]
Maintainer:	Ernest Guevarra <[email protected]>
License:	GPL-3
Version:	0.1.0.9000
Built:	2024-10-15 05:46:29 UTC
Source:	https://github.com/rapidsurveys/okapi

Basic authentication to KoBo Toolbox with a username and password

Description

Basic authentication to KoBo Toolbox with a username and password

Usage

kobo_auth_password(username, password = askpass::askpass())
kobo_auth_password(username, password = askpass::askpass())

Arguments

`username`	KoBo Toolbox username.
`password`	KoBo Toolbox password. Default is an interactive input of password.

Value

System environment variables for KOBO_KF_USERNAME and KOBO_KF_PASSWORD

Examples

kobo_auth_password(username = Sys.getenv("KOBO_USERNAME"),
                   password = Sys.getenv("KOBO_PASSWORD"))

kobo_auth_password(username = Sys.getenv("KOBO_USERNAME"),
                   password = Sys.getenv("KOBO_PASSWORD"))

Basic authentication to KoBo Toolbox with API authentication token

Description

Basic authentication to KoBo Toolbox with API authentication token

Usage

kobo_auth_token(token)
kobo_auth_token(token)

Arguments

token

KoBo Toolbox API authentication token.

Value

System environment variables for KOBO_KF_TOKEN

Examples

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))

Retrieve specific dataset by form ID from specific user

Description

Retrieve specific dataset by form ID from specific user

Usage

kobo_get_data(
  base_url = "https://kf.kobotoolbox.org",
  auth_mode = "token",
  asset_id
)
kobo_get_data(
  base_url = "https://kf.kobotoolbox.org",
  auth_mode = "token",
  asset_id
)

Arguments

`base_url`	KoBo Toolbox URL. Default is https://kf.kobotoolbox.org.
`auth_mode`	Password or token? Default is token.
`asset_id`	Unique asset identifier.

Value

A tibble of datasets available to specific user.

Examples

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))
kobo_get_data(asset_id = "aKJTpKiVUcPYim2epKkPvW")

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))
kobo_get_data(asset_id = "aKJTpKiVUcPYim2epKkPvW")

Retrieve list of assets available to specific user

Description

Retrieve list of assets available to specific user

Usage

kobo_list_assets(base_url = "https://kf.kobotoolbox.org", auth_mode = "token")
kobo_list_assets(base_url = "https://kf.kobotoolbox.org", auth_mode = "token")

Arguments

`base_url`	KoBo Toolbox URL. Default is https://kf.kobotoolbox.org.
`auth_mode`	Password or token? Default is token.

Value

A list of assets available to specific user.

Examples

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))
kobo_list_assets()

kobo_auth_token(token = Sys.getenv("KOBO_TOKEN"))
kobo_list_assets()

Basic authentication to ONA with a username and password

Description

Basic authentication to ONA with a username and password

Usage

ona_auth_password(username, password = askpass::askpass())
ona_auth_password(username, password = askpass::askpass())

Arguments

`username`	ONA username.
`password`	ONA password. Default is an interactive input of password.

Value

System environment variables for ONA_USERNAME and ONA_PASSWORD

Examples

ona_auth_password(username = Sys.getenv("ONA_USERNAME"),
                  password = Sys.getenv("ONA_PASSWORD"))

ona_auth_password(username = Sys.getenv("ONA_USERNAME"),
                  password = Sys.getenv("ONA_PASSWORD"))

Basic authentication to ONA with API authentication token

Description

Basic authentication to ONA with API authentication token

Usage

ona_auth_token(token)
ona_auth_token(token)

Arguments

token

ONA API authentication token.

Value

System environment variables for ONA_TOKEN

Examples

ona_auth_token(token = Sys.getenv("ONA_TOKEN"))

ona_auth_token(token = Sys.getenv("ONA_TOKEN"))

Configure HTTP headers

Description

Configure HTTP headers

Usage

ona_configure(auth_mode = c("token", "password"))
ona_configure(auth_mode = c("token", "password"))

Arguments

auth_mode

Password or token? Default is token.

Value

An object of class request for HTTP requests

Retrieve specific dataset by form ID from specific user

Description

Retrieve specific dataset by form ID from specific user

Usage

ona_data_get(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  form_id
)
ona_data_get(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  form_id
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`form_id`	Form identifier.

Value

A tibble of retrieved dataset.

Examples

ona_data_get(form_id = 276175)

ona_data_get(form_id = 276175)

Retrieve list of datasets available to specific user

Description

Retrieve list of datasets available to specific user

Usage

ona_data_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)
ona_data_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.

Value

A tibble of datasets available to specific user.

Examples

ona_data_list()

ona_data_list()

Delete published form

Description

Delete published form

Usage

ona_form_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  form_id = NULL
)
ona_form_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  form_id = NULL
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`form_id`	Form identifier.

Value

Delete specified form from ONA.

Examples

form_list <- ona_form_list()
form_id <- form_list[["formid"]][form_list[["title"]] == "Appearance Widgets"]
ona_form_delete(form_id = form_id)

form_list <- ona_form_list()
form_id <- form_list[["formid"]][form_list[["title"]] == "Appearance Widgets"]
ona_form_delete(form_id = form_id)

List published forms

Description

List published forms

Usage

ona_form_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)
ona_form_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.

Value

A tibble of published forms.

Examples

ona_form_list()

ona_form_list()

Publish XLSForm

Description

Publish XLSForm

Usage

ona_form_publish(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  xls_file = NULL,
  xls_url = NULL,
  dropbox_xls_url = NULL,
  project_id = NULL,
  public = FALSE
)
ona_form_publish(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  xls_file = NULL,
  xls_url = NULL,
  dropbox_xls_url = NULL,
  project_id = NULL,
  public = FALSE
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`xls_file`	Path to the XLSForm file.
`xls_url`	URL to the XLSForm file.
`dropbox_xls_url`	Dropbox URL to the XLSForm file.
`project_id`	Project identifier of project to publish XLSForm to. If NULL (default), XLSForm is published to the an account's default project.
`public`	Logical. Should the form be public? Default to FALSE.

Value

A published form on ONA.

Examples

project_list <- ona_project_list()
if ("test" %in% project_list$name) {
  project_id = project_list$id[project_list$name == "test"]
  ona_project_delete(project_id = project_id)
}
ona_project_register(name = "test")
project_list <- ona_project_list()
project_id = project_list$id[project_list$name == "test"]
ona_form_publish(
  xls_file = system.file(
    "appearance_widgets.xlsx", package = "okapi"
  ),
  project_id = project_id
)

project_list <- ona_project_list()
if ("test" %in% project_list$name) {
  project_id = project_list$id[project_list$name == "test"]
  ona_project_delete(project_id = project_id)
}
ona_project_register(name = "test")
project_list <- ona_project_list()
project_id = project_list$id[project_list$name == "test"]
ona_form_publish(
  xls_file = system.file(
    "appearance_widgets.xlsx", package = "okapi"
  ),
  project_id = project_id
)

Delete registered organisation

Description

Delete registered organisation

Usage

ona_org_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  org
)
ona_org_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  org
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`org`	Organisation short name or username.

Value

Delete specified organisation from specific ONA account.

Examples

org_list <- ona_org_list()
org_name <- org_list[["org"]]
ona_org_delete(org = org_name)

org_list <- ona_org_list()
org_name <- org_list[["org"]]
ona_org_delete(org = org_name)

List organisations

Description

List organisations

Usage

ona_org_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)
ona_org_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.

Value

A tibble of organisations.

Examples

ona_org_list()

ona_org_list()

Register an organisation

Description

Usage

ona_org_register(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  org,
  name = NULL
)
ona_org_register(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  org,
  name = NULL
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`org`	Organisation short name or username.
`name`	Organisation full name. If NULL (default), short name is used.

Value

Invisible. Organisation registered and created in ONA account

Examples

ona_org_register(org = "okapi_organisation")

ona_org_register(org = "okapi_organisation")

Delete registered project

Description

Delete registered project

Usage

ona_project_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL
)
ona_project_delete(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`project_id`	Project identifier.

Value

Delete specified project from specific ONA account.

Examples

project_list <- ona_project_list()
project_id <- project_list[["projectid"]]
ona_project_delete(project_id = project_id)

project_list <- ona_project_list()
project_id <- project_list[["projectid"]]
ona_project_delete(project_id = project_id)

Get project info

Description

Get project info

Usage

ona_project_info(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL
)
ona_project_info(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`project_id`	Project identifier.

Value

A tibble of projects.

Examples

ona_project_info(project_id = 12345)

ona_project_info(project_id = 12345)

List projects

Description

List projects

Usage

ona_project_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)
ona_project_list(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password")
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.

Value

A tibble of projects.

Examples

ona_project_list()

ona_project_list()

Register a project

Description

Usage

ona_project_register(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  owner = Sys.getenv("ONA_USERNAME"),
  name = NULL,
  public = TRUE
)
ona_project_register(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  owner = Sys.getenv("ONA_USERNAME"),
  name = NULL,
  public = TRUE
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`owner`	Username or organisation name creating the project. Default to username of currently authenticated account (via 'Sys.getenv(ONA_USERNAME)'). If organisation name, should be an organisation to which currently authenticated account is the owner or admin user.
`name`	Name of the project. If NULL (default), project is given a default name similar to that created by ONA for forms published without a project
`public`	Logical. Should the project be public? Default to TRUE.

Value

Invisible. Project registered and created in ONA account

Examples

ona_project_register()

ona_project_register()

Share projects with user(s)

Description

Share projects with user(s)

Usage

ona_project_share(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL,
  username = NULL,
  role = c("readonly", "dataentry", "editor", "manager"),
  email = NULL
)
ona_project_share(
  base_url = "https://api.ona.io",
  auth_mode = c("token", "password"),
  project_id = NULL,
  username = NULL,
  role = c("readonly", "dataentry", "editor", "manager"),
  email = NULL
)

Arguments

`base_url`	ONA URL. Default is https://api.ona.io.
`auth_mode`	Password or token? Default is token.
`project_id`	Project identifier.
`username`	A character value or vector of username/s of user/s to share a form with.
`role`	A character value for the role the user/s will have on the project. This can be readonly, dataentry, editor, or manager.
`email`	Email message to send to user/s to whom project has been shared with. If NULL (default), user/s will not be notified.

Value

Invisible. Project shared with specified users with specified roles. A tibble of project information.

Examples

ona_project_share(
  project_id = 12345,
  username = "validtrial",
  role = "readonly"
 )

ona_project_share(
  project_id = 12345,
  username = "validtrial",
  role = "readonly"
 )

Package 'okapi'

Help Index

Basic authentication to KoBo Toolbox with a username and password

Description

Usage

Arguments

Value

Examples

Basic authentication to KoBo Toolbox with API authentication token

Description

Usage

Arguments

Value

Examples

Retrieve specific dataset by form ID from specific user

Description

Usage

Arguments

Value

Examples

Retrieve list of assets available to specific user

Description

Usage

Arguments

Value

Examples

Basic authentication to ONA with a username and password

Description

Usage

Arguments

Value

Examples

Basic authentication to ONA with API authentication token

Description

Usage

Arguments

Value

Examples

Configure HTTP headers

Description

Usage

Arguments

Value

Retrieve specific dataset by form ID from specific user

Description

Usage

Arguments

Value

Examples

Retrieve list of datasets available to specific user

Description

Usage

Arguments

Value

Examples

Delete published form

Description

Usage

Arguments

Value

Examples

List published forms

Description

Usage

Arguments

Value

Examples

Publish XLSForm

Description

Usage

Arguments

Value

Examples

Delete registered organisation

Description

Usage

Arguments

Value

Examples

List organisations