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] "athanasm@uio.no"
#> 
#> $modifiedBy$name
#> [1] "Athanasia Monika Mowinckel"
#> 
#> $modifiedBy$email
#> [1] "a.m.mowinckel@psykologi.uio.no"
#> 
#> $modifiedBy$type
#> [1] "LOCAL"
#> 
#> 
#> $isOpen
#> [1] FALSE
#> 
#> $deliveryDestination
#> [1] "DATABASE"
#> 
#> $projectName
#> NULL
#> 
#> $numberOfPostponedSubmissions
#> [1] 0
#> 
#> $numberOfSubmissions
#> [1] 3
#> 
#> $numberOfInvitations
#> [1] 0
#> 
#> $editorsContactEmail
#> [1] "a.m.mowinckel@psykologi.uio.no"
#> 
#> $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)

Working with Nettskjema Form Metadata