Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Function to export logfile #383

Merged
merged 14 commits into from
Aug 12, 2022
Merged

Function to export logfile #383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
edc1c6a
feat: adds function to export logfile
joundso Feb 10, 2022
94e513b
Merge branch 'main' into export-logfile
wibeasley Mar 1, 2022
7d040ac
Merge branch 'main' into export-logfile
wibeasley Jul 23, 2022
8aaafea
Merge branch 'main' into pr/383
wibeasley Aug 12, 2022
52f710c
Merge branch 'export-logfile' of https://github.com/joundso/REDCapR i…
wibeasley Aug 12, 2022
11800ef
renaming @joundso's R file
wibeasley Aug 12, 2022
ab349d8
renaming @joundso's function
wibeasley Aug 12, 2022
6578ea5
loosen restriction of server version
wibeasley Aug 12, 2022
1f39c88
log -filter w/ day
wibeasley Aug 12, 2022
2e1f4d8
document logging; test for user & record
wibeasley Aug 12, 2022
6c7b4d3
align whitespace
wibeasley Aug 12, 2022
22b4d71
add news entry
wibeasley Aug 12, 2022
6d2cd53
add news entry
wibeasley Aug 12, 2022
462aed1
quality credential object of url & token
wibeasley Aug 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions NAMESPACE
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ export(redcap_download_file_oneshot)
export(redcap_download_instrument)
export(redcap_event_instruments)
export(redcap_instruments)
export(redcap_log_read)
export(redcap_metadata_read)
export(redcap_metadata_write)
export(redcap_next_free_record_name)
Expand Down
7 changes: 7 additions & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
Upcoming Release
==========================================================

### New Features

* New `redcap_log_read()` function. Exports a project's log. (Thanks @joundso, #383, #320)

Version 1.1.0 (released 2022-08-10)
==========================================================

Expand Down
200 changes: 200 additions & 0 deletions R/redcap-log-read.R
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
#' @title Get the logging of a project.
#'
#' @description This function reads the available logging messages from
#' REDCap an returns them as a [base::data.frame()].
#'
#' @param redcap_uri The URI (uniform resource identifier) of the REDCap
#' project. Required.
#' @param token The user-specific string that serves as the password for a
#' project. Required.
#' @param log_begin_date Return the events occurring after midnight of this
#' date.
#' Defaults to the past week; this default mimics the behavior in the browser
#' and also reduces the strain on your server.
#' @param log_end_date Return the events occurring before 24:00 of this date.
#' Defaults to today.
#' @param record Return the events belonging only to specific record
#' (referring to an existing record name).
#' Defaults to `NULL` which returns
#' logging activity related to all records.
#' If a record value passed, it must be a single value.
#' @param user Return the events belonging only to specific user
#' (referring to an existing username).
#' Defaults to `NULL` which returns
#' logging activity related to all users.
#' If a user value passed, it must be a single value.
#' @param http_response_encoding The encoding value passed to
#' [httr::content()]. Defaults to 'UTF-8'.
#' @param locale a [readr::locale()] object to specify preferences like
#' number, date, and time formats. This object is passed to
#' [`readr::read_csv()`]. Defaults to [readr::default_locale()].
#' @param verbose A boolean value indicating if `message`s should be printed
#' to the R console during the operation. The verbose output might contain
#' sensitive information (*e.g.* PHI), so turn this off if the output might
#' be visible somewhere public. Optional.
#' @param config_options A list of options to pass to `POST` method in the
#' `httr` package.
#'
#' @return Currently, a list is returned with the following elements:
#' * `data`: An R [base::data.frame()] of all data access groups of the project.
#' * `success`: A boolean value indicating if the operation was apparently
#' successful.
#' * `status_codes`: A collection of
#' [http status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes),
#' separated by semicolons. There is one code for each batch attempted.
#' * `outcome_messages`: A collection of human readable strings indicating the
#' operations' semicolons. There is one code for each batch attempted. In an
#' unsuccessful operation, it should contain diagnostic information.
#' * `elapsed_seconds`: The duration of the function.
#'
#' @author Jonathan M. Mang, Will Beasley
#' @references The official documentation can be found on the 'API Help Page'
#' and 'API Examples' pages on the REDCap wiki (*i.e.*,
#' https://community.projectredcap.org/articles/456/api-documentation.html
#' and
#' https://community.projectredcap.org/articles/462/api-examples.html).
#' If you do not have an account for the wiki, please ask your campus REDCap
#' administrator to send you the static material.
#'
#' @examples
#' \dontrun{
#' uri <- "https://bbmc.ouhsc.edu/redcap/api/"
#' token <- "9A81268476645C4E5F03428B8AC3AA7B"
#'
#' ds_last_week <- REDCapR::redcap_log_read(redcap_uri=uri, token=token)$data
#' head(ds_last_week)
#'
#' ds_one_day <-
#' REDCapR::redcap_log_read(
#' redcap_uri = uri,
#' token = token,
#' log_begin_date = as.Date("2020-08-10"),
#' log_end_date = as.Date("2020-08-10")
#' )$data
#' head(ds_one_day)
#'
#' ds_one_day_single_record_single_user <-
#' REDCapR::redcap_log_read(
#' redcap_uri = uri,
#' token = token,
#' log_begin_date = as.Date("2021-07-11"),
#' log_end_date = as.Date("2021-07-11"),
#' record = as.character(3),
#' user = "unittestphifree"
#' )$data
#' head(ds_one_day_single_record_single_user)
#' }

#' @export
redcap_log_read <- function(
redcap_uri,
token,
log_begin_date = Sys.Date() - 7L,
log_end_date = Sys.Date(),
record = NULL,
user = NULL,
http_response_encoding = "UTF-8",
locale = readr::default_locale(),
verbose = TRUE,
config_options = NULL
) {
checkmate::assert_character(redcap_uri , any.missing = FALSE, len = 1, pattern = "^.{1,}$")
checkmate::assert_character(token , any.missing = FALSE, len = 1, pattern = "^.{1,}$")
checkmate::assert_date( log_begin_date , any.missing = FALSE, len = 1)
checkmate::assert_date( log_end_date , any.missing = FALSE, len = 1)
checkmate::assert_character(record , any.missing = FALSE, len = 1, null.ok = TRUE)
checkmate::assert_character(user , any.missing = FALSE, len = 1, null.ok = TRUE)

checkmate::assert_character(http_response_encoding , any.missing=FALSE, len = 1)
checkmate::assert_class( locale, classes = "locale", null.ok = FALSE)
checkmate::assert_logical( verbose , any.missing=FALSE, len = 1, null.ok = TRUE)
checkmate::assert_list( config_options , any.missing=TRUE , null.ok = TRUE)

token <- sanitize_token(token)
verbose <- verbose_prepare(verbose)
log_begin_datetime <- strftime(log_begin_date , "%Y-%m-%d 00:00")
log_end_datetime <- strftime(log_end_date , "%Y-%m-%d 24:00")

post_body <- list(
token = token,
content = "log",
format = "csv",
beginTime = log_begin_datetime,
endTime = log_end_datetime,
record = record,
user = user
)

# This is the important line that communicates with the REDCap server.
kernel <- kernel_api(
redcap_uri = redcap_uri,
post_body = post_body,
config_options = config_options,
encoding = http_response_encoding
)

if (kernel$success) {
try(
# Convert the raw text to a dataset.
ds <-
readr::read_csv(
file = I(kernel$raw_text),
locale = locale,
show_col_types = FALSE
) %>%
as.data.frame(),

# Don't print the warning in the try block. Print it below,
# where it's under the control of the caller.
silent = TRUE
)

if (exists("ds") & inherits(ds, "data.frame")) {
outcome_message <- sprintf(
"%s rows were read from REDCap in %0.1f seconds. The http status code was %i.",
format( nrow(ds), big.mark = ",", scientific = FALSE, trim = TRUE),
kernel$elapsed_seconds,
kernel$status_code
)

# If an operation is successful, the `raw_text` is no longer returned to
# save RAM. The content is not really necessary with httr's status
# message exposed.
kernel$raw_text <- ""
} else { # ds doesn't exist as a data.frame.
# nocov start
# Override the 'success' determination from the http status code.
# and return an empty data.frame.
kernel$success <- FALSE
ds <- data.frame()
outcome_message <- sprintf(
"The REDCap log export failed. The http status code was %i. The 'raw_text' returned was '%s'.",
kernel$status_code,
kernel$raw_text
)
# nocov end
}
} else { # kernel fails
ds <- data.frame() #Return an empty data.frame
outcome_message <- if (any(grepl(kernel$regex_empty, kernel$raw_text))) {
"The REDCapR log export operation was not successful. The returned dataset was empty." # nocov
} else {
sprintf(
"The REDCapR log export operation was not successful. The error message was:\n%s",
kernel$raw_text
)
}
}

if (verbose)
message(outcome_message)

list(
data = ds,
success = kernel$success,
status_code = kernel$status_code,
outcome_message = outcome_message,
elapsed_seconds = kernel$elapsed_seconds,
raw_text = kernel$raw_text
)
}
115 changes: 115 additions & 0 deletions inst/test-data/specific-redcapr/log-read/2020-08-10.R
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
structure(list(timestamp = structure(c(1597087500, 1597087500,
1597087500, 1597087500, 1597087500, 1597087500, 1597087500, 1597087500,
1597087500, 1597087500, 1597087500, 1597087500, 1597087500, 1597087500,
1597087500, 1597087500, 1597087500, 1597087500, 1597087500, 1597087500,
1597087500, 1597087500, 1597087500, 1597087500, 1597087500, 1597087500,
1597087500, 1597087500, 1597087500, 1597087500, 1597087500, 1597087500,
1597060740, 1597060740, 1597060740, 1597060680, 1597060680, 1597060680,
1597060680, 1597060680, 1597060680, 1597060680, 1597060680, 1597060680,
1597060680, 1597060680, 1597060680, 1597060680, 1597060680, 1597060680,
1597060680, 1597060680, 1597060680, 1597060680, 1597060680, 1597060680,
1597060680, 1597060680, 1597060680, 1597060680, 1597060680, 1597060680,
1597060680, 1597060680, 1597037400, 1597037400, 1597037400, 1597037340,
1597037340, 1597037340, 1597037340, 1597037340, 1597037340, 1597037340,
1597037340, 1597037340, 1597037340, 1597037340, 1597037340, 1597037340,
1597037340, 1597037340, 1597037340, 1597037340, 1597037340, 1597037340,
1597037340, 1597037340, 1597037340, 1597037340, 1597037340, 1597037340,
1597037340, 1597037340, 1597037340, 1597037340), class = c("POSIXct",
"POSIXt"), tzone = "UTC"), username = c("unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree"), action = c("Data export (API)",
"Data export (API)", "Data export (API)", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Manage/Design", "Manage/Design",
"Data export (API)", "Data export (API)", "Data export (API)",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Manage/Design",
"Manage/Design", "Data export (API)", "Data export (API)", "Data export (API)",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Data export (API)",
"Data export (API)", "Manage/Design", "Data export (API)", "Data export (API)",
"Manage/Design", "Data export (API)", "Data export (API)", "Manage/Design",
"Data export (API)", "Data export (API)", "Manage/Design", "Manage/Design",
"Manage/Design"), details = c("export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "Export REDCap version (API)",
"Export project information (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "Export REDCap version (API)",
"Export project information (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "export_format: CSV, rawOrLabel: raw",
"export_format: CSV, rawOrLabel: raw", "Download data dictionary (API)",
"export_format: CSV, rawOrLabel: raw", "export_format: CSV, rawOrLabel: raw",
"Download data dictionary (API)", "Export REDCap version (API)",
"Export project information (API)")), row.names = c(NA, -96L), class = "data.frame")
15 changes: 15 additions & 0 deletions inst/test-data/specific-redcapr/log-read/2021-07-11-record3-user.R
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
structure(list(timestamp = structure(c(1626044880, 1626044880,
1626044640, 1626044640, 1626044160, 1626044160, 1625968020, 1625968020,
1625967780, 1625967780, 1625967240, 1625967240), class = c("POSIXct",
"POSIXt"), tzone = "UTC"), username = c("unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree", "unittestphifree", "unittestphifree",
"unittestphifree", "unittestphifree"), action = c("Manage/Design",
"Manage/Design", "Manage/Design", "Manage/Design", "Manage/Design",
"Manage/Design", "Manage/Design", "Manage/Design", "Manage/Design",
"Manage/Design", "Manage/Design", "Manage/Design"), details = c("Download file (API)",
"Download file (API)", "Download file (API)", "Download file (API)",
"Download file (API)", "Download file (API)", "Download file (API)",
"Download file (API)", "Download file (API)", "Download file (API)",
"Download file (API)", "Download file (API)")), row.names = c(NA,
-12L), class = "data.frame")
2 changes: 1 addition & 1 deletion inst/test-data/specific-redcapr/users-export/without-dags--user.R
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ structure(list(username = c("unittestphifree", "wbeasleya"),
data_access_groups = c(FALSE, TRUE), reports = c(TRUE, TRUE
), stats_and_charts = c(TRUE, TRUE), manage_survey_participants = c(TRUE,
TRUE), calendar = c(TRUE, TRUE), data_import_tool = c(FALSE,
TRUE), data_comparison_tool = c(FALSE, TRUE), logging = c(FALSE,
TRUE), data_comparison_tool = c(FALSE, TRUE), logging = c(TRUE,
TRUE), file_repository = c(TRUE, TRUE), data_quality_create = c(FALSE,
TRUE), data_quality_execute = c(FALSE, TRUE), api_export = c(TRUE,
FALSE), api_import = c(FALSE, FALSE), mobile_app = c(FALSE,
Expand Down
Loading