Introduction to susoapiSource:
susoapi package aims to provide an R wrapper function for each Survey Solutions API endpoint, and in so doing enable users to take all API actions without leaving R.
Before any of these functions can be used, the user must set their credentails to be authenticated by the server.
While authentication could be provided separately for each function call as part of its arguments, it is better and more efficient to use the
set_credentials() function to capture the credentials and make them available to all function calls. For example:
# first, set credentials for connecting with the server set_credentials( server = "https://example.server", workspace = "myworkspace", user = "My_API_user1", password = "MySecretPassword2Day" ) # then, get all questionnaires # the arguments of this function are: server, user, and password # but they are provided to the function by the values stored by `set_credentials()` get_questionnaires()
To take an individual action, one simply needs to find the appropriate function. The reference arranges functions according to their area:
For example, to gather all questionnaires loaded on the server:
# collect all questionnaires and data about them, # using previously set server credentials get_questionnaires()
To take a series of related actions, users have two choices:
- Chain commands explicitly
- Use other tools that do this implicitly
To export data, one needs to make a sequence of function calls.
First, start an export job, by specifying all of the particulars:
# set server authentication credentials set_credentials( server = "https://exampleserver.com", workspace = "myworkspace", user = "My_API_user10", password = "MySecretPassword2Day123" ) # start an export job # specifying same same options as in user interface # optionally specifying other options--including some not available in the UI start_export( qnr_id = "72f7160c-12dc-4dd4-9df1-66af819e434d$1", export_type = "STATA", interview_status = "All", include_meta = TRUE ) -> started_job_id
Then, check on the job’s status:
# check export job progess, # specifying ID of job started in prior step get_export_job_details(job_id = started_job_id)
Repeat job status queries until the job is complete.
Next, download the file produced by the completed job:
# download the export file, # specifying: # - job ID # - where to download the file get_export_file( job_id = started_job_id, path = "C:/your/file/path/" )
To monitor user activity on tablets, one needs to follow these steps.
First, collect the list of users and their profile details
# collect all interviewers, their supervisors, and their attributes # this includes both account details and personal details all_users <- get_interviewers()
Then, identify the user of interest by filtering the data.
Next, request the action log of all tablet activity for the target user.
# collect a log of activity on the tablet within specified dates tablet_activity <- get_user_action_log( user_id = target_user_id, start = "2020-02-15", end = "2020-03-15" )
Alternatively, for certain tasks, users can rely on
susoflows, a package that aims to wrap common workflows in single functions (e.g., download data).