createRedcapProject: Create REDCap Project

In nutterb/redcapAPI: Interface to 'REDCap'

Create REDCap Project

Description

These methods enable a user with a 64-character Super API token to create a new REDCap project.

Usage

createRedcapProject(
  rcon,
  project_title,
  purpose = REDCAP_PROJECT_PURPOSE,
  purpose_other = NULL,
  is_longitudinal = FALSE,
  surveys_enabled = FALSE,
  record_autonumbering_enabled = FALSE,
  xml = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
createRedcapProject(
  rcon,
  project_title,
  purpose = REDCAP_PROJECT_PURPOSE,
  purpose_other = NULL,
  is_longitudinal = FALSE,
  surveys_enabled = FALSE,
  record_autonumbering_enabled = FALSE,
  xml = NULL,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Arguments

rcon	A redcapConnection object.
project_title	character(1). Title for the new project.
purpose	character, one of c("Practice/just for fun", "Other", "Research", "Quality Improvement", "Operational Support")
purpose_other	character(1) or NULL. Ignored unless purpose = "Other", in which case this becomes a required argument.
is_longitudinal	logical(1). When TRUE the project will be set as a longitudinal project.
surveys_enabled	logical(1). When TRUE surveys are enabled for the project. (This will not add any survey instruments, only enable them).
record_autonumbering_enabled	logical(1). When TRUE if auto numbering will be enabled in the project.
xml	character(1) or NULL an XML string in CDISC ODM XML format that contains project metadata (fields, forms, events, arms) and might optionally contain data to be imported as well. When not NULL, all other arguments are ignored. See Details.
...	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.

Details

The user creating the project will automatically be added to the project as a user with full user privileges and a project-level API token, which could then be used for subsequent project-level API requests.

When the project is created, it will automatically be given all the project-level defaults just as if it had been created via the web user interface, such as automatically creating a single data collection instrument seeded with a single Record ID field and Form Status field, as well as (for longitudinal projects) one arm with one event.

If the user intends to populate the project with arms and events immediately after creating the project, it is recommended that override = TRUE be used in importArms and importEvents so that the default arm and event are removed.

The xml argument must be in CDISC ODM XML format. It may come from a REDCap Project XML export file from REDCap itself (see exportProjectXml()), or may come from another system that is capable of exporting projects and data in CDISC ODM format. If the xml argument is used in the API request, it will use the XML to import its contents into the newly created project. This will not only create the project with the API request, but also to import all fields, forms, and project attributes (and events and arms, if longitudinal) as well as record data all at the same time.

Only users with a 64-character Super API Tokens can utilize this method (the standard API token is 32 characters). Users can only be granted a super token by a REDCap administrator (using the API Tokens page in the REDCap Control Center). Please be advised that users with a Super API Token can create new REDCap projects via the API without any approval needed by a REDCap administrator.

Value

Returns a character(1) the 32-character, project level API token assigned to the user that created the project. This token is intended to be used for further project configuration using the API.

See Also

exportProjectXml()

Examples

## Not run: 
# The token must be a 64-character token
super_token <- redcapConnection(url = "your_redcap_url", 
                                token = "[64-character-super-api-token]")
         
# Create a new project    
createRedcapProject(super_token, 
                    project_title = "New Project Name", 
                    purpose = "Quality Improvement", 
                    is_longitudinal = FALSE, 
                    surveys_enabled = TRUE)
                    
                    
                    
# Copy an existing project into a new project
unlockREDCap(connections = c(rcon = "token_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
xml_file <- tempfile(file.ext = ".xml")
exportProjectXml(rcon, 
                 file = xml_file)
 
xml_text <- paste0(readLines(xml_file), collapse = " ")
createRedcapProject(super_token, 
                    xml = xml_text)

## End(Not run)

nutterb/redcapAPI documentation built on Feb. 11, 2024, 11:20 p.m.