Kobo: Kobo Class

In CorrelAid/kbtbr: A Wrapper for the KoBoToolbox API

Kobo Class

Description

Interface class for the Kobo API that can handle KoboClient instances (sessions) for both API versions. The Class exposes both generic and specific methods for HTTP requests / interactions with the various endpoints.

Public fields

session_v2

KoboClient session for v2 of the API

session_v1

KoboClient session for v1 of the API

Methods

Public methods

• Kobo$new()

• Kobo$get()

• Kobo$post()

• Kobo$get_assets()

• Kobo$get_surveys()

• Kobo$get_asset()

• Kobo$get_submissions()

• Kobo$clone_asset()

• Kobo$deploy_asset()

• Kobo$import_xls_form()

• Kobo$create_asset()

• Kobo$clone()

---

Method new()

Initialization method for class "Kobo".

Usage

Kobo$new(
  base_url_v2 = NULL,
  base_url_v1 = NULL,
  kobo_token = Sys.getenv("KBTBR_TOKEN"),
  session_v2 = NULL,
  session_v1 = NULL
)

Arguments

base_url_v2

character. The base URL of the API version 2 (known as /api/v2). For example: https://kobo.correlaid.org.

base_url_v1

character. The base URL of the API of your KoBoCAT API (also known as /api/v1). Defaults to NULL. For example: https://kc.correlaid.org.

kobo_token

character. The API token. Defaults to requesting the systen environment KBTBR_TOKEN.

session_v2

KoboClient To pass directly a KoboClient instance for the API version v2.

session_v1

KoboClient In addition to session_v2 one can pass also a KoboClient instance for the API version v1.

---

Method get()

Wrapper for the GET method of internal session objects.

Usage

Kobo$get(path, query = list(), version = "v2", format = "json", parse = TRUE)

Arguments

path

character. Path component of the endpoint.

query

list. A named list which is parsed to the query component. The order is not hierarchical.

version

character. Indicates on which API version the request should be executed (available: v1, v2). Defaults to v2.

format

character. the format to request from the server. either 'json' or 'csv'. defaults to 'json'

parse

whether or not to parse the HTTP response. defaults to TRUE.

Returns

a list encoding of the json server reply if parse=TRUE. Otherwise, it returns the server response as a crul::HttpResponse object.

---

Method post()

Wrapper for the POST method of internal session objects.

Usage

Kobo$post(path, body, version = "v2")

Arguments

path

character. Path component of the endpoint.

body

R list. A data payload to be sent to the server.

version

character. Indicates on which API version the request should be executed (available: v1, v2). Defaults to v2.

Returns

Returns an object of class crul::HttpResponse.

---

Method get_assets()

Returns a list of all assets available in the server as tibble

Usage

Kobo$get_assets()

---

Method get_surveys()

High-level GET request for surveys endpoints endpoint

Usage

Kobo$get_surveys(show_all_cols = FALSE)

Arguments

show_all_cols

if true returns all the columns available for an asset

Returns

An user-friendly summary of the available surveys as a tibble

---

Method get_asset()

Get an asset given its id.

Usage

Kobo$get_asset(id)

Arguments

id

character. ID of the asset within the Kobo API.

Returns

Asset. object of class Asset

---

Method get_submissions()

Get the submissions for a survey.

Usage

Kobo$get_submissions(id)

Arguments

id

character. ID of the survey asset within the Kobo API.

Returns

tibble. submissions as a tibble. if no submissions were made yet, the tibble will have no columns. High-level POST request to clone an asset. assets endpoint (due to default to v2, no further specification is needed).

---

Method clone_asset()

Usage

Kobo$clone_asset(clone_from, new_name, asset_type)

Arguments

clone_from

character. UID of the asset to be cloned.

new_name

character. Name of the new asset.

asset_type

character. Type of the new asset. Can be "block", "question", "survey", "template".

Returns

Returns an object of class crul::HttpResponse.

---

Method deploy_asset()

High-level POST request to deploy an asset. assets/{uid}/deployment/ endpoint (due to default to v2, no further specification is needed).

Usage

Kobo$deploy_asset(uid)

Arguments

uid

character. UID of the asset to be deployed.

Returns

Returns an object of class crul::HttpResponse.

---

Method import_xls_form()

High-level POST request to import an XLS form. imports endpoint (due to default to v2, no further specification is needed).

Usage

Kobo$import_xls_form(name, file_path)

Arguments

name

character. Name of the new asset.

file_path

character. The path to the XLS form file.

Returns

Returns an object of class crul::HttpResponse.

---

Method create_asset()

High-level POST request to create an empty asset. assets/ endpoint (due to default to v2, no further specification is needed).

Usage

Kobo$create_asset(
  name,
  asset_type,
  description = "",
  sector = list(label = "", value = ""),
  country = list(label = "", value = ""),
  share_metadata = FALSE
)

Arguments

name

character. Name of the new asset.

asset_type

character. Type of the new asset. Can be "block", "question", "survey", "template".

description

character. Optional.

sector

A list with elements label and value. Optional. Corresponding labels and values can be found here.

country

A list with elements label and value. Optional. Corresponding labels and values can be found here.

share_metadata

boolean. Optional.

Returns

Returns an object of class crul::HttpResponse.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Kobo$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

CorrelAid/kbtbr documentation built on Dec. 9, 2022, 8:13 a.m.