get_selected_page_records: Get multiple records for a set of fields in a page (i.e.,...

Description Usage Arguments Details Value Warning Examples

View source: R/page_records.R

Description

Sends a request to the iFormBuilder API to get the first 1000 records or less in a given form or subform for a specific set of fields (columns). Specify how many records to retrieve using the limit parameter. Specify how many records to skip before starting to retrieve records using the offset parameter.

Usage

1
2
3
4
5
6
7
8
9
get_selected_page_records(
  server_name,
  profile_id,
  page_id,
  fields = "fields",
  limit = 100,
  offset = 0,
  access_token
)

Arguments

server_name

String of the iFormBuilder server name

profile_id

The id number of your profile

page_id

The id of the form or subform

fields

A set of data fields (columns) to return

limit

The maximum number of records to return

offset

Skips the offset number of records before beginning to return

access_token

Access token produced by get_iform_access_token

Details

This will likely be the primary function used to retrieve records from the iFormBuilder API. When a set of records is downloaded using this function the retrieved data will contain the record id as the first column. By archiving these ids, each request for new records can incorporate the last downloaded id in the fields parameter to only pull newly submitted records. See example below. For more information on how to construct a string that specifies fields and conditions to apply to a request for records, see the Introduction section of the iFormBuilder Apiary

Value

A dataframe of records for the specified fields (columns)

Warning

This function should only be used to request records from one form or subform at a time. Do not assume it will work if records from more than one form are incorporated in the fields parameter. If you request multiple fields but the function only returns the id value, and does not throw an error, this is a strong indication that you did not specify the fields correctly. You may have requested a field that does not exist.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Specify the fields (columns) to be returned
field_list <- glue::glue("observers, survey_start_datetime, survey_method, ",
                         "stream, start_point")

## Not run: 
# Set id to ascending order and pull only records greater than the last_id
since_id <- 5L
parent_form_fields <- glue::glue('id:<(>"{since_id}"), {field_list}')

# Get access_token
access_token <- get_iform_access_token(
  server_name = "your_server_name",
  client_key_name = "your_client_key_name",
  client_secret_name = "your_client_secret_name")

# Get the id of a single form in the profile given the form name
form_id <- get_page_id(
  server_name = "your_server_name",
  profile_id = 123456,
  page_name = "your_form_p",
  access_token = access_token)

# Get multiple records for a set of columns from a form or subform
parent_form_records <- get_selected_page_records(
  server_name = "your_server_name",
  profile_id = 123456,
  page_id = form_id,
  fields = parent_form_fields,
  access_token = access_token)

# Inspect the first three rows and first five columns of the dataframe
parent_form_records[1:3,1:5]

## End(Not run)

arestrom/iformr documentation built on Nov. 25, 2021, 11:21 p.m.