redcapAPI (version 2.8.0)

projectInformationMethods: Export and Import Project Settings

Description

These methods enable the user to export or update project level settings, such as the project title, if it is longitudinal, if surveys are enabled, etc.

Usage

exportProjectInformation(rcon, ...)
importProjectInformation(rcon, data, ...)
# S3 method for redcapApiConnection
exportProjectInformation(
  rcon,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
# S3 method for redcapApiConnection
importProjectInformation(
  rcon,
  data,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Value

exportProjectInformation returns a data frame with the columns

project_id	The internal ID number assigned to the project.
project_title	The project title given to the project.
creation_time	The date/time the project was created.
production_time	The date/time the project was moved into production status.
in_production	Boolean value indicating if the project is in production status.
project_language	The language associated with the project.
purpose	An integerish value identifying the purpose of the project. 0 = "Practice/Just for fun", 1 = "Other", 2 = "Research", 3 = "Quality Improvement", 4 = "Operational Support".
purpose_other	The user supplied character value given when the project purpose is 'Other'.
project_notes	The user supplied notes about the project.
custom_record_label	The user provided custom label for the record identifier field.
secondary_unique_field	The name of the secondary unique field, if this has been configured.
is_longitudinal	Boolean value indicating if the project is a longitudinal project.
has_repeating_instruments_or_events	Boolean value indicating if the repeating instruments or events module has been enabled.
surveys_enabled	Boolean value indicating if the surveys module has been enabled.
scheduling_enabled	Boolean value indicating if the scheduling module has been enabled.
record_autonumbering_enabled	Boolean value indicating if the record autonumbering feature has been enabled.
randomization_enabled	Boolean value indicating if the randomization module has been enabled.
ddp_enabled	Boolean value indicating if dynamic data pull has been enabled for a project (may only be enabled by a REDCap administrator).
project_irb_number	The user provided IRB number for the project.
project_grant_number	The user provided grant number for the project.
project_pi_firstname	The first name of the principal investigator.
project_pi_lastname	The last name of the principal investigator.
display_today_now_button	Boolean value indicating if the today/now button is displayed for date/time fields in the UI.
missing_data_codes	Character value giving the missing data codes enabled for the project. They are given in the format [code],[label], with each coding separated by a pipe character.
external_modules	Character value listing the external modules enabled.
bypass_branching_erase_field_prompt	Boolean value indicating if the box for "Prevent branching logic from hiding fields that have values" has been checked under "Additional Customizations."

importProjectInformation has no return and displays a message indicating the number of fields updated.

Arguments

rcon

A redcapConnection object.

data

data.frame with only one row and any subset of allowable fields to be updated. See Details.

refresh

logical(1). If TRUE, the cached project information will be updated after the import.

...

Arguments to pass to other methods

error_handling

character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().

config

A named list. Additional configuration parameters to pass to httr::POST(). These are appended to any parameters in rcon$config.

api_param

A named list. Additional API parameters to pass into the body of the API call. This provides users to execute calls with options that may not otherwise be supported by redcapAPI.

Functions

• exportProjectInformation(): Export project settings.

• importProjectInformation(): Import project settings.

Details

When importing, fields that are not editable will be quietly removed prior to import. This allows the user to use the result of exportProjectInformation as a template for the import.

For any values that are boolean, they should be represented as either a '0' (no/false) or '1' (yes/true).

It is not required for data to have all of the fields, but only the fields the user wishes to update (see examples).

The following project attributes can be updated:

• project_title

• project_language

• purpose

• purpose_other

• project_notes

• custom_record_label

• secondary_unique_field

• is_longitudinal

• surveys_enabled

• scheduling_enabled

• record_autonumbering_enabled

• randomization_enabled

• project_irb_number

• project_grant_number

• project_pi_firstname

• project_pi_lastname

• display_today_now_button

• bypass_branching_erase_field_prompt

Examples

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export Project Information
exportProjectInformation(rcon)

# Import a new project title
NewData <- data.frame(project_title = "New Title Name")
importProjectInformation(rcon, 
                         data = NewData)
                         
# Enable surveys in the project
NewData <- data.frame(surveys_enabled = 1)
importProjectInformation(rcon, 
                         data = NewData)
                         
# Change multiple fields in the project settings
NewData <- data.frame(project_irb_number = "IRB-12345", 
                      display_today_now_button = 0, 
                      scheduling_enabled = 1)
importProjectInformation(rcon, 
                         data = NewData)
}