User guide
REDCap API
This extension uses REDCap's API (application programming interface) to communicate with the REDCap server. The ability to use the API depends on REDCap user permissions, which can be granted by the REDCap instance administrator.
To use the extension, you must have API Export privileges in the project. Additional permissions, such as "De-Identified", "Remove All Identifier Fields", or "Full Data Set", can determine the scope of your access. User permissions can be granted by the REDCap instance administrator.
To use the extension, you need an API token, which will be used to authenticate all requests sent to the REDCap server. You will find it in the Applications / API page in REDCap's project menu. You may have to request the token first. The token is user-specific and valid for a specific project.
Consult the Help & FAQ section of your REDCap portal for details.
Usage example
In the example below we will demonstrate exporting data from a single form.
The extension operates in existing DataLad datasets. We start this example by creating an empty dataset:
datalad create my-project
cd my-project
Let's assume the form from which we want to export responses is called
"abcd" (note: if your form name contains spaces, you need to replace
them with underscores), and we want to save the export in a file named
abcd.csv
:
datalad export-redcap-form https://example.redcap.com/api/ abcd abcd.csv
If this is the first time you connect to this REDCap instance, you will be prompted for your API token (see Credentials section below). DataLad will then retrieve the form data, write them to the specified file, and save the change in the dataset.
Any time you need to update your dataset, you can repeat the export command:
datalad export-redcap-form https://example.redcap.com/api/ abcd abcd.csv
This will create a new commit if the exported data differs from your local copy (local content will be overwritten). If there are no changes, no new commit will be created. The file to which exported data are written must be in "clean" state, i.e., not have any changes that weren't saved in version control.
If you don't know the form name upfront, want to find out which forms
are available, or what exactly REDCap recognizes as a form name, you
can use the redcap-query
command:
datalad redcap-query https://example.redcap.com/api/
The export-redcap-form
command supports several additional
options. For example, you can export several forms into a single file,
choose not to include the survey identifier and timestamp columns, or
skip the saving step if you want to do datalad save
yourself,
later. To see the list of available options, you can use the
--help
parameter, just like for any other DataLad command:
datalad export-redcap-form --help
Note on git-annex
In the example above we created a new dataset with a default configuration, which means all files will be annexed (i.e. magaged by git-annex). Whether or not that is the desired behaviour (an alternative would be to track the files with Git) is ultimately up to you to decide.
Keep in mind that when it comes to creating dataset siblings, annexed files can be shared separately from the Git part of the dataset. And if you store annexed contents in remote hosting, you may also be interested in git-annex encryption options.
You can control which files are annexed vs tracked with Git using
the annex.largefiles
configuration option in the
.gitattributes
file.
Credentials
DataLad will store or retrieve your API token using your operating system's keyring service.
In general, the first time you connect to the REDCap server, you will
be prompted for the token. If data retrieval succeeds, you will also
be prompted to save and name the credential (with redcap-<api url>
being the default).
When you connect to the same REDCap instance again, DataLad will use, by default, the last credential successfuly used for that API URL.
If you have access to multiple projects on the same instance, you can
create differently named credentials and use the --credential
parameter, supported by all commands used to communicate with REDCap.
You can use the datalad credentials command from DataLad Next extension (which is installed as a dependency for the REDCap extension) to manage (e.g. query, set or remove) credentials known to DataLad.