REDCapR 1.1.0

Version 1.1.0 (released 2022-08-10)

New Features

• New redcap_delete() function. It deletes a vector of records. (Thanks @joundso, #372, #373)
• New redcap_arm_export() function. It retrieves a list of REDCap project arms. (#375)
• redcap_read() and redcap_read_oneshot() accept a new locale parameter that specifies date, time, and number formats, like using a comma as the decimal separator. It is a readr::locale object. (#377, suggested by @joundso)
• New redcap_instruments() function exports a list of the data collection instruments for a project. (#381, @vcastro)
• New redcap_event_instruments() function exports the instrument-event mappings for a project (i.e., how the data collection instruments are designated for certain events in a longitudinal project).. (#381, @vcastro)
• New redcap_dag_read() function returns the Data Access Groups for a project (#382, @joundso)
• New detection when REDCap has trouble with a large request and drops records. (#400 w/ @TimMonahan)

Minor Enhancements

• sanitize_token() now allows lowercase characters --in addition to uppercase characters & digits. (#347, @jmbarbone)
• redcap_metadata_read() now uses json (instead of csv) to transfer the dictionary between server & client. This accommodates super-wide dictionaries with 35k+ variables. The user shouldn't notice a difference, and still will receive a data.frame. (#335, @januz & @datalorax)
• Include a few more testthat::skip_on_cran() calls to comply with CRAN's "fail gracefully" policy. Similarly, skip remaining examples that depend on external resources. (#352)
• retrieve_credential_local() can now user username to identify the desired credential row (#364)
• redcap_read() and redcap_read_oneshot() gain the http_response_encoding parameter that's passed to httr::content(). The default value remains "UTF-8". (#354, @lrasmus)
• Accommodate single-character REDCap variable names (#367 & #368, @daynefiler)
• Modify redcap_users_export() (which calls REDCap's user export). The API dropped the data_export variable and added the forms_export variable. (#396)
• For redcap_read_oneshot_eav(): if the project isn't longitudinal, a dummy value for event_id is used internally (#396)
• For the testing server & projects, the http errors are a little different, so the testing code was adjusted (#396)
• Set httr::user_agent, following the advice of httr's vignette (#397)

Test Suite

• Added two more dictionaries that are super wide -5k & 35k variables (#335 & #360, @januz & @datalorax)
• Read, modify, & read projects with DAGs (#353, daniela.wolkersdorfer, #353)

REDCapR 1.0.0

Version 1.0 (released 2021-07-21)

The package has been stable for years and should be reflected in the major version number.

Minor Enhancements

• When writing records to the server, the functions redcap_write() and redcap_write_oneshot() have a new parameter that converts R's logical/boolean columns to integers. This meshes well with T/F and Y/N items that are coded as 1/0 underneath. The default will be FALSE (ie, the integers are not converted by default), so it doesn't break existing code. (#305)
• When writing records to the server, the functions redcap_write() and redcap_write_oneshot() can toggle the ability to overwrite with blank/NA cells (suggested by @Auricap, #315)
• The functions redcap_read_oneshot(), redcap_read(), & redcap_read_oneshot_eav() now support the parameters datetime_range_begin and datetime_range_end. The are passed to the REDCap parameters dateRangeBegin and dateRangeEnd, which restricts records returned, based on their last modified date in the server. (Thanks @pbchase, #321 & #323.)
• Better documentation about the export_survey_fields parameter in the functions redcap_read() & redcap_read_oneshot(). (Thanks @isaactpetersen, #333)
• New function redcap_report() export records that populate a REDCap report. (#326.)
• New vignette Typical REDCap Workflow for a Data Analyst developed to support a workshop for the 2021 R/Medicine Conference (#332, with @higgi13425, @kamclean, & Amanda Miller)
• New function create_credential_local() starts a well-formed csv file that can contain tokens. (#340, after conversations with @higgi13425 & @kamclean.)

Stability Features

• update for newer version of testthat -v3.0.0 (#312)
• update for newer version of readr 2.0.0 (#343)
• update for newer version of readr 1.4.0 (#313)
• update for newer version of REDCap on test server (#310)
• save expected datasets as files -instead of included in the actual test code (#308)

Corrections & Bug Fixes

• Accepts more than one config_option element. (Proposed by @BastienRance, #307)
• Fixed calculation of success value returned by redcap_read() and redcap_write() when the parameter continue_on_error is true. (Bug found by @llrs, #317)

REDCapR 0.11.0

Version 0.11 (Released 2020-04-20)

Breaking Changes (possible, but unlikely)

• kernel_api() defaults to "text/csv" and UTF-8 encoding. Formerly, the function would decide on the content-type and encoding. More details are below in the 'Stability Features' subsection.

• constant() no longer accepts simplify as an options. An integer vector is always returned. (#280)

New Features

• It's now possible to specify the exact col_types (a readr::cols object) that is passed to readr::read_csv() inside redcap_read_oneshot(). (#258)

• reader::type_convert() is used after all the batches are stacked on top of each other. This way, batches cannot have incompatible data types as they're combined. (#257; thanks @isaactpetersen #245) Consequently, the guess_max parameter in redcap_read() no longer serves a purpose, and has been soft-deprecated. (#267)

• redcap_metadata_write() writes to the project's metadata. (#274, @felixetorres)

• redcap_survey_link_export_oneshot() retrieves the URL to a specific record's suvey (e.g., "https://bbmc.ouhsc.edu/redcap/surveys/?s=8KuzSLMHf6") (#293)

Stability Features

• httr::content() (which is inside kernel_api()) now processes the returned value as "text/csv", by default. This should prevent strange characters from tricking the process as the internal variable raw_text is being formed. See the [httr::content()](https://httr.r-lib.org/reference/content.html) documentation for a list of possible values for the content_type` parameter. (Thanks to great debugging by @vortexing #269, @sybandrew #272, & @begavett, #290)

• Similarly, kernel_api() now has an encoding parameter, which defaults to "UTF-8". (#270)

Minor Enhancements

• check for bad field names passed to the read records functions (#288)

Corrections

• 'checkmate' package is now imported, not suggested (Thanks @dtenenba, #255)

REDCapR 0.10.2

Released 2019-09-22

Minor New Features

• export survey time-stamps optionally (Issue #159)
• redcap_next_free_record_name(): API call for 'Generate Next Record Name', which returns the next available record ID (Issue #237)
• redcap_read() and redcap_read_oneshot() allow the user to specify if all variables
  should be returned with the character data type. The default is to allow readr::read_csv() to guess the data type. (#194)
• redcap_read_oneshot() allows use to specify how many rows should be considered when readr::read_csv() guesses the data type. (#194)
• redcap_read(), redcap_read_oneshot(), and redcap_read_oneshot_eav() always return Linux-style line endings (ie \n) instead of Windows style line endings (ie, \r\n) on all OSes. (#198)
• read_metadata() always returns character vectors for all variables. With readr 1.2.0, some column were returned differently than before. (#193)
• 'raw_or_label_headers' now supported (Thanks Hatem Hosny - hatemhosny, #183 & #203)
• 'export_checkbox_labels' now supported (#186)
• redcap_users_export() now included (#163)
• 'forms' now supported for redcap_read(), redcap_read_oneshot(), & redcap_read_oneshot_eav()(#206). It was already implemented for redcap_metadata_read().
• If no records are affected, a zero-length character vector is returned (instead of sometimes a zero-length numeric vector) (#212)
• New function (called constants()) easily exposes REDCap-specific constants. (#217)
• id_position allows user to specify if the record_id isn't in the first position (#207). However, we recommend that all REDCap projects keep this important variable first in the data dictionary.
• Link to new secure Zenodo DOI resolver (@katrinleinweber #191)
• parameters in redcap_read() and redcap_read_oneshot() are more consistent with the order in raw REDCap API. (#204)
• When the verbose parameter is NULL, then the value from getOption("verbose") is used. (#215)
• guess_max parameter provided in redcap_read() (no longer just redcap_read_oneshot()). Suggested by @isaactpetersen in #245.
• Documentation website constructed with pkgdown (#224).
• redcap_variables() now throws an error when passed a bad URI (commit e542155).

Modified Internals

• All interaction with the REDCap server goes through the new kernal_api() function, which uses the 'httr' and 'curl' packages underneath. Until now, each function called those packages directly. (#213)
• When converting REDCap's CSV to R's data.frame, readr::read_csv() is used instead of utils::read.csv() (Issue #127).
• updated to readr 1.2.0 (#200). This changed how some data variables were assigned a data types.
• uses odbc package to retrieve credentials from the token server. Remove RODBC and RODBCext (#188). Thanks to @krlmlr for error checking advice in https://stackoverflow.com/a/50419403/1082435.
• data.table::rbindlist() replaced by dplyr::bind_rows()
• the checkmate package inspects most function parameters now (instead of testit::assert() and base:stop() ) (#190 & #208).
• collapse_vector() is refactored and tested (#209)
• remove dependency on pkgload package (#218)
• Update Markdown syntax to new formatting problems (#253)

REDCapR 0.9.0

(Developed 2015-01-15 through 2015-08-14)

New Features:

• Adapted for version 1.0.0 of httr (which is now based on the curl package, instead of RCurl).

Minor Updates:

• Uses requireNamespace() instead of require().
• By default, uses the SSL cert files used by httr, which by default, uses those packaged with R.
• Added warning if it appears readcap_read() is being used without 'Full Data Set' export privileges. The problem involves the record IDs are hashed.
• Reconnected code that reads only the id_position in the first stage of batching. The metadata needed to be read before that, after the updates for REDCap Version 6.0.x.
• retrieve_token_mssql() uses regexes to validate parameters

REDCapR 0.7-1

Since the last CRAN release:

Version 0.7 (Developed 2014-12-17 through 2014-12-17)

New Features:

• Updated for Version 6.0.x of REDCap (which introduced a lot of improvements to API behavior).

Version 0.6 (Developed 2014-10-29 through 2014-11-03)

New Features:

• The config_options in the httr package are exposed to the REDCapR user. See issues #55 & #58; thanks to @rparrish and @nutterb for their contributions (#55 & #58).

Version 0.5 (Developed 2014-09-20 through 2014-10-19)

New Features:

• redcap_metadata_read are tested and public.

Minor Updates:

• Test suite now uses testthat::skip_on_cran() before any call involving OUHSC's REDCap server.
• Vignette example of subsetting, conditioned on a 2nd variable's value.

REDCapR 0.4-28

First release on CRAN, 2014-09-20.

REDCapR 0.9.8

New Features

• Enumerate the exported variables. with redcap_variables().
• Experimental EAV export in redcap_read_oneshot_eav(), which can be accessed with a triple colon (ie, REDCapR::redcap_read_oneshot_eav()).

Bug Fixes

• Adapted to new 2.4 version of curl (see #154)

REDCapR 0.9.7

New Features:

• Support for filtering logic in redcap_read() and redcap_read_oneshot() (PR #126)
• New functions retrieve_credential_mssql() and retrieve_credential_local(). These transition from storing & retrieving just the token (ie, retrieve_token_mssql()) to storing & retrieving more information. retrieve_credential_local() facilitates a standard way of storing tokens locally, which should make it easier to follow practices of keeping it off the repository.
• Using parameterized queries with the RODBCext package. (Thanks @nutterb in issues #115 & #116.)
• Remove line breaks from token (Thanks @haozhu233 in issues #103 & #104)

Minor Updates:

• When combining batches into a single data.frame, data.table::rbindlist() is used. This should prevent errors with the first batch's data type (for a column) isn't compatible with a later batch. For instance, this occurs when the first batch has only integers for record_id, but a subsequent batch has values like aa-test-aa. The variable for the combined dataset should be a character. (Issue #128 & http://stackoverflow.com/questions/39377370/bind-rows-of-different-data-types; Thanks @arunsrinivasan)
• Uses the dplyr package instead of plyr. This shouldn't affect callers, because immediately before returning the data, REDCapR::redcap_read() coerces the tibble::tibble (which was formerly called dplyr::tbl_df) back to a vanilla data.frame with as.data.frame().
• A few more instances of validating input parameters to read functions. (Issue #8).

REDCapR 0.9.3

(Developed 2015-08-25)

Minor Updates:

• The retrieve-token() tests now account for the (OS X) builds where the RODBC package isn't available.