REDcap Server and RADAR-base Integration confg

Owned by Yatharth Ranjan
Last updated: Dec 13, 2019 by Amos Folarin

eIn REDCap, it is possible to set a Data Entry Trigger as  an advanced feature. It provides a way for REDCap to trigger a call to a remote web address (URL), in which it will send a HTTP POST request to the specified URL whenever any record or survey response has been created or modified on any data collection instrument or survey in this project (it is nottriggered by data imports but only by normal data entry on surveys and data entry forms). Its main purpose is for notifying other remote systems outside REDCap at the very moment a record/response is created or modified, whose purpose may be to trigger some kind of action by the remote website, such as making a call to the REDCap API.

For setting a Data Entry Trigger

  1. login in a REDCap project using a project admin account
  2. go to Project Setup view
  3. go to Enable optional modules and customisations and click to Additional customisations
  4. add a valid URL
  5. verify if the URL is accessible from REDCap
  6. enable Data Entry Trigger
  7. click on Save

This project exposed a REST endpoint located at <host>:<port>/redcap/trigger or <host>/redcap/trigger is mapped 8080 port.

It is highly recommended to use an encrypted connection (i.e. SSL/HTTPS) for accessing set Data Entry Trigger.



Central Server Spec

For RADAR-CNS we are using Redcap version 7.4.10 (the current LTS)


  • Ubuntu 16.04 server (VM)
    • 2 cpu, 4GB RAM
    • 40GB boot
    • 100GB redcap-data disk
  • Install LAMP stack
    • Mysql on same server
    • Data on the data volume




Server (L)AMP Config


PHP, APACHE


Mysqld

Remove anonymous users? (Press y|Y for Yes, any other key for No) : y
 Disallow root login remotely? (Press y|Y for Yes, any other key for No) : y
 Remove test database and access to it? (Press y|Y for Yes, any other key for No) : y
 Reload privilege tables now? (Press y|Y for Yes, any other key for No) : y

  • CREATE USER 'redcap_user'@'%' IDENTIFIED BY 'YOUR_REDCAP_DB_PWD';
  • GRANT SELECT, INSERT, UPDATE, DELETE ON `redcap`.* TO 'redcap_user'@'%';
  • Salt: SALT_STRING


Setup TLS, Use commercial cert vendor or Let's Encrypt 

    • Acmetool is apparently the prefered agent these days



RedCap Installation

  • Copy installation folder to /
  • Install some php modules 
    • apt-cache search php- | less
    • apt-get install php-curl, php-xml, php-zip, php-gd, php-mbstring ...etc see config check for full set (requires apache restart before modules are available)
  • IMPORTANT
    • Once everything is installed and email smtp setup create a new user then elevate them to the administrator privileged, if you don't do this and you enable "Table Based Authentication" you will be locked out of your installation!!!, you won't be able to create a password until you enable Table Based Authentication but you must already have created the user and have received the password update link.


Post Installation

  • Setup a special user that is used by the RADAR platform to handle integration between the REDCap and the RADAR Management Portal.
    • Username: "radarintegration" user permissions (see below)





  • This user should also have an API token generated for them (see below)

This user should also have an API token generated for them (see below)





Use this Callback URL https://radar-cns-platform.rosalind.kcl.ac.uk/redcapint/trigger/


To complete the registration: you'll need to email the radar-platform administrators to add the project to the Management Portal integration. To complete this we'll need the following radar.yml file:


redcap_info:
  url: #URL pointing to the REDCap instance
  project_id: #REDCap project identifier e.g. 13
  enrolment_event: #Unique identifier for the enrolment event e.g. enrolment_arm_1
  token: #REDCap API Token used to identify the REDCap radarintegrtation user

The radar platform admins will create a new project for you in the Management Portal that is linked to to your Redcap Project, when you create users in Redcap and save any form the corresponding user will be created in the Management Portal.



SMTP config


Users

  • It is possible to allocate a manager for the project who can create new users
  • It is probably worth setting up Regular User and Admin roles for each the project


Project Naming Convention

  • There are some constraints about the naming convention for projects


  • Currently for integration app to work properly, the REDCap projects should have a canonical structure
  • [Name]-[SubName1]-[SubName2]-[SubName3]
  • For RADAR studies typically namespaced like so: Subname1=Disease, SubName2=PartnerSite, SubName3=StudyNumberString
    • e.g. RADAR-MDD-KCL-s1 for KCL's Depression Study
  • Both REDCcap and the Management Portal projects MUST have the same name exactly.
  • "Work package" in ManagementPortal Project Configuration is taken as a combination of [SubName1]-[SubName2]




radar.yml Configuration File

# Set of supported projects

# ManagementPortal configuration
oauth_client_id: YOUR-OAUTH-CLIENT-ID
oauth_client_secret: YOUR-OAUTH-SECRET
management_portal_url: http://management-portal:8080/managementportal/
token_endpoint: oauth/token
project_endpoint: api/projects/
subject_endpoint: api/subjects

# Set of supported projects
projects:
  - redcap_info:
      url: #URL pointing REDCap instance
      project_id: #REDCap project identifier e.g. 13
      enrolment_event: #Unique identifier for the enrolment event  e.g. enrolment_arm_1
      integration_form: #Name of integration REDCap form e.g. radar_integration
      token: #REDCap API Token to identify the REDCap user e.g radarintegrtation user 
    mp_info:
      project_name: #Management Portal project name



Management  Portal Configuration

Some configuration in the ManagementPortal Project Settings is also required:


The Project in Management Portal

In the name structure should match the REDCap project. Also see above for the canonical structure of project name this is  important.



REDCap From Email Address and No-Reply Email Address


Do you have the no-reply email in the "Set a universal 'FROM' email address for *all* emails sent from REDCap" option on the General Configuration page in the Control Center? If so, then "all" emails will show that they were sent from that email address.