2.6.0

Project.toml

@@ -1,7 +1,7 @@
 name = "REDCap"
 uuid = "ba918724-fbf9-5e4a-a61c-87e95654e718"
 authors = ["Cory Cothrum", "Dilum Aluthge <[email protected]>", "Ashlin Harris <[email protected]>"]
-version = "2.5.1"
+version = "2.6.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

src/REDCap.jl

@@ -1,13 +1,10 @@
-#TODO: are paramaters always camel case, and attributes always snake case?
-#TODO: documents this
-#TODO: change function names based on this?
-#
-# use DataFrames style arguments in 3.0 (unroll data parameter)
 #TODO: some import methods can be used to delete entries
 # Should this behavior be migrated to delete_* functions?
 
 """
 REDCap API methods are defined as named Julia functions.
+The named arguments of the Julia functions each correspond to the API parameters.
+REDCap API parameters seem to always have camelCase names, and parameters that share a name generally have the same behavior and accepted values.
 
 REDCap API calls generally include a `content` and `action` parameter.
 
@@ -50,7 +47,10 @@ If you have a super token, you might wish to keep that in your startup file, gen
 ### `data`
 The `data` parameter contains a list of attributes, which varies between REDCap methods.
 For definitive attribute lists, see the official REDCap documentation.
-In REDCap.jl, this can be a NamedTuple (or any derived type), a file handle, or a String.
+These attributes generally have camel_case names.
+
+In REDCap.jl, the corresponding `data` argument is implemented as a Collection.
+This can be a NamedTuple or a Dict, as well as a file handle or String.
 If you use a NamedTuple, it will be translated internally into whatever `format` you use (xml by default).
 ```julia
 import_project_info(

src/api_methods/logging.jl

@@ -8,7 +8,7 @@ Export mappings of data collection instruments onto designated Events for a long
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
 - `format`: the desired output format: `:csv`, `:json`, or `:xml` (default)
-- `logtype`: optionally limit output to an event type (export, manage, user, record, record_add, record_edit, record_delete, lock_record, page_view)
+- `logtype`: optionally limit output to an event type (`export`, `manage`, `user`, `record`, `record_add`, `record_edit`, `record_delete`, `lock_record`, `page_view`)
 - `user`: optionally limit output to a specific user
 - `record`: optionally limit output to a specific record
 - `dag`: optionally limit output to a specific Data Access Group (DAG)

src/api_methods/projects.jl

@@ -6,7 +6,7 @@ Create a new REDCap project
 # Named arguments
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
-- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Availabel attributes are project_title, purpose, purpose_other, project_notes, is_longitudinal, surveys_enabled, and record_autonumbering_enabled.
+- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Availabel attributes are `project_title`, `purpose`, `purpose_other`, `project_notes`, `is_longitudinal`, `surveys_enabled`, and `record_autonumbering_enabled`.
 - `format`: the format of the `data` input parameter: `:csv`, `:json`, or `:xml` (default). If `data` is a String or a file name, this value must indicate the correct format. If `data` is a NamedTuple, Dict, or similar type, this value will determine what format will be used internally to pass on the data.
 - `returnFormat`: the desired output format: `:csv`, `:json`, or `:xml` (default)
 
@@ -75,7 +75,7 @@ Import basic attributes of a REDCap project
 # Named arguments
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
-- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Availabel attributes are 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, iand bypass_branching_erase_field_prompt.
+- `data`: May be a String`, `a file name`, `or a data type such as NamedTuple or Dict. Available attributes are `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`, and bypass_branching_erase_field_prompt`.
 - `format`: the format of the `data` input parameter: `:csv`, `:json`, or `:xml` (default). If `data` is a String or a file name, this value must indicate the correct format. If `data` is a NamedTuple, Dict, or similar type, this value will determine what format will be used internally to pass on the data.
 
 """

src/api_methods/records.jl

@@ -47,7 +47,7 @@ Export records from a REDCap project
 - `rawOrLabelHeaders`: (for `:flat` type, `:csv` format only) raw or label CSV headers
 - `exportCheckboxLabel`: toggle format of checkbox field values (false by default)
 - `exportSurveyFields`: optionally export survey identifier and timestamp fields (false by default)
-- `exportDataAccessGroups`: optionally export the "redcap_data_access_group" field (false by default)
+- `exportDataAccessGroups`: optionally export the `redcap_data_access_group` field (false by default)
 - `filterLogic` : optionally filter records based on a logic string
 - `dateRangeBegin`: optionally limit output to records created or modified after a given datetime
 - `dateRangeEnd`: optionally limit output to records created or modified before a given datetime

src/api_methods/user_roles.jl

@@ -62,7 +62,7 @@ Import role assignments to a REDCap project
 # Named arguments
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
-- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Available attributes are user_name, unique_role_name, and data_access_group.
+- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Available attributes are `user_name`, `unique_role_name`, and `data_access_group`.
 - `format`: the format of the `data` input parameter: `:csv`, `:json`, or `:xml` (default). If `data` is a String or a file name, this value must indicate the correct format. If `data` is a NamedTuple, Dict, or similar type, this value will determine what format will be used internally to pass on the data.
 - `returnFormat`: the desired output format: `:csv`, `:json`, or `:xml` (default)
 
@@ -75,16 +75,21 @@ function import_user_role_assignments(; url=get_url(), token=get_token(), format
 	)
 end
 
-#TODO: for both import functions (?), You have to clear the unique_role_name column to import the roles you've exported from another project
+#TODO: handle unique_role_name constraint within API
+#TODO: does disclaimer apply to other functions?
+#TODO: a bare record number return value isn't so useful - add a helpful info message with the meaningm including confirmation of success
+#TODO: This won't overwrite existing roles of the same name!
 """
-	function import_user_roles(; url=get_url(), token=get_token(), format=nothing, returnFormat=nothing, data,
+	function import_user_roles(; url=get_url(), token=get_token(), format=nothing, returnFormat=nothing, data,)
 
 Import roles to a REDCap project
 
+An important REDCap API note: `unique_role_name` is generated by REDCap and must be left blank. You have to clear the unique_role_name column to import the roles you've exported from a project.
+
 # Named arguments
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
-- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Available attributes are unique_role_name, role_label, design, alerts, user_rights, data_access_groups, reports, stats_and_charts, manage_survey_participants, calendar, data_import_tool, data_comparison_tool, logging, email_logging, file_repository, data_quality_create, data_quality_execute, api_export, api_import, api_modules, mobile_app, mobile_app_download_data, record_create, record_rename, record_delete, lock_records_customization, lock_records, lock_records_all_forms, forms, and forms_export.
+- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict. Available attributes are `unique_role_name`, `role_label`, `design`, `alerts`, `user_rights`, `data_access_groups`, `reports`, `stats_and_charts`, `manage_survey_participants`, `calendar`, `data_import_tool`, `data_comparison_tool`, `logging`, `email_logging`, `file_repository`, `data_quality_create`, `data_quality_execute`, `api_export`, `api_import`, `api_modules`, `mobile_app`, `mobile_app_download_data`, `record_create`, `record_rename`, `record_delete`, `lock_records_customization`, `lock_records`, `lock_records_all_forms`, `forms`, and `forms_export`.
 - `format`: the format of the `data` input parameter: `:csv`, `:json`, or `:xml` (default). If `data` is a String or a file name, this value must indicate the correct format. If `data` is a NamedTuple, Dict, or similar type, this value will determine what format will be used internally to pass on the data.
 - `returnFormat`: the desired output format: `:csv`, `:json`, or `:xml` (default)
 
@@ -96,5 +101,6 @@ function import_user_roles(; url=get_url(), token=get_token(), format=nothing, r
 		data=REDCap_data(data,REDCap_format(format),xml_tag="users"),
 		kwargs = (; token=REDCap_token(token), content=:userRole, format=REDCap_format(format), returnFormat=REDCap_format(returnFormat),),
 	)
+	@info "Return value is number of roles added"
 end
 

src/api_methods/users.jl

@@ -1,13 +1,22 @@
+#TODO: ensure user has delete records privilege (way to automate this?)
+#TODO: shouldn't it be users=users?
 """
-	function delete_users(; url=get_url(), token=get_token(), users)
+	function delete_users(; url=get_url(), token=get_token(), users=users)
 
-Delete users from a REDCap project
+Delete users from a REDCap project (must have delete records privilege)
 
 # Named arguments
 - `url`: (read from `ENV["REDCAP_API_URL"]` by default)
 - `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
 - `users`: user names (can be scalar or vector)
 
+# Example
+
+```
+julia > delete_users(users = [:user1,  :user2])
+```
+
+
 """
 function delete_users(; url=get_url(), token=get_token(), users)
 	REDCap.request(

src/types.jl

@@ -9,7 +9,7 @@ REDCap_datetime(x::Nothing) = nothing
 struct REDCap_format
 	id
 	REDCap_format(id::Symbol) = REDCap_format(string(id))
-	REDCap_format(id::String) = lowercase(id) ∈ Set(["csv","json","xml"]) ? new(Symbol(id)) : throw(ArgumentError("Invalid format parameter"))
+	REDCap_format(id::String) = id ∈ Set(["csv","json","xml"]) ? new(Symbol(id)) : throw(ArgumentError("Invalid format parameter (must be :csv, :json, or :xml"))
 	REDCap_format(id::Nothing) = nothing
 end
 Base.display(x::REDCap_format) = Base.display(x.id)
@@ -55,7 +55,6 @@ end
 #TODO: someway to throw an error if there's no comma to make the args a NamedTupe? unfold to pairs::Pairs..., as in DataFrames
 #TODO: consider converting all collections to NamedTuples, then to string?
 REDCap_data(x::NamedTuple, format::Union{REDCap_format,Nothing}; xml_tag=nothing) = REDCap_data(x |> pairs |> Dict, format, xml_tag=xml_tag)
-#TODO: Remove this for 3.0.0 (On the other hand, it's very convenient)
 REDCap_data(x::String, format::Union{REDCap_format, Nothing}; xml_tag=nothing) = x
 #TODO: handle large files?
 REDCap_data(x::IOStream, format::Union{REDCap_format, Nothing}; xml_tag=nothing) = read(x,String)