From cc65c57e52f8ba85cbb7d681ca5261ac77d4a87d Mon Sep 17 00:00:00 2001
From: alicebyers5 <alice.byers@gov.scot>
Date: Tue, 12 Mar 2024 16:21:43 +0000
Subject: [PATCH] Add FAQ vignette

---
 .gitignore                    |  1 +
 DESCRIPTION                   |  3 +++
 R/bypass_2fa.R                |  9 +++++++--
 man/allow_bypass_2fa.Rd       |  3 ++-
 man/participant_bypass_2fa.Rd |  7 +++----
 vignettes/.gitignore          |  2 ++
 vignettes/faqs.Rmd            | 29 +++++++++++++++++++++++++++++
 7 files changed, 47 insertions(+), 7 deletions(-)
 create mode 100644 vignettes/.gitignore
 create mode 100644 vignettes/faqs.Rmd

diff --git a/.gitignore b/.gitignore
index 234f028..0d7f03b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 .RData
 .Ruserdata
 docs
+inst/doc
diff --git a/DESCRIPTION b/DESCRIPTION
index 561f0fe..25217ac 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -21,6 +21,9 @@ Imports:
     rlang
 Suggests: 
     httptest2,
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0),
     withr
 Config/testthat/edition: 3
+VignetteBuilder: knitr
diff --git a/R/bypass_2fa.R b/R/bypass_2fa.R
index 29ffedc..2cc171c 100644
--- a/R/bypass_2fa.R
+++ b/R/bypass_2fa.R
@@ -1,5 +1,8 @@
 #' Allow/disallow bypassing of two factor authentication for workgroup
 #'
+#' @description More information on two factor authentication can be found in
+#' `vignette("faqs")`.
+#'
 #' @param workgroup_uuid Workgroup UUID
 #' @param allow_bypass Logical to indicate whether the workgroup should allow
 #' selected participants to bypass two step workspace verification.
@@ -32,14 +35,16 @@ allow_bypass_2fa <- function(workgroup_uuid,
 
 #' Allow/disallow bypassing of two factor authentication for participant
 #'
+#' @description Note that this setting can only be updated by a workspace owner.
+#' More information on two factor authentication can be found in
+#' `vignette("faqs")`.
+#'
 #' @param participant_uuid Participant UUID (note that this is different to the
 #' user UUID)
 #' @param allow_bypass Logical to indicate whether the participant should be
 #' able to bypass two step verification for workspace.
 #' @inheritParams objectiveR
 #'
-#' @details Note: This setting can only be updated by a workspace owner.
-#'
 #' @export
 
 participant_bypass_2fa <- function(participant_uuid,
diff --git a/man/allow_bypass_2fa.Rd b/man/allow_bypass_2fa.Rd
index 1e834df..30bab81 100644
--- a/man/allow_bypass_2fa.Rd
+++ b/man/allow_bypass_2fa.Rd
@@ -15,5 +15,6 @@ selected participants to bypass two step workspace verification.}
 \item{use_proxy}{Logical to indicate whether to use proxy}
 }
 \description{
-Allow/disallow bypassing of two factor authentication for workgroup
+More information on two factor authentication can be found in
+\code{vignette("faqs")}.
 }
diff --git a/man/participant_bypass_2fa.Rd b/man/participant_bypass_2fa.Rd
index 9143c4e..9cde386 100644
--- a/man/participant_bypass_2fa.Rd
+++ b/man/participant_bypass_2fa.Rd
@@ -20,8 +20,7 @@ able to bypass two step verification for workspace.}
 \item{use_proxy}{Logical to indicate whether to use proxy}
 }
 \description{
-Allow/disallow bypassing of two factor authentication for participant
-}
-\details{
-Note: This setting can only be updated by a workspace owner.
+Note that this setting can only be updated by a workspace owner.
+More information on two factor authentication can be found in
+\code{vignette("faqs")}.
 }
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
new file mode 100644
index 0000000..097b241
--- /dev/null
+++ b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/faqs.Rmd b/vignettes/faqs.Rmd
new file mode 100644
index 0000000..af54283
--- /dev/null
+++ b/vignettes/faqs.Rmd
@@ -0,0 +1,29 @@
+---
+title: "Frequently Asked Questions"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Frequently Asked Questions}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## What is the difference between users and participants?
+
+A user is an individual using Objective Connect. A participant is a user in a particular workspace. For example, a person using Objective Connect will have a User UUID associated with them, and also a Participant UUID for each individual workspace they are a member of. 
+
+A user can get their User UUID by running `my_user_id()`. A user can find their participant UUID for a particular workspace using `participants()`.
+
+
+## How does two factor authentication (2FA) work?
+
+(Note: this is sometimes also referred to as 'two step verification'.)
+
+Where workspaces have 2FA enabled, users cannot use the API unless they have been given permission to bypass this. Permission to bypass 2FA is given at a workspace level, and can only be granted by the workspace owner.
+
+Firstly, permission must be given at a workgroup level to allow bypassing permissions to be granted for workspaces within it. This can be done using `allow_bypass_2fa()`.
+
+Once this has been allowed, bypassing can be granted for individual participants in a workspace using `participant_bypass_2fa()`. 
+
+Both of these functions also allow for bypassing to be disallowed using `allow_bypass = FALSE`.
+
+To check the status of bypassing 2FA for participants in a workspace, use `participants()`.