REDCap_Modules

Development work for REDCap External Modules/Packages to support a standardized Hook/Plugin framework and management mechanism

Installation

1. Clone this repo into to an external_modules directory under your REDCap web root.
2. Run sql/create tables.sql and then sql/migration-2017-01-18_10-03-00.sql on your redcap database to create the required tables.
3. In Control Center -> General Configuration -> REDCap Hooks, select the hooks.php file under the new external_modules directory.
   • If you wish to use a different hooks file, you can still add External Module support via the following steps:

     1. Insert the following at the top of your hooks file:

        require_once dirname(APP_PATH_DOCROOT) . '/external_modules/classes/ExternalModules.php';
        use ExternalModules\ExternalModules;
        

     2. Place the following line at the end of each function in your hooks file:

        ExternalModules::callHook(__FUNCTION__, func_get_args());
        

4. An External Modules section will now be available under both the Control Center and Project menus.

Usage

The best way to get started is to download the example module from here: https://github.com/mmcev106/redcap-external-module-example

It can be installed by downloading that repo as a ZIP file, then extracting it's contents to <redcap-web-root>/modules/vanderbilt_example_v1.0

Here are a few details on managing modules:

• Once installed, modules can be enabled under the Manage External Modules link under Control Center.
• Enabling a module under Control Center does not enable it on any projects by default.
• To enable a module on a specific project, go to the Manage External Modules link on the project homepage, click Search for Additional Module(s), and click Enable next to the desired module name. Then to configure a module, click Configure next to the module's name.
• To enable a module on ALL projects by default, go to the Manage External Modules link under Control Center, click Configure next to the module name, check the Enable on all projects by default checkbox, then click save.

The only setting that actually does anything in the example module is the Project Menu Background CSS setting. This will change the background color of the menu on project pages, and is a great demo of simple hook usage, and how a setting can be set systemwide and/or overridden per project.

AbstractExternalModule

The AbstractExternalModule class must be extended when creating an external module. Module creators may make use of the following methods to store and manage settings for their module. This includes both settings set via the Manage External Modules interface, as well as any other data the module creator wants to store:

Method	Description
setSystemSetting($key, $value)	Set the setting specified by the key to the specified value systemwide (shared by all projects).
getSystemSetting($key)	Get the value stored systemwide for the specified key.
removeSystemSetting($key)	Remove the value stored systemwide for the specified key.
setProjectSetting($key, $value [, $pid])	Set the setting specified by the key to the specified value for this project (override the systemwide setting). In most cases the project id can be detected automatically, but it can optionaly be specified as the third parameter instead.
getProjectSetting($key [, $pid])	Returns the value stored for the specified key for the current project if it exists. If this setting key is not set (overriden) for the current project, the systemwide value for this key is returned. In most cases the project id can be detected automatically, but it can optionaly be specified as the third parameter instead.
removeProjectSetting($key [, $pid])	Remove the value stored for this project and the specified key. In most cases the project id can be detected automatically, but it can optionaly be specified as the third parameter instead.
getUrl($path)	Get the url to a resource (php page, js/css file, image etc.) at the specified path relative to the module directory.
hasPermission($permissionName)	checks whether the current External Module has permission for $permissionName
getConfig()	get the config for the current External Module; consists of config.json and filled-in values
getModuleDirectoryName()	get the directory name of the current external module
getModuleName()	get the name of the current external module
delayModuleExecution()	pushes the execution of the module to the end of the queue; helpful to wait for data to be processed by other modules; execution of the module will be restarted from the beginning

How to Create an External Module from the Example

External Modules combine the concepts of REDCap Plugins and REDCap Hooks. They consist of hooks and plugin (webpages) that work under configurable settings. Individual Hooks and Plugins are best for projects that need specific and peculiar customization. External Modules are best for general functions that are needed by many projects. Hooks and Plugins can even import External Modules and customize their functionality if everything is configured properly.

1. Copy an existing External Module into a new directory named __v1.0/.

2. Change the filename of the ** ExternalModule.php* file to ExternalModule.php with the first letter capitalized. This will now be called The External Module File. This will contain all of the hook information.

3. Change the name of the class and the namespace to *ExternalModule with the first letter capitalized, just as in changing the directory name. This should extend the AbstractExternalModule class.

   • Enter in your hook name, beginning with hook_ instead of redcap_. Also, enter in your parameters listed in the REDCap documentation. Like
     • function hook_save_record($project_id, $record, $instrument, $event_id, $group_id)
   • Fill in all of the hooks like above. You can also add helper methods or reference outside classes.
   • Make note of all of the hooks used. We will have to grant them permission in the configuration JSON.

4. Open the PHP code to any plugin webpages. These will just run as stand-alone webpages within the External Module infrastructure. To access External Module settings, include ../../external_modules/classes/ExternalModules.php and use the appropriate public functions.

5. Open the config.json file. This is a JSON used to specify the External Module.

   • Fill in the name
   • Fill in the description
   • Fill in the name and email for authors. At least one email is required to run the module.
   • Grant permissions for all of the operations. Start with hook_.... For example, hook_save_record.
   • links specify any links to show up on the left-hand toolbar. These include stand-alone webpages (substitutes for plugins) or links to outside websites. These are listable at the control-center level or at the project level. A link consists of:
     • A name to be displayed on the site
     • An icon in REDCap's image repository
     • A url either in the local directory or external to REDCap.
   • system-settings specify settings configurable at the system-wide level (this Control Center). Individual projects can override these settings.
   • project-settings specify settings configurable at the project level, different for each project.
   • A setting consists of:
     • A key that is the unique identifier for the item. Dashes (-'s) are preferred to underscores (_'s).
     • A name that is the plain-text label for the identifier. You have to tell your users what they are filling out.
     • required is a boolean to specify whether the user has to fill this item out in order to use the module.
     • type is the data type. Can be: text
       • json
       • textarea
       • rich-text
       • field-list
       • user-role-list
       • user-list
       • dag-list
       • dropdown
       • checkbox
       • project-id
       • form-list
       • sub_settings
       • radio
       • file
     • choices consist of a value and a name for selecting elements (dropdowns, radios).
     • repeatable is a boolean that specifies whether the element can repeat many times. If it is repeatable (true), the element will return an array of values.
     • When type = sub_settings, the sub_settings element can specify a group of items that can be repeated as a group if the sub_settings itself is repeatable. The settings within sub_settings follow the same specification here.
       • Repeatable elements of repeatable elements are not allowed. Only one level of repeat is supported.
       • sub_settings of sub_settings are not supported either.
     • As a reminder, true and false are specified as their actual values (true/false not as the strings "true"/"false"). Other than that, all values and variables are strings.
   • If your JSON is not properly specified, an Exception will be thrown.

6. All run-time errors throw Exceptions that generate emails, so be careful.

7. You can use the REDCap class by \REDCap inside of the External Module.