https://github.com/lsgs/redcap-rest
REDCap external module enabling additional API functionality e.g. outbound calls
https://github.com/lsgs/redcap-rest
mcri murdoch-childrens redcap redcap-external-module redcap-repo
Last synced: 5 months ago
JSON representation
REDCap external module enabling additional API functionality e.g. outbound calls
- Host: GitHub
- URL: https://github.com/lsgs/redcap-rest
- Owner: lsgs
- License: gpl-3.0
- Created: 2022-08-25T03:19:27.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-05T20:17:46.000Z (over 1 year ago)
- Last Synced: 2025-03-05T21:42:00.902Z (over 1 year ago)
- Topics: mcri, murdoch-childrens, redcap, redcap-external-module, redcap-repo
- Language: PHP
- Homepage:
- Size: 58.6 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# REDCap REST
Luke Stevens, Murdoch Children's Research Institute https://www.mcri.edu.au
[https://github.com/lsgs/redcap-redcap-rest](https://github.com/lsgs/redcap-redcap-rest)
## Description
An external module enabling REDCap to send outbound API calls when saving data entry or survey forms and specified conditions are met. This can facilitate copying of data from your REDCap project to another application via its API, or to another REDCap project in either the same or a different instance of REDCap.
v1.4.0 introduces the facility for configuring sensitive configuration such as API or Autorization tokens at system level rather than hard-coding tokens into project module configuration. Use the placeholder `[token-ref:someref]` in place of your sensitive configuration value, and have your system administrator configure `someref` at system level. Tokens configured this way are also masked in logging.
## Limitations
* Initial implementation is of outbound API calls only.
* Initial implementation does not facilitate authentication mecahnisms like OAuth2.
## Configuration in Projects
Multiple outbound API messages can be configured via the External Modules Configure dialog.
**Enabled?**
* Check to enable a message.
**Trigger form(s)**
* One or more instruments for which the current message will be triggered.
**Trigger condition**
* *Optional*: REDCap logic expression that must evaluate to *true* for the current record in order for the message to be generated. Leave empty to always send on saving the trigger form(s).
**Destination URL**
* The URL of the endpoint the message will be sent *to*. Piping supported.
```
https://consentmgt.ourplace.org/api/record/[record_id]
```
**Payload**
* *Optional*: Textarea for specifying the form of the payload in JSON format. Piping supported, including of references to system-level token configuration.
```json
{
"consent": [consent],
"consent_date": "[consentdt]"
}
```
**Content Type**
* *Optional* Option to specify an alternative to 'application/json'.
**Additional Headers**
* *Optional* Additional headers along with Content-Type and Content-Length. Piping supported.
**cURL Options**
* *Optional* Key-value pairs for cURL settings, one pair per line in the notes box. Piping supported.
**Capture of Return Data**
API response data can be captured into fields within the same event as the triggering form.
**Result Field**
* *Optional* Select a field (e.g. a Notes-type field) in which to store the entire response (useful for debugging or for extracting values from complex reposnses using JavaScript).
**Response HTTP Code**
* *Optional* Record the HTTP code of the response to this field (useful for controlling behaviour based on success or otherwise of the API call).
**Map JSON Response Data to Fields**
* *Optional*, *Repeating* For JSON reponses, enter a property value to find in the response and a corresponding field name into which the property's value will be stored.
## Examples
### REDCap API
Call a REDCap API endpoint to obtain the value of field `[fieldtogetvaluefor]` for the record id piped in from field `[recordtofind]`:
* Destination URL: `https://redcap.someplace.edu/api/`
* HTTP Method: `POST`
* Payload form: `token=[token-ref:my-project-123-token]&content=record&type=flat&format=json&records=[recordtofind]&fields[]=record_id&fields[]=fieldtogetvaluefor`
* Content Type: `application/x-www-form-urlencoded` (note *not* `application/json`)
### Australia/New Zealand Clinical Trial Registry (https://anzctr.org.au/)
Obtain published details of a clinical trial identified using its ANZCTR ID (piped into paylod using `[anzctrid]`):
* Destination URL: `https://www.anzctr.org.au/WebServices/AnzctrWebservices.asmx`
* HTTP Method: `POST`
* Payload form:
```xml
[anzctrid]
```
* Content Type: `application/soap+xml; charset=utf-8`
### Basic Authentication
Send a payload to an API endpoint secured with Basic Auth, uncluding an encoded token as an HTTP header:
* Destination URL: `https://deep.thought.org/endpoint/`
* HTTP Method: `POST`
* Payload form:
```json
{ "answer":42 }
```
* Content Type: `application/json`
* Additional headers: `Authorization: Basic SWYgdGhhdCdzIHRoZSBhbnN3ZXIsIHdoYXQgaXMgdGhlIHF1ZXN0aW9uPw==`
or, better:
* Additional headers: `Authorization: Basic [token-ref:my-basic-auth-token]`
## Configuration of Sensitive Parameters at System Level (From v1.4.0)
Configure sensitive configuration such as API or Autorization tokens at system level rather than hard-coding tokens into project module configuration. Use the placeholder `[token-ref:someref]` in place of your sensitive configuration value, and have your system administrator configure `someref` at system level. Tokens configured this way are also masked in logging.
**Token Reference**
* Arbitrary unique reference or key for each token. Reference in project module settings in piping-style form as [token-ref:xyz] where xyz matches this reference.
**Token Destination URL**
* Token will only be used for requests to the specified URL. (Helps prevent exposure of token by directing requests to an arbitrary URL.)
**Token Lookup Option**
* Choose whether to specify the sensitive value or look up an API token for a project and user in the current instance of REDCap.
* Lookup: Read the token belonging to the specified user in the specified project.
* Specify: Enter the sensitive value directly.
**Token Lookup Option "Lookup": Project**
* The project to read a REDCap API token from.
**Token Lookup Option "Lookup": Username**
* The user to read a REDCap API token from.
**Token Lookup Option Specify**
* The specific value to utilise where configured, e.g. a token for Basic Authentication with an external API.