This development guide covers how to create an external module in REDCap. The external module developed in this guide is a simple (classic) ‘hello world’ example.

Skip to the hello world external module example (with code!)

How to get started creating an external module in REDCap?

Setup a development environment on your local machine. This should replicate your production environment as closely as possible. I do this using docker, here are some links which may help you get up and running on my development environments page.

You could set up one of these development environments, and then copy over the version of REDCap you are going to be using. In my case, I am going to be working with a few different versions to test compatibility:

• v8.8.2
• v9.1.8
• v10.6.17

Once you have your local dev env setup, the first step is to download the official REDCap external module template. You can download the files here https://github.com/vanderbilt-redcap/external-module-templater

Then, navigate to your external modules folder In my case, this was here for v9.1.8

www/redcap/redcap_v9.1.8/ExternalModules/example_modules

and similarly, here for v10.6.17

www/redcap/redcap_v10.6.17/ExternalModules/example_modules

create a new folder, called

companyname_ExternalModuleName_v0.1

Then copy the content of the external-module-templater-master folder. You should end up with a folder structure like this:

├── companyName_ExternalModuleName_v0.1
│   ├── LICENSE
│   ├── README.md
│   ├── Templater.php
│   ├── composer.json
│   ├── composer.lock
│   ├── config.json
│   ├── generate_template.php
│   ├── js
│   │   └── functions.js
│   └── templates
│       ├── README.twig
│       ├── class.twig
│       ├── config.twig
│       └── newModule.twig

How to install External Modules in REDCap?

To check if the previous steps actually worked, we need to install the external module in redcap. This will mean it can be seen and used by REDCap. In order to do this, navigate to control center, then from the left hand menu, select external modules, and enable a module.

You should see your new external module in this list, as shown below.

You have now completed the basic steps to setup a REDCap external module. The next section of this article has code for a basic hello world external module.

Basic Hello World External Module

How do we setup a very basic hello world external module?

Note; this code was developed using REDCap Version 10.6.17. All code is available from my github repository github.com/aalshukri/REDCap_ExternalModule_HelloWorld”.

Create a directory with the format <company>_<module name>_<version number> An example, would be company_HelloWorldModule_v0.1

Download the files from my repository https://github.com/aalshukri/REDCap_ExternalModule_HelloWorld.

You want to look at two files that are important to the running of this hello world example:

• config.json
• HelloWorldExternalModule.php

The first file, is the config.json.

This file has been updated with information on the external module, like description and author etc. But the really important part of the config.json is the permissions part. Note, how the module is requesting permission for redcap_data_entry_form. This is also reflected in the function call in HelloWorldExternalModule.php.

	"permissions": [
		"redcap_data_entry_form"
	],

Here is a sample of the HelloWorldExternalModule.php file. You will notice, the main function is named redcap_data_entry_form. The line print '<div class="yellow">Hello World.</div>'; simply acts as our hello world print statement, which is output as a line on the bottom of all input forms within the REDCap project.

    function redcap_data_entry_form(...)
    {
        print '<div class="yellow">Hello World.</div>';
    }

Now we have taken a look at the important files, we can look at enabling this module so we can see it working on REDCap.

Navigate to the control centre home in your REDCap instance and enable your ‘Hello World’ external module.

Once enabled, you should see your module listed as available on the system.

Once enabled on the REDCap system, we then need to enabled our hello world external module on a specific project. Navigate to the ‘External Module’ section.

From this page, you can now enable this module for your project.

Once this is enabled, then you can navigate to one of your projects CRFs, you should see the ‘hello world’ text displayed at the bottom of the data entry form, as shown below.

If you found this redcap external module development guide useful, and would like to see some of the other REDCap external modules I have built, or need advice, please reach out and contact me.