---
title: "Nettskjema Attachments: Download and Save"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Nettskjema Attachments}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



# Overview

Nettskjema allows users to upload attachments with their form submissions. This vignette explains how to use the functions provided in this package to list, retrieve, and save these attachments efficiently.

# Listing Attachments

Before downloading any attachments, it's useful to list the available files.

## Listing attachments for a specific submission

Each submission ID may have associated attachments. Use `ns_list_submission_attachments()` to retrieve information about the available attachments.


``` r
library(nettskjemar)
# Example: List attachments for a specific submission
submission_id <- 27685292
ns_list_submission_attachments(submission_id)
#>   submissionId  answerId elementId
#> 1     27685292 158263134   1641713
#>   externalElementId textAnswer
#> 1      attachment_1  sølvi.png
#>   answerAttachmentId  filename
#> 1             538819 sølvi.png
#>   mediaType   size elementType
#> 1 image/png 628613  ATTACHMENT
#>   attachment.answerAttachmentId
#> 1                        538819
#>   attachment.filename
#> 1           sølvi.png
#>   attachment.mediaType
#> 1            image/png
#>   attachment.size counter
#> 1          628613       1
```

This function returns a `data.frame` with details such as the attachment ID, original filename, and standardized filename.

## Listing all attachments for a form

To list all attachments across multiple submissions for a form, use `ns_list_form_attachments()`.


``` r
# Example: List attachments for an entire form
formid <- 123823
ns_list_form_attachments(formid)
#>    formid formId submissionId
#> 16 123823 123823     27685292
#> 32 123823 123823     27685302
#>     answerId elementId
#> 16 158263134   1641713
#> 32 158263185   3525020
#>    externalElementId  textAnswer
#> 16      attachment_1   sølvi.png
#> 32      attachment_2 marius.jpeg
#>    answerOptionIds
#> 16                
#> 32                
#>    externalAnswerOptionIds
#> 16                        
#> 32                        
#>    elementType         createdDate
#> 16  ATTACHMENT 2023-06-01T20:57:15
#> 32  ATTACHMENT 2023-06-01T20:58:33
#>           modifiedDate subElementId
#> 16 2023-06-01T20:57:15           NA
#> 32 2023-06-01T20:58:33           NA
#>    answerAttachmentId    filename
#> 16             538819   sølvi.png
#> 32             538820 marius.jpeg
#>     mediaType   size
#> 16  image/png 628613
#> 32 image/jpeg  89494
#>    attachment.answerAttachmentId
#> 16                        538819
#> 32                        538820
#>    attachment.filename
#> 16           sølvi.png
#> 32         marius.jpeg
#>    attachment.mediaType
#> 16            image/png
#> 32           image/jpeg
#>    attachment.size counter
#> 16          628613       1
#> 32           89494       1
```

# Downloading Attachments

Once you have identified the attachments, you can download them using `ns_get_attachment()`.

```r
# Example: Download a single attachment
attachment_id <- "12345"
ns_get_attachment(attachment_id, path = "downloaded_file.pdf")
```

If `path` is not provided, the function returns the response object without saving the file.

# Saving All Attachments

## For a Single Submission

Use `ns_get_submission_attachments()` to download and save all attachments associated with a single submission.

```r
# Example: Save all attachments for a submission
ns_get_submission_attachments(submission_id)
```

This function supports two filename conventions:

- **"standardized"** (default): Creates filenames based on submission ID and a counter.
- **"original"**: Uses the filenames as they were uploaded.

To save attachments using the original filenames:

```r
ns_get_submission_attachments(submission_id, filenames = "original")
```

You can also specify an output directory:

```r
ns_get_submission_attachments(submission_id, output_dir = "my_attachments/")
```

## For an Entire Form

To download and save all attachments from a form:

```r
ns_get_form_attachments(formid)
```

As with submission attachments, you can specify a filename format and output directory:

```r
ns_get_form_attachments(formid, filenames = "original", output_dir = "all_attachments/")
```

# Summary

This vignette demonstrated how to:
- List attachments for submissions and forms.
- Retrieve individual attachments.
- Save attachments using different naming conventions.

By using these functions, you can efficiently manage Nettskjema file attachments within your R workflow.

