1 Deployment and Download
2 Installation
- 2.1 Installation of REDCap PHP Plugin
- 2.2 Installation of OpenSpecimen plugin
3 Update REDCap PHP Plugin
4 How to check the plugin version?

Deployment and Download

The integration requires two separate components to be installed on their respective servers. Both must be configured correctly to enable data synchronization.

Component	Installation Target	How to Obtain
REDCap PHP Plugin	REDCap Web Server	Click here to download or contact the Krishagni team.
OpenSpecimen Plugin	OpenSpecimen App Server	Contact the Krishagni team to request the latest JAR file.

Installation

Installing these plugins on the remote server helps share data or information across datasets. There are two parts to this process:

Installation of REDCap PHP Plugin

The standard REDCap APIs do not support the functionalities we need. OpenSpecimen needs data and metadata of each instrument, including only delta changes since the last sync run.

To avoid this, Krishagni has developed a REDCap plugin which exposes additional APIs using the REDCap audit logs and internal APIs.

Log in to the REDCap server and navigate to the REDCap install directory containing the file redcap_connect.php and database.php files.
The following are example commands executed in our dev environment.

$ cd /home/var-www/html/redcap/
$ ls database.php redcap_connect.php
database.php  redcap_connect.php

Create a new 'plugins' directory if not present.

$ mkdir -p plugins

Copy the REDCap_PHP file to the plugin's directory.

$ cp $RC_OS_PLUGIN/openspecimen_plugin.php plugins

To ensure the plugins are correctly installed, you can use the following API with the HTTP client of your choice, or run the commands shown below.

Below is an example done using Postman
1. Replace <host> with hostname where REDCap server is deployed
2. Replace <Project API token> with actual API token issued for accessing REDCap project using APIs
3. In response, you should see the REDCap audit log events nicely formatted using JSON.

The following commands should succeed with printing JSON string on the console.
1. RC_HOST - URL of the REDCap server. E.g. https://redcap.openspecimen.org
2. RC_DOCROOT - Document root of the REDCap server. E.g. /, /r
3. OS_PLUGIN - Relative path of the OpenSpecimen REDCap plugin w.r.t document root. E.g. /plugins/openspecimen_plugin.php

Test Project Details

$ curl -X POST -D "token=<Project API token>" -d "content=project" -d "format=json" -d "returnFormat=json" $RC_HOST/$RC_DOCROOT/api/

Example command:
curl -X POST -d "token=xxxx" -d "content=project" -d "format=json" -d "returnFormat=json" https://redcap.openspecimen.org/r/api/
// project details JSON

Output

<!DOCTYPE html>
<html>
<head>
<title>REDCap Project</title>
</head>
<body>
........
</body>
</html>

Test Events list

$ curl -X POST -d "token=<Project API token>" -d "content=event" -d "format=json" -d "returnFormat=json" $RC_HOST/$RC_DOCROOT/$OS_PLUGIN
// events list JSON

Example command:
curl -X POST -d "token=xxxx" -d "content=event" -d "format=json" -d "returnFormat=json" https://redcap.openspecimen.org/r/plugins/openspecimen_plugin.php

Output
>>[{"event_id":"40","day_offset":"1","offset_min":"0","offset_max":"0","event_name":"Event 1","arm_num":"1","repeatable":"0"}]

Please contact your REDCap system admin for these steps. There might be slight differences based on the REDCap version, operating system, etc.

Installation of OpenSpecimen plugin

Exact the JAR file from your downloaded zip file.
Login to your OpenSpecimen server and navigate to the $TOMCAT_HOME/bin directory.
Stop the tomcat service using the command:
./shutdown.sh force
Now, navigate to the $plugins/paiddirectory and remove an older copy of the REDCap-OpenSpecimen plugin (if any) and copy the current version.
Navigate back to the $TOMCAT_HOME/bin directory and restart the Tomcat service using the command:
./startup.sh

Update REDCap PHP Plugin

To update the existing REDCap PHP plugin with a new one, please follow the steps below:

Rename Old Plugin
$ cp <plugin_name>.php to <plugin_name>.php.old
Copy the new plugin to the required folder.
$ cp <path-to-downloaded-plugin>/data_log_events.php <plugin_name>.php

<plugin_name> is the name chosen by the REDCap admin during the first install and used in the OpenSpecimen configurations.

How to check the plugin version?

Use the below command to check the version of the plugin installed on the REDCap server-side

PHP plugin version

$ curl -X POST -d "token=<Project API token>" -d "content=version" -d "format=json" -d "returnFormat=json" $RC_HOST/$RC_DOCROOT/$OS_PLUGIN

Example command:
curl -X POST -d "token=xxxx" -d "content=version" -d "format=json" -d "returnFormat=json" https://redcap.openspecimen.org/r/plugins/openspecimen_plugin.php

Output

>>{"version":"2020-10-12T07:58:48.225Z"} (Before OS v8.2)
>>{"version":"2021-10-11T09:30:00.000Z"} (After OS v8.2)
>>{"version":"2024-04-30T06:53:49.691Z"} (After RCv14 support)