Package {SurveySolutionsAPIv2}

SurveySolutionsAPIv2: Comprehensive API Access to Your 'Survey Solutions' Server Using 'httr2'

Description

A comprehensive suite of functions for interfacing with the 'Survey Solutions' APIs (https://demo.mysurvey.solutions/apidocs/index.html and https://docs.mysurvey.solutions/). It supports all the current POST, GET, and PATCH requests of the 'REST' API and extends its capabilities by integrating selected 'GraphQL' API queries and mutations when 'REST' API equivalents are not available. Designed for ease of use, it includes several convenience functions to streamline operations. The package ensures that data retrieved from the API is automatically transformed into a single, easy-to-use data frame or data table, optimizing it for subsequent analysis and processing. Additionally, it is specifically designed to facilitate seamless integration into 'shiny' applications, enhancing the interactive web application development experience. Built on the robust 'httr2' package, this version supersedes the previous 'httr'-based implementation. Recognizing the needs of large-scale data operations such as censuses, the package also incorporates features for parallel processing, enhancing its efficiency and scalability.

Author(s)

Maintainer: Michael Wild michael.wild@me.com [copyright holder]

See Also

Useful links:

• https://michael-cw.github.io/SurveySolutionsAPIv2/

• https://github.com/michael-cw/SurveySolutionsAPIv2

• Report bugs at https://github.com/michael-cw/SurveySolutionsAPIv2/issues

User Classes & Methods

Description

Users class extends the data.table class to include relevant methods

Usage

UserClass(x, ...)

Arguments

Value

An object of class UserClass (inheriting from data.table)

Examples

usr_list <- list(Users = data.frame(UserName = "interviewer1", Role = "Interviewer"))
uc <- UserClass(usr_list)
is.UserClass(uc)

Assignment Classes & Methods

Description

Assignments class extends the data.table class to include relevant methods

Usage

assignmentClass(x, ...)

Arguments

Details

The assignmentClass is a data.table extended with additional attributes and methods, depending on the api endpoint. The assignmentClass is used as input for the getinfo function.

Value

assignmentClass object

Examples

ass_list <- list(Assignments = data.frame(Id = 1, ResponsibleName = "interviewer1"))
ac <- assignmentClass(ass_list)
is.assignmentClass(ac)

S3 method to create a box plot of numeric variables for an exportClass object

Description

This function generates a box plot for the numeric variables in a exportClass object.

Usage

boxplot_summary(x, useGGplot2 = FALSE, ...)

## S3 method for class 'exportClass'
boxplot_summary(x, useGGplot2 = FALSE, ...)

Arguments

Value

A box plot visualizing the numeric variables.

A ggplot2 plot object if useGGplot2 is TRUE, or a base R boxplot list invisibly otherwise

Examples

dt <- data.table::data.table(q1 = 1:10, q2 = 11:20)
vlabs <- data.table::data.table(
  VariableName = c("q1", "q2"),
  QuestionText = c("Question 1", "Question 2")
)
ec <- exportClass(dt, varLabels = vlabs)
boxplot_summary(ec)

Create, update or delete a calendar event

Description

Create, update or delete a calendar event for one or several assignments or interviews.

Usage

suso_createCALEV(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = NULL,
  AssId = NULL,
  comment = NULL,
  startDate = NULL,
  startTime = NULL,
  startTZ = "UTC"
)

suso_updateCALEV(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  publicKey = NULL,
  comment = NULL,
  startDate = NULL,
  startTime = NULL,
  startTZ = "UTC"
)

suso_delCALEV(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  publicKey = NULL
)

Arguments

Details

This function creates a calendar event either for one or several assignments or one or several interviews. Either one of AssID or intID must not be NULL. If length(AssID) or length(AssID) is greater 1, then startDate, startTime and startTZ must either be each of length 1 (same event for all) or of the same length, allowing for multiple events with different times.

Value

a data.table with the created event(s).

Functions

• suso_createCALEV(): add a calendar event

• suso_updateCALEV(): update a calendar event

• suso_delCALEV(): delete a calendar event

Examples

# add single calendar event to assignment
calEvass<-suso_createCALEV(AssId = 268,
                           startDate = "2024-01-17",
                           startTime = "10:40:00")

# update single event
calEvup<-suso_updateCALEV(publicKey = calEvass$publicKey[1],
                         startDate = "2024-01-18",
                        startTime = "10:40:00")

# delete single event
calEvDel<-suso_delCALEV(publicKey = calEvup$publicKey[1])


# add calendar event to multiple assignments
calEvass<-suso_createCALEV(AssId = 55:60,
                           startDate = "2024-01-18",
                           startTime = "11:40:00")
# delete multiple calendar events
calEvDel<-suso_delCALEV(publicKey = calEvass$publicKey)

Export Classes & Methods

Description

Export class extends the data.table class to include relevant methods

Usage

exportClass(x, varLabels, ..., type = "main")

Arguments

Value

An object of class exportClass (inheriting from data.table)

Examples

dt <- data.table::data.table(q1 = 1:5)
vlabs <- data.table::data.table(VariableName = "q1", QuestionText = "Question 1")
ec <- exportClass(dt, varLabels = vlabs)
is.exportClass(ec)

assignmentClass methods

Description

getinfo allows you to retrieve relevant additional information from the assignmentClass, object depending on the api endpoint.

Usage

getinfo(obj, arg)

## S3 method for class 'assignmentClass'
getinfo(obj, arg)

## S3 method for class 'exportClass'
getinfo(obj, arg)

## S3 method for class 'UserClass'
getinfo(obj, arg)

Arguments

Details

To retrieve all availalbe arguments use arg="arglist"

Value

the specific attribute

Examples

ass_list <- list(
  Assignments = data.frame(Id = 1, ResponsibleName = "interviewer1"),
  ResponsibleId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
)
asslist <- assignmentClass(ass_list)

# retrieve the uid of the person responsible
getinfo(asslist, "responsibleid")

# see all available attribute names
getinfo(asslist, "arglist")

Function to check if an object is of class UserClass

Description

Function to check if an object is of class UserClass

Usage

is.UserClass(x)

Arguments

Value

TRUE if object is of class UserClass

Examples

uc <- UserClass(list(Users = data.frame(UserName = "interviewer1")))
is.UserClass(uc)
is.UserClass(data.frame())

Function to check if an object is of class assignmentClass

Description

Function to check if an object is of class assignmentClass

Usage

is.assignmentClass(x)

Arguments

Value

TRUE if object is of class assignmentClass

Examples

ac <- assignmentClass(list(Assignments = data.frame(Id = 1)))
is.assignmentClass(ac)
is.assignmentClass(data.frame())

Function to check if an object is of class exportClass

Description

Function to check if an object is of class exportClass

Usage

is.exportClass(x)

Arguments

Value

TRUE if object is of class exportClass

Examples

dt <- data.table::data.table(q1 = 1:5)
vlabs <- data.table::data.table(VariableName = "q1", QuestionText = "Question 1")
ec <- exportClass(dt, varLabels = vlabs)
is.exportClass(ec)
is.exportClass(dt)

S3 method to create a summary table of numeric variables for an exportClass object

Description

This function generates a summary table of numeric variables in an exportClass object.

Usage

summaryTable(x, ...)

## S3 method for class 'exportClass'
summaryTable(x, ..., includeFactors = FALSE, useDT = TRUE, DTstyle = TRUE)

## S3 method for class 'paradata'
summaryTable(x, ..., useDT = TRUE, DTstyle = TRUE)

Arguments

Details

• For the main data: The table includes statistics such as mean, standard deviation, maximum, minimum, and total count as well as count of NA values.

• For paradata: Different summary tables for response times, duration times etc. see examples.

Value

A DataTable (DT) object (HTML table) displaying the summary statistics, if useDT = TRUE, and a plain data.table otherwise.

Examples

questlist<-suso_getQuestDetails()

### MAIN DATA
export <- suso_export(questID = questlist$QuestionnaireId[7],
                      version = questlist$Version[7],
                      combineFiles = TRUE,
                      reloadTimeDiff = 20)

# Create a summary table
summary_data_table <- summaryTable(export)

# Display the summary table
summary_data_table


dt <- data.table::data.table(q1 = 1:10, q2 = 11:20)
vlabs <- data.table::data.table(
  VariableName = c("q1", "q2"),
  QuestionText = c("Question 1", "Question 2")
)
ec <- exportClass(dt, varLabels = vlabs)
summaryTable(ec, useDT = FALSE)



questlist<-suso_getQuestDetails()

### PARADATA
# 1. Pre-Processed tables created during export
para<-suso_export_paradata(questID = questlist$QuestionnaireId[1],
                          version = questlist$Version[1], reloadTimeDiff = 24,
                          workStatus = "All", asList = FALSE, onlyActiveEvents = TRUE)

# Create a summary table of all event counts by action (includes always passive and active one)
actions <- summaryTable(para, "action")

# Create a summary table of all event counts by user
users <- summaryTable(para, "user")

# 2. Tables created on request for response times
# grouped by variables, i.e. type, VariableName, responsible etc.

# Create a summary table of the average response time by variable
resptime_var <- summaryTable(para, "VariableName")

# Create a summary table of the average response time by question type
resptime_type <- summaryTable(para, "type")

# Create a summary table of the average response time by user
resptime_user <- summaryTable(para, "responsible")

S3 method to create a summary table of users for UserClass object

Description

This function generates a summary table of Users.

Usage

## S3 method for class 'UserClass'
summaryTable(x, includeFactors = FALSE, useDT = TRUE, DTstyle = TRUE, ...)

Arguments

Details

For very large tables you will get a warning when rendering in Rstudio, however in a shiny app you have the option to use server side processing: DT::renderDataTable(..., server = TRUE). In cases where future and future.apply is available on your system the additional information will be retrieved in parallel (multisession), otherwise sequential. For large data sets parallel processing is recommended. Furthermore when processing in parallel, a progress bar for shiny applications is included and active when running in a shiny application, otherwise a cli progress bar will be displayed.

Value

A DataTable (DT) object (HTML table) if useDT = TRUE, and a plain data.table otherwise. The table contains all users core data, plus completed and assigned counts,

Examples

allintprim<-suso_getINT(workspace = "primary")

# Create a summary table
summary_data_table <- summaryTable(allintprim)

# Display the summary table
summary_data_table

Configuration options used for the SurveySolutionsAPIv2 package

Description

Below are the options and environment variables, that are used by the SurveySolutionsAPIv2 package.

Value

No return value, called for documentation on package configuration options.

Available options

Bellow is a list of options, with their default values.

• suso.url.http if TRUE allows for non SSL connections, which is generally not recommended for publicly facing set-ups, however may be required for testing purposes.

• suso.maxpar.req specifies the maximum number of parallel requests, default is 100.

• suso.maxpar.con specifies the maximum number of parallel connections, and must always be equal or greater than suso.maxpar.req, default is 100.

• suso.para.break specifies the maximum response time to be considered as a break in seconds, default 120.

• suso.para.tz specifies the local timezone for the processing of time values, default is Sys.timezone().

• suso.para.maxcore specifies the number of cores used for parallel processing, default is data.table::getDTthreads()-2.

• suso.para.plan specifies plane used for parallel processing, default is multisession. For details please see future::plan

• suso.useshiny should R shiny elements be used if running in shiny app, default is TRUE. Currently implemented for:

  • suso_PwCheck, providing feedback for credentials check, the suso.pwcheck.message_succ and suso.pwcheck.message_fail can be modified.

  • suso_export, providing different progress bars for interactive (cli) use and in shiny app use (shiny::withProgress, to also customize the progress bar message, i.e. in a different language, the suso.progressbar.message can be modified.

  • TBD

Examples

# Inspect the current maximum parallel requests option
getOption("suso.maxpar.req", default = 100)

# Inspect the timezone option
getOption("suso.para.tz", default = Sys.timezone())

Utility function to check if credentials are correct

Description

This function returns a 200 status code if credentials are correct and a 400 code otherwise.

Usage

suso_PwCheck(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Details

If the app runs interactively, status is printed to the console, if it runs in a shiny app, a status notification will be shown, if option suso.useshiny is TRUE.

Value

200 code if correct, 400 if incorrect.

Examples

suso_PwCheck(
  server = "https://demo.mysurvey.solutions",
  apiUser = "api_user",
  apiPass = "password123"
)

Survey Solutions API call (un-) archive user

Description

(Un-)Archive user

Usage

suso_archUSR(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  user_id = NULL,
  archive = FALSE,
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Value

A data.table containing the user ID, archive timestamp, and archive status.

Examples

# you can archive a user by archive=T
suso_archUSR(
          workspace = "myworkspace",
          user_id = "xxxx-xxxx-xxxx-xxx",
          archive = TRUE
          )
# and unarchive a user by archive=F
suso_archUSR(
          workspace = "myworkspace",
          user_id = "xxxx-xxxx-xxxx-xxx",
          archive = FALSE
          )

Assign interview to interviewer or supervisor

Description

Reassigns an interview to a specified interviewer or supervisor.

Usage

suso_assignInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = "",
  userId = NULL,
  userName = NULL,
  supervisor = FALSE
)

Arguments

Value

A data.table indicating the assignment status.

Examples

suso_assignInterview(
  intID = "11111111-2222-3333-4444-555555555555",
  userName = "interviewer01"
)

Survey Solutions API call to assign workspace (!! WORKS ONLY WITH ADMIN CREDENTIALS)

Description

suso_assignWorkspace Allows you to assign a workspace to a specific user or a group of users. For more details please read https://docs.mysurvey.solutions/headquarters/accounts/workspaces/. To run this command you require admin credentials and not the regular API user credentials.

Usage

suso_assignWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  assign_workspace = NULL,
  keep_old_workspace = TRUE,
  uid = NULL,
  sv_id = NULL
)

Arguments

Details

When keep_old_workspace=FALSE the user will only be assigned to the new workspace, otherwise the existing ones will be added, if the former is the case, then you need to make sure, that all assignments, interviews, team members etc. are cleared in the old workspace. Be aware, that for using this call you require admin credentials, and not the regular API user credentials.

Value

If successful, returns a data.table with the details as well as the Status message workspace list updated.

A data.table containing the assignment update status.

Examples

## Use Admin Credentials!

# Assign a new workspace to a single user, keep old one(s)
suso_assignWorkspace(
          assign_workspace = "myworkspace1",
          uid = "xxx-xxx-xxx-xxx-xxx",
          sv_id = "xxx-xxx-xxx-xxx-xxx",
          apiUser = "xxxxxx",
          apiPass = "xxxxxx",
          keep_old_workspace = TRUE
          )

# Assign a new workspace to a single user, drop old one(s)
suso_assignWorkspace(
          assign_workspace = "myworkspace1",
          uid = "xxx-xxx-xxx-xxx-xxx",
          sv_id = "xxx-xxx-xxx-xxx-xxx",
          apiUser = "xxxxxx",
          apiPass = "xxxxxx",
          keep_old_workspace = TRUE
          )

# Assign all supervisors from on workspace to a new one, keep old one
allsv<-suso_getSV(workspace = "old")
suso_assignWorkspace(
          assign_workspace = "new",
          uid = allsv$UserId,
          sv_id = allsv$UserId,
          apiUser = "xxxxxx",
          apiPass = "xxxxxx",
          keep_old_workspace = TRUE
          )

# Assign all interviewers from one workspace to a new one, keep old one
allint<-suso_getINT(workspace = "old")
suso_assignWorkspace(
          assign_workspace = "new",
          uid = allint$UserId,
          sv_id = allint$sv_id,
          apiUser = "xxxxxx",
          apiPass = "xxxxxx",
          keep_old_workspace = TRUE
          )

Survey Solutions API call to cancel an export process

Description

Cancels an ongoing export process or deletes an export process by ID.

Usage

suso_cancelExport(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  jobid = NULL
)

Arguments

Value

A data.table containing the canceled export process information.

Examples

# Cancel an ongoing export process
suso_cancelExport(jobid = 123)

Clear Credentials

Description

Clears all the API credentials

Usage

suso_clear_keys()

Value

Invisible NULL.

Examples

suso_clear_keys()

Leave a comment on a question in an interview

Description

Leaves a comment on a question using either the questionId or the questionnaire variable name.

Usage

suso_commentInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = "",
  comment = "",
  questionId = NULL,
  variable = NULL,
  rosterVector = NULL
)

Arguments

Value

A data.table indicating the comment status.

Examples

suso_commentInterview(
  intID = "11111111-2222-3333-4444-555555555555",
  variable = "age",
  comment = "Please verify respondent age."
)

Survey Solutions API call for Assignment Creation

Description

Creates assignment with ID data. Uses the httr2 package, and specifically the req_perform_parallel function. Compared to a sequential approach, this significantly and safely decreases the overall processing time. Adjust relevant option suso.maxpar.req for number of parallel processes to match the capacity of your system (default is 100 parallel requests).

Usage

suso_createASS(
  df = NULL,
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL
)

Arguments

Details

Dataframe needs to be provided with columns for ID data, matching the required type, as well as Quantity and ResponsibleName. Return value is a data.table, with the ID data, if successful.

Value

Returns a data.table with a row for each assignment, containing identifying data, responsible id etc.

Examples

# get the list of questionnaires in the workspace
questlist<-suso_getQuestDetails()


# Create the assignments with your upload data
asslist <- suso_createASS(df = IdentifyingData,
                          questID = questlist$QuestionnaireId[1],
                          version = questlist$Version[1])

Survey Solutions API call for User Creation

Description

Creates Survey Solutions users (observers, interviewers or supervisors).

Usage

suso_createUSER(
  userlist = NULL,
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  showUser = FALSE
)

Arguments

Details

Dataframe needs to be provided with the mandatory columns for user creation which are: Role, UserName, Password and Supervisor (in case of interviewer), optional you can also provide FullName, PhoneNumber and Email. Return value is a data.table, which includes the user information as well as the response's status code. Important is also that the UserName and Password are provided in the required format.

Value

A data.table containing the user information and HTTP response status code for each created user.

Examples

new_users <- data.frame(
  Role = "Interviewer",
  UserName = "interviewer01",
  Password = "Password123!",
  Supervisor = "supervisor01"
)
suso_createUSER(userlist = new_users)

Survey Solutions API call to create workspace

Description

suso_createWorkspace Allows you to create a workspace with a specific system name and display name. For more details please read https://docs.mysurvey.solutions/headquarters/accounts/workspaces/. To run this command you require admin credentials.

Usage

suso_createWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  new_workspace = NULL,
  displayName = NULL
)

Arguments

Details

Be aware, that for using this call you require the ADMIN credentials, and not the regular API user credentials.

Value

A data.table containing the created workspace information.

Examples

# Use Admin Credentials!
suso_createWorkspace(
          new_workspace = "myworkspace1",
          displayName = "SpecialWorkspace",
          apiUser = "xxxxxx",
          apiPass = "xxxxxx")

Delete an interview

Description

Deletes an interview from the Survey Solutions server.

Usage

suso_deleteInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = ""
)

Arguments

Value

A data.table indicating the deletion status.

Examples

suso_deleteInterview(intID = "11111111-2222-3333-4444-555555555555")

Delete a workspace

Description

Deletes a specified workspace. Accessible only to administrator.

Usage

suso_deleteWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = NULL
)

Arguments

Value

A data.table indicating the deletion status.

Examples

suso_deleteWorkspace(workspace = "old_ws")

Delete Map from Server

Description

Allows the user to delete maps stored on the server.

Usage

suso_deletemap(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  fileName = NULL
)

Arguments

Value

A data.table containing the deleted map details (file name, shape type, and import timestamp).

Examples

suso_deletemap(
  workspace = "myworkspace",
  fileName = "Lat9264Lon625_ALL.tif"
)

Enable or disable a workspace

Description

Enables or disables access to a specified workspace. Accessible only to administrator.

Usage

suso_enableWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = NULL,
  enable = TRUE
)

Arguments

Value

A data.table indicating the enable/disable status.

Examples

# Enable workspace
suso_enableWorkspace(workspace = "my_ws", enable = TRUE)
# Disable workspace
suso_enableWorkspace(workspace = "my_ws", enable = FALSE)

Survey Solutions API call to generate and download the data

Description

Generates and downloads the data from your Survey Solutions server.

Usage

suso_export(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  questID = NULL,
  version = NULL,
  from_date = NULL,
  from_time = "00:00:00",
  to_date = NULL,
  to_time = "23:59:59",
  workStatus = c("All", "SupervisorAssigned", "InterviewerAssigned",
    "RejectedBySupervisor", "Completed", "ApprovedBySupervisor",
    "RejectedByHeadquarters", "ApprovedByHeadquarters"),
  addTranslation = FALSE,
  translationLanguage = NULL,
  reloadTimeDiff = 1,
  inShinyApp = FALSE,
  verbose = FALSE,
  weight_file = NULL,
  process_mapquestions = FALSE,
  combineFiles = TRUE,
  addsysfiles = FALSE
)

Arguments

Details

This API call uses the tab export format and uses information from the included questionnaire document to assign value labels to any factor variables. Currently this is done for single select and multiselect questions. If you export the data with combineFiles = FALSE a list will be returned with the following structure:

• it is returned as a LIST with up to 4 different lists. The list names are:

  • main Contains the top level data, and (if available interviewer comments)

  • R1 All rosters in roster level 1

  • R2 All rosters in roster level 2

  • R3 All rosters in roster level 3

• Number of lists depends on the level of roster nesting

• If process_mapquestions = TRUE is provided, the different lists will also contain an sf object for each spatial variable found at the corresponding main/roster level (multipolygons, multipoints, points and lines), for details see also the sf package.

• All variable names are transformed to lower case and categorical variables are consistently labeled

• List elements are returned as data.tables

• Allows for specification of reload time (i.e. generation of new download file)

• PRESERVES categorical labels and values.

If however, you export the data with combineFiles = TRUE a single data.table containing all the data in wide format will be returned. This is the result of the following processing steps:

• First all roster files are cast into wide format.

• Second the rosters are merged from bottom to top.

• Third the result of the previous step is merged with the main file

The resulting data.table contains value labels for factor variables. If the file path to a weight file is provided, then these will be added too, and is as such ready for analysis.

Value

a single exportClass data.table or a list of exportClass data.tables, see details.

Examples

questlist<-suso_getQuestDetails()

exp<-suso_export(questID = questlist$QuestionnaireId[1],
                 version = questlist$Version[1],
                 workStatus = "All", process_mapquestions = TRUE,
                 combineFiles = TRUE,
                 reloadTimeDiff = 0,
                 translationLanguage = "italian")

Export Survey Solutions paradata

Description

Exports Survey Solutions paradata, and returns either a single exportClass data.table, or a list of data.tables.

Usage

suso_export_paradata(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  questID = NULL,
  version = NULL,
  from_date = NULL,
  from_time = "00:00:00",
  to_date = NULL,
  to_time = "23:59:59",
  workStatus = c("All", "SupervisorAssigned", "InterviewerAssigned",
    "RejectedBySupervisor", "Completed", "ApprovedBySupervisor",
    "RejectedByHeadquarters", "ApprovedByHeadquarters"),
  reloadTimeDiff = 1,
  inShinyApp = FALSE,
  multiCore = NULL,
  onlyActiveEvents = FALSE,
  asList = FALSE,
  allResponses = TRUE,
  gpsVarName = NA,
  verbose = FALSE,
  showProgress = FALSE
)

Arguments

Details

suso_export_paradata returns a data.table. Calculates the response time and separates multiple responses into individual columns. It also creates a variable counter which preserves the sequence of events.

The return value is a list with a separate list element for each event. If any of the variable names contains gps this function also attempts to identify (and extract) the geo-reference location. In case of multiple gps variables, it identifies the first variable, with not all missing values. This in turn facilitates the creation of paradata maps (see vignette on paradata). In addition it also returns all the variables and responses in separate columns and as factors. Exporting onlyActiveEvents substantially decrease processing time. The events may be sufficient for most of the paradata analysis.

To further decrease the processing time, one could set allResponses to FALSE. Doing so will still export all the data, however it will not attempt to extract all responses and setting them to factors.

Value

a single exportClass data.table or a list of data.tables.

Examples

questlist<-suso_getQuestDetails()
# Get a single data.table with response timings,
# only active events,
# and responses are not expanded
para<-suso_export_paradata(questID = questlist$QuestionnaireId[1],
                           version = questlist$Version[1],
                           reloadTimeDiff = 0,
                           workStatus = "All",
                           asList = FALSE,
                           onlyActiveEvents = TRUE,
                           allResponses = FALSE)

# Create a summary table
summary_data_table <- summaryTable(para)

# Display the summary table
summary_data_table

Survey Solutions API call to retrieve all answers for a specific interview

Description

Returns all responses for a specific interview

Usage

suso_getAllAnswerInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = ""
)

Arguments

Value

A data.table containing all answers for the given interview.

Examples

suso_getAllAnswerInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea"
          )

Get all history for a specific interview

Description

Get all history for a specific interview

Usage

suso_getAllHistoryInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = ""
)

Arguments

Value

A data.table containing the history records for the interview.

Examples

suso_getAllHistoryInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea"
          )

Survey Solutions API call to retrieve all interviews for a specific questionnaire

Description

Returns all interviews for the specified questionnaire and the selected status.

Usage

suso_getAllInterviewQuestionnaire(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = "",
  version = 1,
  workStatus = c("Completed", "All", "SupervisorAssigned", "InterviewerAssigned",
    "RejectedBySupervisor", "ApprovedBySupervisor", "RejectedByHeadquarters",
    "ApprovedByHeadquarters")
)

Arguments

Details

ATTENTION: This function only exists for consistency reasons with the original SurveySolutionsAPI package. Under the hood it uses suso_getQuestDetails, which is based on the GraphQL API.

Value

A data.table listing all interviews matching the specified questionnaire and status filter.

Examples

# To get all interviews for a specific questionnaire and a specific status
     suso_getAllInterviewQuestionnaire(
              workspace = "myworkspace",
              questID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
              version = 1,
              workStatus = "InterviewerAssigned"
              )
# or to get all interviews in status completed
     suso_getAllInterviewQuestionnaire(
              workspace = "myworkspace",
              questID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
              version = 1
              )

Survey Solutions API call to list export processes

Description

Retrieves a list of export processes matching specified filters.

Usage

suso_getExportList(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  exportType = NULL,
  interviewStatus = NULL,
  questID = NULL,
  version = NULL,
  exportStatus = NULL,
  hasFile = NULL,
  limit = NULL,
  offset = NULL
)

Arguments

Value

A data.table containing the list of export processes.

Examples

# List all export processes in workspace
exp_list <- suso_getExportList()

Survey Solutions API call to get detailed information about an export process

Description

Retrieves status and details of a single export process by its ID.

Usage

suso_getExportProcess(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  jobid = NULL
)

Arguments

Value

A data.table containing export process details.

Examples

# Get status of export process by jobid
proc_info <- suso_getExportProcess(jobid = 123)

Survey Solutions API call for list of interviewers

Description

Get list of all interviewers by supervisor id, or a list of all interviewers in the workspace.

Usage

suso_getINT(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  sv_id = NULL,
  bigTeam = FALSE
)

Arguments

Value

An object of class UserClass (inheriting from data.table) containing the interviewers.

Examples

# Get all members for a single supervisor
suso_getINT(
          sv_id = "xxxx-xxxx-xxxx-xxx"
          )

# Get all members in the workspace
suso_getINT()

Survey Solutions API call for info on interviewers

Description

Get details of a single interviewer or retrieve the action log

Usage

suso_getINT_info(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  int_id = NULL,
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  log = FALSE,
  startDate = NULL,
  endDate = NULL
)

Arguments

Value

A data.table containing interviewer details or audit logs.

Examples

suso_getINT_info(
          workspace = "myworkspace",
          int_id = "xxxx-xxxx-xxxx-xxx"
          )

Download interview PDF transcript

Description

Downloads the PDF transcript of a completed interview.

Usage

suso_getInterviewPDF(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = "",
  path = NULL
)

Arguments

Value

The file path where the PDF was saved.

Examples

pdf_path <- suso_getInterviewPDF(intID = "11111111-2222-3333-4444-555555555555")

Survey Solutions API call for questionnaire

Description

suso_getQuestDetails implements all Questionnaire related API commands. It allows for different operation types, see details bellow for further clarification.

Usage

suso_getQuestDetails(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL,
  operation.type = c("list", "statuses", "structure", "interviews"),
  include_raw = FALSE,
  AssId = NULL,
  InterviewKey = NULL,
  errorsCount = NULL,
  errosCountFilter = c("lower", "higher", "equal"),
  interviewMode = c("CAPI", "CAWI"),
  notAnsweredCount = NULL,
  notAnsweredCountFilter = c("lower", "higher", "equal"),
  QuestionnaireVariable = NULL,
  ResponsibleName = NULL,
  responsibleRole = c("INTERVIEWER", "SUPERVISOR"),
  workStatus = c("All", "SupervisorAssigned", "InterviewerAssigned",
    "RejectedBySupervisor", "Completed", "ApprovedBySupervisor",
    "RejectedByHeadquarters", "ApprovedByHeadquarters"),
  supervisorName = NULL
)

Arguments

Details

If list is selected, then list of questionnaires is returned.

If statuses is selected, a list of all available questionnaire statuses is returned (deprecated).

In case structure is chosen the return value is a list with four data.table elements:

• List element q contains all questions, rosters etc. with full metadata.

• List element val contains all validations.

• List element v is an alias for val for backward compatibility.

• List element answers contains categorical answer options, codes, and linked questions.

In this way it is straightforward to use the return value for questionnaire manuals and the likes.

In case interviews is selected, a list of all interviews for the specific questionnaire is returned.

Value

Depending on operation.type:

list

A data.table listing all questionnaires on the server.

statuses

A character vector of questionnaire statuses.

structure

A list with four data.tables: q (questions/rosters metadata), val (validations), v (alias for val), and answers (categorical answer options and codes).

interviews

A data.table listing interviews for the specified questionnaire.

Examples

# List all questionnaires on the server
q_list <- suso_getQuestDetails(operation.type = "list")

# Get questionnaire structure (questions, validations, answers)
q_struct <- suso_getQuestDetails(
  questID = q_list$QuestionnaireId[1],
  version = q_list$Version[1],
  operation.type = "structure"
)

Survey Solutions API call for questions and responses from single questionnaire

Description

Returns all questions for a single questionnaire (ONLY if they contain responses). If you require all questions from any questionnaire on the server, use suso_getQuestDetails(..., operation.type = "structure").

Usage

suso_getQuestionsQuestionnaire(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL
)

Arguments

Value

A data.table listing questions with responses for the questionnaire.

Examples

suso_getQuestionsQuestionnaire(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1
)

Survey Solutions API call for list of supervisors

Description

Gets list of supervisors

Usage

suso_getSV(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Value

An object of class UserClass (inheriting from data.table) containing the list of supervisors.

Examples

# receive all supervisors in the workspace
suso_getSV()

Survey Solutions API call for supervisor info

Description

Gets detailed info about a single supervisor by supervisor ID.

Usage

suso_getSV_info(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  sv_id = NULL,
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Value

A data.table containing supervisor details.

Examples

suso_getSV_info(
  workspace = "myworkspace",
  sv_id = "xxxx-xxxx-xxxx-xxx"
)

Survey Solutions API call for questionnaires with statistics

Description

Retrieves the list of questionnaires that have statistics data on the server.

Usage

suso_getStatsQuestionnaires(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Value

A data.table listing questionnaires with statistics.

Examples

suso_getStatsQuestionnaires()

Survey Solutions API call for info on any user

Description

Get any user's info, by either providing the user id, email, or the user name

Usage

suso_getUSR(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  user_id = NULL,
  user_name = NULL,
  user_email = NULL,
  workspace = suso_get_api_key("workspace"),
  token = NULL
)

Arguments

Value

A data.table containing user details.

Examples

suso_getUSR(
          workspace = "myworkspace",
          user_id = "xxxx-xxxx-xxxx-xxx"
          )

Survey Solutions API call for workspace information

Description

suso_getWorkspace allows you to get the list of workspaces, information about individual workspace names as well as workspace statuses. Workspaces as well as Workspaces information can only be accessed, if credentials are eligible. For more details please read https://docs.mysurvey.solutions/headquarters/accounts/workspaces/

Usage

suso_getWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = NULL,
  status = FALSE
)

Arguments

Value

A data.table containing workspace information or status.

Examples

# This assumes, that suso_PwCheck(workspace = "myworkspace") was
# sucessful

# shows all workspaces in the system AND the user has access to
suso_getWorkspace(
          status = FALSE)

# shows details for specific workspace myworkspace
suso_getWorkspace(
          workspace = "myworkspace",
          status = TRUE)

Get credentials

Description

Get API credentials

Usage

suso_get_api_key(api = c("susoServer", "susoUser", "susoPass", "workspace"))

Arguments

Details

Get credentials, used as input in API calls

Value

Character string of the requested credential, or NA if not set.

Examples

suso_get_api_key("susoServer")
suso_get_api_key("workspace")

Survey Solutions API call for assignment list

Description

suso_get_assignments calls the Survey Solutions assignment API

Usage

suso_get_assignments(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  questID = NULL,
  AssId = NULL,
  version = NULL,
  responsibleID = NULL,
  supervisorId = NULL,
  searchBy = NULL,
  status = NULL,
  start = NULL,
  length = NULL,
  ShowArchive = FALSE,
  order.by = c("Id ASC", "Id DESC", "ResponsibleName DESC", "ResponsibleName ASC",
    "InterviewsCount DESC", "InterviewsCount ASC", "Quantity DESC", "Quantity ASC",
    "UpdatedAtUtc DESC", "UpdatedAtUtc ASC", "CreatedAtUtc DESC", "CreatedAtUtc ASC"),
  operations.type = c("assignmentQuantitySettings", "history", "recordAudio")
)

Arguments

Value

Returns an S3 object of assignmentClass. If you select any of the operations types, then no data.frame is returned, the data.table will be NULL, however any information returned from the API can be retrieved by using the getinfo() function with the corresponding arguments.

Examples

# get all assignment for specific workspace
asslist<-suso_get_assignments(
                   workspace = "myworkspace"
                   )
# get all assignment for specific responsible
asslist<-suso_get_assignments(
                   workspace = "myworkspace",
                   responsibleID = "a67d2b82-bf28-40cf-bd1a-7901225c0885"
                   )
# get the overall count
getinfo(asslist, "totalcount")

#get all single assignment details
asslist<-suso_get_assignments(
                   workspace = "myworkspace",
                   AssId = 1
                   )
# retrieve the uid of the person responsible
getinfo(asslist, "responsibleid")

# get the status of the quantitysettings
asslist<-suso_get_assignments(
                   workspace = "myworkspace",
                   AssId = 1,
                   operations.type = "assignmentQuantitySettings")
asslist
# Null data.table (0 rows and 0 cols)

getinfo(asslist, "canchangequantity")
# [1] TRUE

Checks if credentials are present

Description

Helper function

Usage

suso_get_default_key(
  api = c("susoServer", "susoUser", "susoPass", "workspace")
)

Arguments

Value

Character string of the requested credential, or throws error if not set.

Examples

suso_set_key(
  suso_server = "https://demo.mysurvey.solutions",
  suso_user = "api_user",
  suso_password = "password123",
  workspace = "primary"
)
suso_get_default_key("susoServer")
suso_clear_keys()

Survey Solutions API call for Summary Tables

Description

Returns summary tables for individual questions from Survey Solutions statistics. If no responses have been provided, an empty table will be returned.

Usage

suso_get_stats(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL,
  qQuest = "",
  byTeam = TRUE,
  exportType = c("Csv", "Json")
)

Arguments

Value

A data.table containing the summary statistics for the question.

Examples

suso_get_stats(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1,
  qQuest = "age"
)

Get statistics for interview

Description

Fetch statistics for a specific interview, vectorized over interview id (int_id)

Usage

suso_get_stats_interview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = ""
)

Arguments

Value

A data.table containing statistics for the requested interview(s).

Examples

suso_get_stats_interview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea"
          )

Survey Solutions API call for Headquarters Global Notice settings

Description

Allows getting, setting, and removing the global notice displayed in the Survey Solutions Headquarters application.

Usage

suso_globalNotice(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  action = c("get", "set", "delete"),
  message = NULL
)

Arguments

Value

When action = "get", returns a character string with the current notice (or NULL if no notice is set). When action = "set" or "delete", returns TRUE invisibly on success.

Examples

# Get current global notice
suso_globalNotice(action = "get")

# Set a new global notice
suso_globalNotice(action = "set",
                  message = "Maintenance tonight at 22:00 UTC.")

# Delete the global notice
suso_globalNotice(action = "delete")

Survey Solutions API credentials

Description

(this function has been inspired by the googleway package https://github.com/SymbolixAU/googleway, an excellent package to use google geo-spatial API) Retrieves the list of Survey Solutions credentials that have been set.

Usage

suso_keys()

Value

A list of class suso_api containing current Survey Solutions credentials.

Examples

suso_keys()

Assigns/Unassign a map to a user

Description

Allows the user to assign/unassign a map to an interviewer to be used in CAPI data collection.

Usage

suso_mapassign(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  fileName = NULL,
  userName = NULL,
  assignUser = TRUE
)

Arguments

Value

A data.table containing the map assignment details (file name, user name, shape type, and import timestamp).

Examples

suso_mapassign(workspace = "myworkspace",
              fileName = "Lat9264Lon625_ALL.tif",
              userName = "INT0004")

Receive maps currently uploaded to the server

Description

Allows the user to retrieve filtered or unfiltered map data inlcuding map details, like size, assigned users etc..

Usage

suso_mapinfo(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  fileName = NULL,
  importDateUtc = NULL,
  size = NULL,
  users = NULL,
  sortby_filename = NULL,
  sortby_importeddateutc = NULL,
  sortby_size = NULL,
  take = NULL,
  skip = NULL
)

Arguments

Details

Attention: this uses the GraphQL API, not the REST API.

Value

Returns a data.table, with all the maps and additonal information. If multiple users are assigned to a map, the table is expanded, such that there is one user per map.

Examples

suso_mapinfo(workspace = "myworkspace")

Create a Map Report

Description

Allows the user to create a map report with pre-specified parameters.

Usage

suso_mapreport(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL,
  variable = NULL,
  zoom = 1,
  clientMapWidth = 0,
  west = -180,
  east = 180,
  north = 90,
  south = -90,
  assignmentId = NULL,
  clientKey = NULL,
  createdDate = NULL,
  errorsCount = NULL,
  identifyingData = NULL,
  interviewMode = NULL,
  notAnsweredCount = NULL
)

Arguments

Value

A list containing the map report result.

Examples

suso_mapreport(
  workspace = "myworkspace",
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1,
  variable = "gps_loc"
)

Upload map to server

Description

Allows the user to upload a zip file of background maps and boundary files

Usage

suso_mapupload(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  path_to_zip = NULL
)

Arguments

Details

Resources for upload must meet the requirements specified under: https://docs.mysurvey.solutions/headquarters/mapsmanage/map-formats/, Attention: this uses the GraphQL API, not the REST API.

Value

Returns a data.table, with information about the uploaded maps

Examples

# either upload the content of a folder
suso_mapupload(workspace = "myworkspace",
              path_to_zip = "./mapfiles/")

# or a zip file with the files included
suso_mapupload(workspace = "myworkspace",
              path_to_zip = "../mapfiles/maps.zip")

Approve interviews either as supervisor or as headquarter.

Description

Allows you to approve interviews in supervisor or headquarters role, unapprove from headquarters status, as well as to provide a comment (i.e. reason).

Usage

suso_patchApproveInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = "",
  HQ = FALSE,
  hqunapprove = FALSE,
  comment = "Well done!"
)

Arguments

Details

For details please see: https://docs.mysurvey.solutions/headquarters/interviews/survey-workflow/

Value

A data.table containing the status of the approval operation.

Examples

# approve the interview as supervisor
suso_patchApproveInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea"
          )
# approve the interview as headquarters
suso_patchApproveInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
          HQ = TRUE
          )

Reject interviews either as supervisor or as headquarter.

Description

Allows you to reject interviews in supervisor or headquarters role as well as to provide a comment (i.e. reason) for the rejection.

Usage

suso_patchRejectInterview(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  intID = "",
  new_uid = NULL,
  HQ = FALSE,
  comment = "Please check errors and re-submit!"
)

Arguments

Details

For details please see: https://docs.mysurvey.solutions/headquarters/interviews/survey-workflow/

Value

A data.table containing the status of the rejection operation.

Examples

# reject the interview as supervisor
suso_patchRejectInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea"
          )
# reject the interview as headquarters
suso_patchRejectInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
          HQ = TRUE
          )
# reject the interview and provide a comment, so the interviewer knows about the problem
suso_patchRejectInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
          comment = "Too many errors, please check and re-submit!"
          )
# reject the interview to a different user
suso_patchRejectInterview(
          workspace = "myworkspace",
          intID = "dee7705f-d611-4b12-9b97-2b8e5b80c4ea",
          new_uid = "3b0c6e09-d606-4914-9e20-2abc048d5bea"
          )

Survey Solutions API call for questionnaire criticality level setting

Description

Gets or sets the criticality level setting for a specific questionnaire.

Usage

suso_questCriticalityLevel(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL,
  level = NULL
)

Arguments

Value

When level = NULL, returns the current criticality level setting. When level is provided, returns TRUE invisibly upon successful update.

Examples

# Get current criticality level
suso_questCriticalityLevel(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1
)
# Set criticality level to Warn
suso_questCriticalityLevel(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1,
  level = "Warn"
)

Survey Solutions API call for questionnaire audio recording setting

Description

Gets or sets the audio recording setting for a specific questionnaire.

Usage

suso_questRecordAudio(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  workspace = suso_get_api_key("workspace"),
  token = NULL,
  questID = NULL,
  version = NULL,
  enabled = NULL
)

Arguments

Value

When enabled = NULL, returns a list with Enabled (logical) and AudioAuditScope (character vector). When enabled is provided, returns TRUE invisibly upon successful update.

Examples

# Get current audio recording setting
suso_questRecordAudio(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1
)
# Enable audio recording
suso_questRecordAudio(
  questID = "11111111-2222-3333-4444-555555555555",
  version = 1,
  enabled = TRUE
)

Survey Solutions API call for assignment manipulation

Description

suso_set_assignments allows to (re-)assign, change limits or audio recording settings, as well as archiving/unarchive, downsizing, changing status/target area, and closing assignments.

Usage

suso_set_assignments(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = suso_get_api_key("workspace"),
  AssId = NULL,
  payload = NULL,
  operations.type = c("recordAudio", "archive", "assign", "changeQuantity", "close",
    "unarchive", "downsize", "changeStatus", "changeTargetArea")
)

Arguments

Details

If operations.type is recordAudio, TRUE/FALSE is required as payload. If it is archive, unarchive, close, or downsize, no payload is required. If it is assign the payload must be the user ID (UUID) or username of the new responsible person (character, or data.frame/list with Responsible). If it is changeQuantity the payload must be the new integer number of assignments (-1 for unlimited). If it is changeStatus the payload must be the new status string (e.g. "Closed", "Deleted") or a named list with Status and optional Comment. If it is changeTargetArea the payload must be the new target area string.

Value

Returns an S3 object of assignmentClass

Examples

# (re-)assign existing assignment by UUID, username, or data.frame
asslist<-suso_set_assignments(
                   workspace = "myworkspace",
                   AssId = 10,
                   payload = "43f3d2bd-7959-4706-97ae-2653b5685c9e",
                   operations.type = "assign"
                   )
asslist<-suso_set_assignments(
                   workspace = "myworkspace",
                   AssId = 10,
                   payload = data.frame(Responsible = "interviewer01"),
                   operations.type = "assign"
                   )
# downsize assignment
asslist<-suso_set_assignments(
                   workspace = "myworkspace",
                   AssId = 10,
                   operations.type = "downsize"
                   )

Set all credentials at once

Description

Sets API credentials so it's available for all API calls. See details

Usage

suso_set_key(
  suso_server = "",
  suso_user = "",
  suso_password = "",
  workspace = NULL,
  suso_token = ""
)

Arguments

Details

Use suso_set_key to make API keys available for all the suso_ functions, so you don't need to specify the credentials parameter within those functions. The server address can be provided with or without https:\ suffix, nevertheless if it is missing, then the suffix will be added. For testing purposes it also allows for http connections, however for publicly accessible servers we do not recommend unencrypted connections.

In case suso_token is provided, only token authentication will be attempted. For details on token authentication in Survey Solutions please see https://docs.mysurvey.solutions/headquarters/accounts/token-based-authentication/.

Value

Invisible NULL.

Examples

suso_set_key(
  suso_server = "https://demo.mysurvey.solutions",
  suso_user = "api_user",
  suso_password = "password123",
  workspace = "primary"
)
suso_clear_keys()

Convenience Function to modify the maximum number of parallel requests option

Description

This function allows to modify the maximum number of parallel requests suso.maxpar.req in a single call. It also checks the maximum number of parallel connections, and if lower than the number of requests max_req then also sets the suso.maxpar.con option to max_req.

Usage

suso_set_maxpar_req(max_req = 100)

Arguments

Value

Invisible NULL.

Examples

# Set maximum parallel requests to 50
suso_set_maxpar_req(50)
# Reset back to default
suso_set_maxpar_req(100)

Convenience functions to modify user notification text

Description

These functions allow the user to customize certain notifications and messages when used in shiny apps.

Usage

suso_set_pwcheck_mess(mess_succ = NULL, mess_fail = NULL)

suso_set_prog_mess(mess = NULL)

Arguments

Value

always invisible TRUE.

Examples

# Set custom notification messages for shiny app
suso_set_pwcheck_mess(mess_succ = "Connected successfully!", mess_fail = "Authentication failed!")
suso_set_prog_mess(mess = "Downloading data, please wait...")

Convenience function to switch workspace

Description

Sets the workspace only, but leaves all other credentials the same.

Usage

suso_set_workspace(workspace = NULL)

Arguments

Details

Use suso_set_workspace to make the desired workspace available for all the suso_ functions, so you don't need to specify the workspace parameter within those functions. The function also checks if the workspace name is correct, and the user with the current credentials is authorized.If the workspace requires different credentials, then use suso_set_key again.

Value

invisibly TRUE if successful.

Examples

# switch to workspace "windows"
suso_set_workspace("windows")

# switch to primary (default) workspace
suso_set_workspace()

Update workspace details

Description

Updates the display name of a workspace. Accessible only to administrator.

Usage

suso_updateWorkspace(
  server = suso_get_api_key("susoServer"),
  apiUser = suso_get_api_key("susoUser"),
  apiPass = suso_get_api_key("susoPass"),
  token = NULL,
  workspace = NULL,
  displayName = NULL
)

Arguments

Value

A data.table indicating the update status.

Examples

suso_updateWorkspace(workspace = "my_ws", displayName = "Renamed Workspace")