| Title: | Connect to the 'nettskjema.no' API of the University of Oslo |
|---|---|
| Description: | Enables users to retrieve data, meta-data, and codebooks from <https://nettskjema.no/>. The data from the API is richer than from the online data portal. This package is not developed by the University of Oslo IT. Mowinckel (2021) <doi:10.5281/zenodo.4745481>. |
| Authors: | Athanasia Mo Mowinckel [aut, cre] (ORCID: <https://orcid.org/0000-0002-5756-0223>), Trym Nohr Fjørtoft [ctb] (ORCID: <https://orcid.org/0000-0002-7654-4587>) |
| Maintainer: | Athanasia Mo Mowinckel <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.4 |
| Built: | 2026-05-11 07:41:04 UTC |
| Source: | https://github.com/LCBC-UiO/nettskjemar |
Codebook is by default turned off in Nettskjema, but best practices in handling data is to have it on. This function checks if the codebook of a form has been activated or not
has_codebook(form_id)has_codebook(form_id)
form_id |
integer. Number of the form to retrieve |
logical is codebook is turned on
has_codebook(123823)has_codebook(123823)
The 'ns_add_labels' function applies labels to variables in a dataset based on a provided codebook. It assigns variable labels, value labels, and metadata required for the "ns-data" class.
ns_add_labels(data, codebook)ns_add_labels(data, codebook)
data |
data from |
codebook |
object from
|
A data frame with the same structure as 'data', but with variable and value labels applied. The resulting object is assigned the class '"ns-data"'.
data <- ns_get_data(123823) cb <- ns_get_codebook(123823) labeled_data <- ns_add_labels(data, cb)data <- ns_get_data(123823) cb <- ns_get_codebook(123823) labeled_data <- ns_add_labels(data, cb)
This function processes checkbox matrix variables in a dataset, transforming their representations into one of the specified formats.
ns_alter_checkbox(data, to = c("character", "list"), sep = ",", cb = NULL)ns_alter_checkbox(data, to = c("character", "list"), sep = ",", cb = NULL)
data |
A 'data.frame' containing the dataset to modify. |
to |
A character string specifying the output format for checkbox matrix variables. Must be one of "character" or "list". |
sep |
A character string used as a separator when 'to = "character"'. Defaults to '","'. |
cb |
An optional codebook ('data.frame') to identify checkbox matrix variables. If 'NULL', the codebook is generated using 'ns_get_codebook()'. |
A modified 'data.frame' with processed checkbox matrix variables.
dt <- ns_get_data(123823) cb <- ns_get_codebook(123823) ns_alter_checkbox(dt, to = "list", cb = cb) ns_alter_checkbox(dt, to = "character", sep = ";", cb = cb)dt <- ns_get_data(123823) cb <- ns_get_codebook(123823) ns_alter_checkbox(dt, to = "list", cb = cb) ns_alter_checkbox(dt, to = "character", sep = ";", cb = cb)
Opens the browser to display the API documentation for the Nettskjema PI.
ns_api_docs()ns_api_docs()
None. Opens a browser window.
## Not run: ns_api_docs() ## End(Not run)## Not run: ns_api_docs() ## End(Not run)
This function initializes an OAuth2 client using the 'httr2::oauth_client' function. It is used to authenticate and interact with the Nettskjema API.
ns_client( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )ns_client( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )
client_id |
[character] The client ID provided by Nettskjema. |
client_secret |
[character] The client secret provided by Nettskjema. |
client_name |
[character] An optional name for the client (default = "nettskjemar"). |
A configured 'httr2::oauth_client' object.
## Not run: # Example: Initialize an OAuth2 client for Nettskjema client <- ns_client( client_id = "your_client_id", client_secret = "your_client_secret" ) # Using a custom client name client <- ns_client( client_id = "your_client_id", client_secret = "your_client_secret", client_name = "custom_client_name" ) ## End(Not run)## Not run: # Example: Initialize an OAuth2 client for Nettskjema client <- ns_client( client_id = "your_client_id", client_secret = "your_client_secret" ) # Using a custom client name client <- ns_client( client_id = "your_client_id", client_secret = "your_client_secret", client_name = "custom_client_name" ) ## End(Not run)
Opens the Nettskjema client creation URL in the default web browser.
ns_create_client()ns_create_client()
Use this function to create a new client for accessing Nettskjema APIs.
NULL. Opens the client creation page in a browser.
## Not run: ns_create_client() ## End(Not run)## Not run: ns_create_client() ## End(Not run)
The Nettskjema forms has an option
to upload attachments with forms.
These can be retrieved by this function.
Recommended workflow is to first call
ns_list_submission_attachments,
and use the output of this to pass along
to the function. This function is called
by ns_get_form_attachments,
but you can use it to define your own output
file names.
ns_get_attachment(attachment_id, path = NULL)ns_get_attachment(attachment_id, path = NULL)
attachment_id |
integer. Unique ID of attachment, as found in the submission data. |
path |
Character. Location to save the file. |
httr2-response. saves attachment to file.
## Not run: #submission_id <- c(22222, 1232, 21555) #attach_dt <- ns_list_submission_attachments(submission_id) #ns_save_attachment(path = attach_dt$path, output = attach_dt$standardized) ## End(Not run)## Not run: #submission_id <- c(22222, 1232, 21555) #attach_dt <- ns_list_submission_attachments(submission_id) #ns_save_attachment(path = attach_dt$path, output = attach_dt$standardized) ## End(Not run)
With the given API token, will retrieve a list of all the forms you have access to
ns_get_codebook(form_id, asis = FALSE)ns_get_codebook(form_id, asis = FALSE)
form_id |
integer. Number of the form to retrieve |
asis |
logical. Whether to return the raw content from nettskjema. Default is FALSE. |
list of class ns_meta_data
ns_get_codebook(123823) ns_get_codebook(123823, asis = TRUE)ns_get_codebook(123823) ns_get_codebook(123823, asis = TRUE)
This function connects to a specific form and fetches all answers. The responses are placed in a data.frame for easy use.
ns_get_data(form_id, type = NULL) ns_get_submissions(form_id, type = NULL)ns_get_data(form_id, type = NULL) ns_get_submissions(form_id, type = NULL)
form_id |
integer. Number of the form to retrieve |
type |
Character or NULL. One of either "original" or "long". |
- Returns data in the same tabular format as delivered by Nettskjema.
- Returns the data in tall format, where there are multiple rows per participant (one per question) and each choice is timestamped.
data.frame
ns_get_submissions(): Alternative function name, does the same.
# Retrieve all data ns_get_data(123823) ns_get_data(123823, "long")# Retrieve all data ns_get_data(123823) ns_get_data(123823, "long")
Some Nettskjema have fields for attachments. These
can be downloaded through this function. There
are two naming convention that may be used for the
saved files' names. See output of
ns_list_submission_attachments for idea
of the names used.
ns_get_form_attachments( form_id, filenames = c("standardized", "original"), output_dir = "." )ns_get_form_attachments( form_id, filenames = c("standardized", "original"), output_dir = "." )
form_id |
integer. Number of the form to retrieve |
filenames |
Character of either 'standardized' (default) or 'original' indicating which file names to use. |
output_dir |
directory to output the files to |
filenames types
- uses file names are they were uploaded to Nettskjema
- creates file names based on the submission id and a counter number to uniquely create file names for each submission (in case there are more than one attachment)
invisible named logical if the file was saved successfully
## Not run: form_id <- 1100000 ns_get_form_attachments(form_id) # save files to specific folder ns_get_form_attachments(form_id, output_dir = "~/Desktop") # save using original file names ns_get_form_attachments(form_id, filenames = "original") ## End(Not run)## Not run: form_id <- 1100000 ns_get_form_attachments(form_id) # save files to specific folder ns_get_form_attachments(form_id, output_dir = "~/Desktop") # save using original file names ns_get_form_attachments(form_id, filenames = "original") ## End(Not run)
Each Nettskjema form has several auxiliary forms that can be retrieved.
ns_get_form_reports( form_id, type = c("csv", "excel", "spss"), path = report_path(form_id, type) )ns_get_form_reports( form_id, type = c("csv", "excel", "spss"), path = report_path(form_id, type) )
form_id |
integer. Number of the form to retrieve |
type |
Character. Either "csv", "excel" or "spss". |
path |
Character. Full path to where the downloaded file should be saved. Defaults to current directory with correct extension. |
httr2-response
## Not run: ns_get_form_reports(123823, type="csv") ns_get_form_reports(123823, type="excel") ns_get_form_reports(123823, type="spss") ## End(Not run)## Not run: ns_get_form_reports(123823, type="csv") ns_get_form_reports(123823, type="excel") ns_get_form_reports(123823, type="spss") ## End(Not run)
All users have access to specific forms, and this function uses the token provided to check what the current user has access to.
ns_get_forms(asis = FALSE)ns_get_forms(asis = FALSE)
asis |
logical. Whether to return the raw content from nettskjema. Default is FALSE. |
data.frame, if asis = TRUE returns a list
ns_get_forms()ns_get_forms()
Based on login credential, returns information on the user accessing the Nettskjema PI
ns_get_me()ns_get_me()
list of information
ns_get_me()ns_get_me()
With the given API token, will retrieve the meta-data connected to a form.
ns_get_meta(form_id)ns_get_meta(form_id)
form_id |
integer. Number of the form to retrieve |
list of class ns_meta_data
ns_get_meta(123823)ns_get_meta(123823)
Get an individual submission answer
ns_get_submission(submission_id)ns_get_submission(submission_id)
submission_id |
integer. Unique identifier of a specific Nettskjema submission. |
list of all answers
ns_get_submission(27685292)ns_get_submission(27685292)
Each unique submission ID in Nettskjema may have some attachments. This function saves all attachments associated with a submission ID.
ns_get_submission_attachments( submission_id, filenames = "standardized", output_dir = paste0("./", submission_id) )ns_get_submission_attachments( submission_id, filenames = "standardized", output_dir = paste0("./", submission_id) )
submission_id |
integer. Unique identifier of a specific Nettskjema submission. |
filenames |
Character of either 'standardized' (default) or 'original' indicating which file names to use. |
output_dir |
directory to output the files to |
a data.frame with information on attachments available, files written to path
## Not run: submission_id <- 22222 ns_get_submission_attachments(submission_id) ns_get_submission_attachments(submission_id, "original") ## End(Not run)## Not run: submission_id <- 22222 ns_get_submission_attachments(submission_id) ns_get_submission_attachments(submission_id, "original") ## End(Not run)
Retrieves the current OAuth2 access token for debugging purposes, such as testing endpoints in Swagger UI. This function uses the client credentials flow to obtain the token. You will not normally need to call this function directly, as authentication is handled automatically.
ns_get_token( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )ns_get_token( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )
client_id |
Character. Retrieved from the Client portal. |
client_secret |
Character. Retrieved from the Client portal. |
client_name |
Character. Used to identify who has been running the commands. |
httr2 token object, list with access_token, token_type, and expires_in
## Not run: # Get token for Swagger debugging token <- ns_get_token() token$access_token ## End(Not run)## Not run: # Get token for Swagger debugging token <- ns_get_token() token$access_token ## End(Not run)
This function verifies whether the required system variables ('NETTSKJEMA_CLIENT_ID' and 'NETTSKJEMA_CLIENT_SECRET') are set to enable authentication with the Nettskjema API. It provides feedback on the setup status and returns whether the system is correctly configured.
ns_has_auth( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET") )ns_has_auth( client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET") )
client_id |
[character] The client ID provided by Nettskjema. |
client_secret |
[character] The client secret provided by Nettskjema. |
Logical. Returns 'TRUE' if both environment variables are set, otherwise 'FALSE'.
For more information about authentication setup, see: https://www.capro.dev/nettskjemar/articles/authentication.html
ns_has_auth()ns_has_auth()
Some Nettskjema have fields for attachments. These
can be downloaded through this function. There
are two naming convention that may be used for the
saved files' names. See output of
ns_list_submission_attachments for idea
of the names used.
ns_list_form_attachments(form_id)ns_list_form_attachments(form_id)
form_id |
integer. Number of the form to retrieve |
filenames types
- uses file names are they were uploaded to Nettskjema
- creates file names based on the submission id and a counter number to uniquely create file names for each submission (in case there are more than one attachment)
invisible named logical if the file was saved successfully
## Not run: form_id <- 1100000 ns_list_form_attachments(form_id) ## End(Not run)## Not run: form_id <- 1100000 ns_list_form_attachments(form_id) ## End(Not run)
Each unique submission ID in Nettskjema may have some attachments. These can be listed using this function, which will provide the information on where in the Nettskjema API the files are located, their original file names, and a suggested standardized file names for tidier data output.
ns_list_submission_attachments(submission_id)ns_list_submission_attachments(submission_id)
submission_id |
integer. Unique identifier of a specific Nettskjema submission. |
a data.frame with information on attachments available.
## Not run: submission_id <- 22222 ns_list_submission_attachments(submission_id) ## End(Not run)## Not run: submission_id <- 22222 ns_list_submission_attachments(submission_id) ## End(Not run)
Sets the API url and access token. This is used for almost all the functionality in this package. If you want to use endpoints not yet covered by functions in the package, this is the basis function you can build from.
ns_req(...)ns_req(...)
... |
arguments passed to |
httr2 request
## Not run: ns_req() |> httr2::req_url_path_append("me") |> httr2::req_perform() |> httr2::resp_body_json() ## End(Not run)## Not run: ns_req() |> httr2::req_url_path_append("me") |> httr2::req_perform() |> httr2::resp_body_json() ## End(Not run)
After creating a client in Nettskjema, this function will retrieve the access token needed for the remaining processes in the package. Automatically caches the token for more efficient API usage.
ns_req_auth( req, client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )ns_req_auth( req, client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"), client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"), client_name = "nettskjemar" )
req |
An httr2 request, usually |
client_id |
Character. Retrieved from the Client portal. |
client_secret |
Character. Retrieved from the Client portal. |
client_name |
Character. Used to identify who has been running the commands. |
This function provides a situational report (sitrep) for the Nettskjema R package. It outputs detailed information on the package version, API configuration, environment variables, and tests API connectivity when credentials are available.
ns_sitrep()ns_sitrep()
The function performs the following: - Displays the installed version of the 'nettskjemar' package. - Validates the 'NETTSKJEMA_CLIENT_ID' and 'NETTSKJEMA_CLIENT_SECRET' environment variables. - Checks the API base URL for connectivity and attempts a test request if credentials are configured. - Displays system environment details such as R version and operating system.
No return value; the function outputs diagnostic and configuration status messages to the console.
ns_sitrep()ns_sitrep()
Validates the format of Nettskjema client identifiers such as the 'NETTSKJEMA_CLIENT_ID' or 'NETTSKJEMA_CLIENT_SECRET'. Returns 'TRUE' if the input matches the required format, and 'FALSE' otherwise.
ns_validate_client_pattern(x, type = c("id", "secret")) ns_validate_client_id(x) ns_validate_client_secret(x)ns_validate_client_pattern(x, type = c("id", "secret")) ns_validate_client_id(x) ns_validate_client_secret(x)
x |
A character string to validate. |
type |
The identifier type to validate ('"id"' or '"secret"'). |
- '"id"' validation expects a UUID format: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'. - '"secret"' validation expects a 72-character alphanumeric string.
A logical value: 'TRUE' if the input format is valid, otherwise
ns_validate_client_id(): Validate Nettskjema Client ID
ns_validate_client_secret(): Validate Nettskjema Client Secret
client_id <- "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ns_validate_client_pattern(client_id, type = "id") ns_validate_client_id(client_id) client_secret <- "aB3xK9mP2vQ8_R7nL98Mcs81sT4uY6wE5zC0hJ9iO3kM8pN2qA7bD1gF4jH6lS-9vX3nR5mT" #nolint ns_validate_client_pattern(client_secret, type = "secret") ns_validate_client_secret(client_secret)client_id <- "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ns_validate_client_pattern(client_id, type = "id") ns_validate_client_id(client_id) client_secret <- "aB3xK9mP2vQ8_R7nL98Mcs81sT4uY6wE5zC0hJ9iO3kM8pN2qA7bD1gF4jH6lS-9vX3nR5mT" #nolint ns_validate_client_pattern(client_secret, type = "secret") ns_validate_client_secret(client_secret)
Save codebook information to a
file for safe keeping. Depending
on the type of codebook (raw or tidy)
the file will either be stored as a
json-file through write_json
or a text table through write.table.
ns_write_codebook(codebook, path, ...) ## Default S3 method: ns_write_codebook(codebook, path, ...) ## S3 method for class 'ns_codebook_raw' ns_write_codebook(codebook, path, ...) ## S3 method for class 'ns_codebook' ns_write_codebook(codebook, path, sep = "\t", ...)ns_write_codebook(codebook, path, ...) ## Default S3 method: ns_write_codebook(codebook, path, ...) ## S3 method for class 'ns_codebook_raw' ns_write_codebook(codebook, path, ...) ## S3 method for class 'ns_codebook' ns_write_codebook(codebook, path, sep = "\t", ...)
codebook |
object of class ns_codebook |
path |
filename or path |
... |
arguments to
|
sep |
character. If writing text table, column delimiter. |
Given the two types of codebooks, writes different types of files.
- writes a tab-separated table
- writes a json-file
no return value. Writes a file to path.
## Not run: form_id <- 1100000 my_cb <- ns_get_codebook(form_id) ns_write_codebook(my_cb, "my/path/codebook_110000.txt") ## End(Not run)## Not run: form_id <- 1100000 my_cb <- ns_get_codebook(form_id) ns_write_codebook(my_cb, "my/path/codebook_110000.txt") ## End(Not run)
Save meta-data information to a file for safe keeping. The function saves the data in json-format, which best preserves the information.
ns_write_meta(meta, path, ...) ## Default S3 method: ns_write_meta(meta, path, ...) ## S3 method for class 'ns_meta' ns_write_meta(meta, path, ...)ns_write_meta(meta, path, ...) ## Default S3 method: ns_write_meta(meta, path, ...) ## S3 method for class 'ns_meta' ns_write_meta(meta, path, ...)
meta |
object of class ns_meta class |
path |
file name or path |
... |
other arguments to |
no return value. Writes a file to path.
## Not run: form_id <- 1100000 my_meta <- ns_get_meta(form_id) ns_write_meta(my_meta, "my/path/meta_110000.json") ## End(Not run)## Not run: form_id <- 1100000 my_meta <- ns_get_meta(form_id) ns_write_meta(my_meta, "my/path/meta_110000.json") ## End(Not run)