In LCBC-UiO/nettskjemar: Connect to the 'nettskjema.no' API of the University of Oslo

Overview

Forms on Nettskjema come with associated metadata, such as the title, contact information, and status. This vignette demonstrates how to use functions to: 1. Retrieve metadata for a specific form. 2. Save metadata to a file for safe keeping.

Prerequisites

Before executing any function, ensure you are authenticated. Refer to the vignette on authentication (authentication.html) for guidance.

Additionally, load the required package:

Retrieving Metadata for a Form: ns_get_meta

The function ns_get_meta retrieves metadata for a given form using its form ID. The retrieved metadata is returned as an object of class ns_meta.

Example: Retrieve Metadata

Here’s an example of how to retrieve metadata for a form:

library(nettskjemar)

# Replace this with your form ID
formid <- 123823

# Retrieve metadata for the form
form_meta <- ns_get_meta(formid)

# Display the metadata
form_meta
#> $form_id
#> [1] 123823
#> 
#> $title
#> [1] "API test form"
#> 
#> $canEditForm
#> [1] TRUE
#> 
#> $isCodebookValid
#> [1] TRUE
#> 
#> $hasSubmissions
#> [1] TRUE
#> 
#> $modifiedDate
#> [1] "2025-03-13T19:27:18"
#> 
#> $modifiedBy
#> $modifiedBy$personId
#> [1] 58096
#> 
#> $modifiedBy$username
#> [1] "[e-mail]"
#> 
#> $modifiedBy$name
#> [1] "Athanasia Monika Mowinckel"
#> 
#> $modifiedBy$email
#> [1] "[e-mail]"
#> 
#> $modifiedBy$type
#> [1] "LOCAL"
#> 
#> 
#> $isOpen
#> [1] FALSE
#> 
#> $deliveryDestination
#> [1] "DATABASE"
#> 
#> $projectName
#> NULL
#> 
#> $numberOfPostponedSubmissions
#> [1] 0
#> 
#> $numberOfSubmissions
#> [1] 3
#> 
#> $numberOfInvitations
#> [1] 0
#> 
#> $editorsContactEmail
#> [1] "[e-mail]"
#> 
#> $editorsContactUrl
#> NULL
#> 
#> $lastSubmissionDate
#> [1] "2023-06-01T20:59:50"
#> 
#> $markedForDeletionDate
#> NULL
#> 
#> $deleteDate
#> NULL
#> 
#> attr(,"class")
#> [1] "ns_meta" "list"

The metadata object includes various details about the form, such as the title, number of submissions, and whether the codebook is valid.

Exploring the Metadata Object

The metadata object is a structured list with useful information about the form. You can directly access individual fields in the metadata object as you would with any list.

Example: Access Specific Metadata Fields

# Access the title of the form
form_meta$title
#> [1] "API test form"

# Check the number of submissions
num_submissions <- form_meta$numberOfSubmissions
print(paste("Number of submissions:", num_submissions))
#> [1] "Number of submissions: 3"

# Check if the form is open
is_open <- form_meta$isOpen
print(paste("Is the form open?:", is_open))
#> [1] "Is the form open?: FALSE"

Saving Metadata to a File: ns_write_meta

The metadata retrieved using ns_get_meta can be saved to a file for safe keeping or further use. The ns_write_meta function writes the metadata into a JSON file, preserving all its information in a structured format.

Example: Save Metadata as a JSON File

# Replace with your desired file path
output_path <- "meta_110000.json"

# Save the metadata to the specified path
ns_write_meta(form_meta, output_path)

Example: Save Metadata to a Custom Path

If your file doesn’t have a .json extension, the function will automatically append it to the file name.

# Save to a file without .json extension
ns_write_meta(form_meta, "meta_file")

# The file will be saved as "meta_file.json"

Example: Use Custom JSON Formatting Options

The ns_write_meta function supports any additional arguments passed to the jsonlite::write_json function. For example, you can specify pretty = TRUE for a more human-readable format.

# Save the metadata in a pretty-printed JSON file
ns_write_meta(form_meta, "pretty_meta.json", pretty = TRUE)

LCBC-UiO/nettskjemar documentation built on April 11, 2025, 11:01 p.m.