/
SureAdhere to EDC API Specification

SureAdhere to EDC API Specification

Overview

The Data Transfer Specification (DTS) describes the user and functional requirements for the implementation of a data integration between Dimagi SureAdhere system and Medidata Rave EDC of a study. The requirements contained in this document will be used as the basis to design, build and test a data transfer solution.

Data Transfer Overview

  1. Data Transfer Type: EDC for “Clinical Data - Exposure”

  2. Transfer type Frequency: Real time

  3. Direction: Two Way

    1. SureAdhere into EDC

    2. Patient data (including trial arm) from EDC system

  4. Transfer Method:  Web services

  5. Unblinded Data Points: No 

Critical Data Points: Yes

Data Transfer Credentials

It is expected that the client will provide Dimagi with at least 2 separate accounts with appropriate permissions for the purpose of the integration: one with access for testing environment (TEST, UAT, DEV, etc…) and the other with production access only.

The account with access to production should not have access to any of the testing environments. 

File Transport and Data Transfer Assumptions

  1. The Rave_Web_Services_for_Rave_5.6.4_User_Guide_(ENG).pdf was used to write this specification 

  2. Rave Web Service (RST) uses the REST architecture.

  3. XML document compatible with the CDISC ODM v1.3 schema and should be encoded as UTF-8.

  4. A Rave Web Service URL will be provided. Specific to client. See Client-Specific Elements below.

  5. This integration will

    1. POST data to RWS

    2. GET patient data from EDC 

  6. Both Rave Forms are for log lines

  7. The maximum length (bytes) of a POST of Clinical Data is 1,000,000 bytes

  8. RWS (API) is up and running prior to all Web Service calls

  9. Dimagi is provided a dedicated user account with sufficient permissions to update subject forms in the EDC system

Variables

This table provides specific information about generic variables that are required to populate the XML files described in the following sections.

 

XML Variable

Definition

File#

A string to specify Exposure XML

DateTime

Date and time of file creation in SureAdhere in yyyy-mm-ddThh:nn:ss format (e.g. “2008-01-25T13:45:12”).

  • If null data will be sent as “” (i.e., an empty string)

  • All dates and times will be sent in Client Time zone (ie country time zone)

StudyOID

Study OID will depend on the environment (dev, UAT, or production). See Client-Specific Elements below.

SubjectKey

Client can define subject key format. Dimagi will not perform any validation on subject key.

LocationOID

3-Character site number

By default, the LocationOID will reference the Client Division ID in EDC.

Error Handling

  1. For every transaction, RWS returns a response, and, if there is an error, an error description and error location in XPath notation. A list of response codes is provided in the Rave Web Services API Guide. 

  2. RWS checks the request XML in two ways: by checking that it is valid XML and by checking it against the ODM v1.3 schema 

  3. It isn’t possible to show web app users/nurses error messages about the success or failure of the integration, as the requests will be queued and sent to Rave asynchronously.

  4. It is essential that errors returned regarding the wrong drugs for a patient are dealt with in a timely manner as the patient could be on the incorrect arm/regimen

  5. The SureAdhere system shall log the details of each web service call that is made to RWS, with all log entries available for the internal technical team to review.

  6. The SureAdhere system shall continue attempting to send data to RAVE service and if RAVE is unavailable for any reason, SureAdhere system will attempt to send the data until the data has been sent successfully or the configured maximum failed send attempts is reached (default = 3).

The SureAdhere system shall generate logs for any error codes.

Support for Integration Failures

  1. Errors regarding subject ID or Site -> contact client

  2. Errors regarding Forms -> contact client

  3. System errors from Rave -> Medidata support & client

Web Service Integration Specification

Web Service Call Specification

This section describes the process that the SureAdhere system uses to call into the Rave EDC RWS to transfer XML files that are created after user actions are performed in the SureAdhere web app

  1. Each of the ODM XML files will be sent as the body of an HTTPS POST request.

  2. The content type of the document must be set as text/xml and should be encoded as UTF-8.

  3. All POSTs to RWS are for Log Lines, so must be called with TransactionType of Update

  4. Each Log line must be unique and no duplicates can be created. This is essential for searching for a log line to update or remove else it is not possible to match for an update/remove and error is “Unique log line not found”.

  5. All <ItemData> fields must have values, even if “” (empty string), for an insert 

  6. A response message is generated by RWS that includes the field IsTransactionSuccessful. If the value of this field is 1, the transfer is successful and complete. If the value of the field is 0, the transfer is unsuccessful

  7. Unsuccessful transactions must be logged, assessed and resolved manually.

The response message also includes NewRecords which confirm the insertion of log lines and provides details of the inserted repeat key.

Example Successful Response Message

<Response ReferenceNumber="aacbaffe-8eed-45d7-bfe3-4916f4935af4" InboundODMFileOID="FromSureAdhereApp" IsTransactionSuccessful="1" SuccessStatistics="Rave objects touched: Subjects=0; Folders=0; Forms=0; Fields=4; LogLines=0" NewRecords=""></Response>

Example Failed Response Message

<Response ReferenceNumber="7127e3d0-92e3-4448-97b2-d6338de897f2" InboundODMFileOID="FromSureAdhereApp" IsTransactionSuccessful="0" ReasonCode="RWS00041" ErrorOriginLocation="/ODM/ClinicalData[1]/SubjectData[1]/StudyEventData[1]/FormData[1]/ ItemGroupData[1]/ItemData[1]" SuccessStatistics="Rave objects touched: Subjects=0; Folders=0; Forms=0; Fields=0; LogLines=0" ErrorClientResponseMessage="Field does not exist."></Response>

Notes

  • ReferenceNumber is a 256 bit alphanumeric unique identifier for the transaction. Used for requesting support for failed transactions.

  • SuccessStatistics shows how many Rave objects have been touched (created, updated, or removed). This can be compared against expectations to verify that the import has worked as desired.

  • NewRecords confirms insertions of log lines, and provides details of the inserted repeat key

Exposure Log Lines

Process Description

This section provides information on the SureAdhere functions that trigger XMLfile creation and transfer into the Rave EDC system.

  1. When a user in the SureAdhere system presses the “Submit for Review” button on the dose details tab on Adherence screen, SureAdhere will generate XML to update the EDC Exposure Form to indicate dose taken

    1. There is the scenario when the patient uses the mobile device to record an “In Person DOT”, then this information recorded on the device is automatically sent from the device, to the server and then to RAVE

  2. NOTE: SureAdhere will send data to RAVE on pills taken by patients

    1. Every day a dose is expected to be taken AND the nurse using SureAdhere presses the “Submit for Review” button on the dose details tab on Adherence screen, this data will be sent to RAVE

    2. NOTE: If a nurse does not edit and press the “Submit for Review” button on the Adherence screen, then NO data can be sent to RAVE. This scenario must be handled by training and processes

    3. If the days drugs are not taken and the dose is effectively missed, the data will still be sent to RAVE

  3. Rules and data validation is needed to reduce risk of updating RAVE multiple times if a user is making multiple edits

  4. Frequency: We are assuming 1 exposure log upload per patient per day per drug

  5. Update: And due to staff/users of the web app making changes to a patient's information if they make a mistake or update details for a day, we may get a few additional updates per patient per week. 

  6. If a drug is changed from having pills taken to having 0 pills taken, then 0 pills taken will be sent to RAVE

  7. NOTE: SureAdhere will NEVER do a removal of an Exposure Log Line.

Edit Checks/Validations in SureAdhere

  1. Start Date will never be “”. 

  2. Each Log line will be unique by SubjectID and StartDate

  3. Dose Prescribed Unit (mg) will always be “mg” - the SureAdhere systems does not store if a liquid

  4. Number of Tablets Taken can be 0 if the patient self reports 0 pills with mobile app as does not take one of the drugs for the day

  5. StartTime will be “” to indicate there was no Self Report, Video or In person DOT Event. And then “Mode of Observation” will also be  “”

  6. Mode of Observation can be “” (empty string)

Form Specifications

Exposure: Daily Adherence Reports

FolderName: Study Medication

Medication Exposure Form

StudyEvent OID

TRIALINTERVENTION

Form OID:

Specific to client. See Client-Specific Elements below.

Trigger(s):

When a user in the SureAdhere system presses the “Submit for Review” button on the dose details tab on Adherence screen

StudyEventRepeatKey

N/A

ItemGroupRepeatKey

@context

Dependencies:

N/A

Item Name 

Item OID

Data Format

SureAdhere Mapping

Start Date

EXSTDAT

DateTime dd MMM yyyy

medicationStartDate

Start Time

EXSTTIM

HH:nn (24 hr clock)

doseTimeSubmission

Number of Tablets Prescribed

EXPNUM

Text $5.2

numberOfTabletsPrescribed

Number of Tablets Taken

EXNUM

Text $5.2

numberOfTabletsTaken

Mode of Observation

EXMODE

Text $50

modeOfObservation

Taken within one hour of eating

EXFOOD

Text $3

withFood

Insert

<ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" ODMVersion="1.3" FileType="Transactional" FileOID="SureAdhereDose" CreationDateTime="2022-07-03T00:00:00"> <ClinicalData StudyOID="<Study OID>" MetaDataVersionOID="1"> <SubjectData SubjectKey="999-888-7777" TransactionType="Update"> <SiteRef LocationOID="999"/> <StudyEventData StudyEventOID="SM" StudyEventRepeatKey="1" TransactionType="Update"> <FormData FormOID="EX" TransactionType="Update"> <ItemGroupData ItemGroupOID="EX" ItemGroupRepeatKey="@CONTEXT" TransactionType="Upsert"> <ItemData ItemOID="EXSTDAT" TransactionType="Context" Value="04 JUL 2025"/> <ItemData ItemOID="EXSTTIM" TransactionType="Upsert" Value="14:00"/> <ItemData ItemOID="EXPNUM" TransactionType="Upsert" Value="1"/> <ItemData ItemOID="EXNUM" TransactionType="Upsert" Value="1"/> <ItemData ItemOID="EXMODE" TransactionType="Upsert" Value="VDOT Recorded"/> <ItemData ItemOID="EXFOOD" TransactionType="Upsert" Value="yes"/> </ItemGroupData> </FormData> </StudyEventData> </SubjectData> <AuditRecords /> <Signatures /> <Annotations /> </ClinicalData> </ODM>

Update

<ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" ODMVersion="1.3" FileType="Transactional" FileOID="SureAdhereDose" CreationDateTime="2022-07-03T00:00:00"> <ClinicalData StudyOID="<Study OID>" MetaDataVersionOID="1"> <SubjectData SubjectKey="999-888-7777" TransactionType="Update"> <SiteRef LocationOID="999"/> <StudyEventData StudyEventOID="SM" StudyEventRepeatKey="1" TransactionType="Update"> <FormData FormOID="EX" TransactionType="Update"> <ItemGroupData ItemGroupOID="EX" ItemGroupRepeatKey="@CONTEXT" TransactionType="Upsert"> <ItemData ItemOID="EXSTDAT" TransactionType="Context" Value="04 JUL 2025"/> <ItemData ItemOID="EXSTTIM" TransactionType="Upsert" Value="16:00"/> <ItemData ItemOID="EXMODE" TransactionType="Upsert" Value="Self Report"/> </ItemGroupData> </FormData> </StudyEventData> </SubjectData> <AuditRecords /> <Signatures /> <Annotations /> </ClinicalData> </ODM>

Technical Notes

Following are requirements and technical notes for the DAT platform (SureAdhere) to receive subjectID and arm data for the project. The data will be used in the SureAdhere system to populate a list of subject IDs and regimen names based on the trial arm.

Terminology

  • Subject ID from EDC is called the MRN (Medical Research Number) in the SureAdhere system

  • Trial arm in EDC is called Regimen name in the SureAdhere system

  • Site code in EDC is called Site Code in SureAdhere

Scope

In Scope

  1. Client to send Subject ID number per trial specifications to ensure consistency of data capture across trial 

  2. Client to send regimen associated with subject ID to ensure consistency of regimen arm randomization across trial 

  3. Dimagi to populate list of subject IDs into SureAdhere’s Patient Profile MRN field and display regimen name at top of screen on Patient’s Regimen page.

Overview of Solution

Dimagi will use a publicly accessible API that can be used by the EDC system. When a randomized subject is chosen, this will be sent to SureAdhere by EDC calling this API in real time, and the data will be usable in SureAdhere web app.

The data from EDC will be stored in the SureAdhere database as lookup values for the MRN field. And associated with the Subject ID, will be a regimen name.

Feature in SureAdhere Web app

Subject ID

SureAdhere will create a new patient with the given subject id and trial arm. A user can then visit the web app, search for the patient, and enter their state date, which will fully populate their regimen.

Arm

The name of the arm that is associated with the Subject Id, will then be automatically added as the name of the patient's Regimen. We expect that all data will be sent by EDC at Baseline visit with patient

Site Code

The site that the patient is assigned to for the trial.

Authentication scheme

The authentication scheme for the API is based on tokens. Each token is linked to a workspace (SureAdhere client) and manually shared with an integration partner.

Some characteristics of the authentication scheme:

  • Token encodes both authorization and destination of data, 

  • Authorization is associated with a SureAdhere client

  • Token has explicit permissions applied to it.

  • Token won't expire. It will be manually revoked if necessary.

  • Authentication is write-only, meaning the EDC system can only submit subject_id and arm data pairs, without being able to access any resulting information.

  • Firewall IP whitelisting

Error handling

  1. Consider if SureAdhere system is down, EDC system must continue to send until acknowledgement from SureAdhere (201 is created successfully or 409 for duplicates)

  2. Data validation:

    1. API will validate that MRN is unique for all patients for a client/workspace.

    2. A 409 will be returned if the MRN given already exists in the system.

    3. Also validates MRN format, and that the site exists, and that regimen arm is one of the expected options.

  3. Error logging and reporting: 

    1. The API will log any errors in SureAdhere that occur during processing and provide a mechanism for reporting those errors to administrators or other relevant parties.

  4. Throttling: 

    1. The API should include a throttling mechanism to prevent overload and ensure fair usage. For example, the API may limit the number of requests per second or per minute from a single IP address.

    2. Throttling is unlikely to be an issue given the relatively small number of patients per trial..

Authentication

Client token must be included in each request as a header named MRNIntegrationToken

Data

Data should be provided in JSON format and encoded as UTF-8. Example request payload:

{ "mrn": 123-123-1234, "regimen": "Group 1", "site_code": "123", }

MRN - Required. This is the SubjectID from EDC.

  1. Must be unique within the client/country. As above, a 409 response will be returned if this is a duplicate.

  2. This will be used as the patient's username and first name on the mobile app

Regimen - Required. Specific to client. See Client-Specific Elements below.

Site Code - Required, this is a 3-digit number

Endpoint

POST: /treatment/ingest/mrn_regimen

Responses:

  • 201 Success!

  • 400 Bad token or issue with MRN format or nonexistent site or regimen arm

  • 409 Subject with the same subjectID /MRN already exists

  • 500 Internal Server Error

Example cURL

curl -X POST \ https://some-sureadhere-env.com:8004/treatment/ingest/mrn_regimen\ -H 'Content-Type: application/json' \ -H 'MRNIntegrationToken: 123abc' \ -d '{ "mrn": "100-100-1000", "regimen": "Group 1", "site_code": "100", }'

Terminology

  • CRF - case report form

  • CDISC - Clinical Data Interchange Standards Consortium

  • DAS - Data Acquisition Specification

  • DAT - Digital Adherence Tech . ie SureAdhere

  • EDC- electronic data capture system. This is the main source for all the clinical trial data. In this case the EDC that we will be integrating with is called Medidata Rave

  • Rave EDC - system for clinical trial site, patient, and lab data capture and management.

  • RWS - Rave Web Services. Integrates Medidata Rave with third party systems to exchange CDISC ODM v1.3 standard clinical data or metadata synchronously and with immediate confirmation.

  • Subject ID - The patient identifier. This is what Sureadhere will save as MRN in SureAdhere database

Client-Specific Elements

The following elements are unique to each integration and will need to be agreed upon by the client and Dimagi:

  1. Rave web service URL: see File Transport and Data Transfer Assumptions above.

  2. StudyOID: this will vary depending on the environment (dev, UAT, or production). See File Transport and Data Transfer Assumptions > Variables above.

  3. FormOIDs: see Form Specifications > Medication Exposure Form above.

  4. Regimen names - These will be provided to the patient creation API. See Technical Notes > Data above.