# Working with Nettskjema Form Metadata

# 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-09-08T16:57:36"
    #>
    #> $modifiedBy
    #> $modifiedBy$personId
    #> [1] 3439404
    #>
    #> $modifiedBy$username
    #> [1] "ccda25ce-8256-4c6f-ba71-7a4357dc6caf@apiclient"
    #>
    #> $modifiedBy$name
    #> [1] "nettskjemar"
    #>
    #> $modifiedBy$email
    #> [1] "athanasm@uio.no"
    #>
    #> $modifiedBy$type
    #> [1] "API_CLIENT"
    #>
    #>
    #> $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
    #>
    #> $receiptText
    #> 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")
    #> ℹ Switching file extension to .json

    # 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
    )