Overview

SureAdhere integrates with Medidata Rave, the electronic data capture (EDC) system used by clinical trials, so that adherence data recorded in SureAdhere lands in the study database automatically — no double data entry by site staff.

Data flows in both directions:

Quick facts

SureAdhere → EDC: dose adherence

What triggers a transfer

SureAdhere sends (or updates) an adherence log line in Rave whenever any of the following happens:

1. A provider submits a dose review in the web app. On the Adherence screen, pressing Submit for Review on a dose sends one log line per drug in that dose. Editing and re-submitting the same dose updates the same log line in Rave (no duplicates).

2. A patient submits from the mobile app. When a patient records a video, self-reports a dose, or an in-person DOT is recorded on the device, the submission is sent to Rave automatically — no provider action needed for the initial record.

What happens behind the scenes

1. SureAdhere builds a CDISC ODM v1.3 XML message for the patient, drug, and date.

2. The message is placed on an internal queue and delivered to Rave Web Services asynchronously, with automatic retries if Rave is temporarily unavailable.

3. Every call and every Rave response is logged, and errors are captured in our monitoring tools for the technical team to review. Web app users never see integration success/failure messages — delivery is asynchronous, so integration issues are handled by the SureAdhere team, not site staff.

Rules that keep the data clean

• One log line per patient, per drug, per day. Each log line is uniquely identified by the subject, the dose date, and the drug's form (for twice-daily drugs, also the morning/evening slot). Later edits update the existing line rather than creating a new one.

• Adherence log lines are never deleted. SureAdhere only inserts and updates exposure records.

• All dates and times are in the patient's local time zone (based on their site). Dates are formatted dd MMM yyyy, times HH:mm (24-hour).

• Times are only sent when they're meaningful. The recorded time is left blank when the submission was made on a different day than the dose date (a back-dated entry's wall-clock time isn't meaningful), or when 0 pills were taken.

• If a dose's video exists, the video's recording time is the source of truth for the dose time, even when the observation method comes from a self-report or in-person record from the same session.

Field reference: form layouts

Every study has its own Rave form design, so the set of fields differs per study. The three layouts currently in production are described below (anonymized as Study A, B, and C). The tables list exactly which item OIDs each layout receives and where each value comes from in SureAdhere.

Shared field values

Layout A — standard exposure form

Layout B — extended exposure form

The richest layout of the three — it also carries drug name and status, prescribed/taken dose in mg, dose comments, and last-meal details.

Layout C — per-drug exposure form (suffixed fields)

This layout uses per-drug adherence and a form design where each drug in the regimen writes its own set of fields, distinguished by a numeric suffix. One drug is dosed twice daily, so its log lines are additionally keyed by a morning/evening slot.

Example XML

Insert / update (layout A)

The EXSTDAT item uses TransactionType="Context" (it identifies which log line to touch); the data items use Upsert. Updates reuse the same structure and only need to carry the fields that changed.

SureAdhere → EDC: pill counts

For studies that use SureAdhere's pill count feature, pill count visits are also sent to a drug accountability form in Rave — one log line per drug per visit, keyed by the dispensed date.

Triggers

• Creating or editing a pill count visit in the web app sends (or updates) the log line for each drug in the visit.

• Removing a drug line from a visit sends a removal for that drug's log line. (This is the only place the integration ever deletes anything in Rave.)

Field reference

SureAdhere validates pill counts before they can be saved (e.g. pills returned plus lost/damaged can never exceed pills dispensed, and only one pill count visit is allowed per patient per date), so Rave receives internally consistent data.

EDC → SureAdhere: subject enrollment

When a subject is randomized in the study, EDC calls a SureAdhere API in real time. SureAdhere then creates the patient automatically:

• The Subject ID becomes the patient's MRN (and their username and display name in the mobile app).

• The trial arm is matched to a SureAdhere regimen template of the same name, so the patient's regimen is pre-selected. Site staff only need to open the patient and set the start date — the full regimen populates from the template.

• The site code assigns the patient to the correct site in SureAdhere.

Endpoint

POST /treatment/ingest/mrn_regimen

The request body is JSON (UTF-8):

Responses

• 201 — patient created successfully

• 400 — missing/invalid token, unrecognized regimen name, unrecognized site code, or bad MRN format

• 409 — a subject with the same MRN already exists

• 500 — internal server error

If SureAdhere is unreachable, the EDC side should keep retrying until it receives a 201 (or a 409, which means the subject already made it in).

Authentication

Each request must include the client's token in a header named MRNIntegrationToken.

• Each token is tied to one SureAdhere client (workspace) — it encodes both authorization and where the data goes.

• Tokens are write-only: the EDC system can submit enrollments but cannot read anything back.

• Tokens don't expire; they are revoked manually if needed. Firewall IP allow-listing applies.

Example

Error handling & reliability

1. Delivery is queued with automatic retries. Outbound messages are queued and retried until Rave accepts them or the configured maximum number of attempts is reached; failures are logged for the technical team. By default, up to 3 delivery attempts are made before a failure is escalated for manual review.

2. Every Rave response is checked. RWS returns IsTransactionSuccessful (1 = success, 0 = failure) plus an error code, description, and XPath location on failure. Unsuccessful transactions are logged and captured in our error monitoring, then assessed and resolved by the SureAdhere team.

3. Site staff never see integration errors. Because delivery is asynchronous, nurses and providers are not shown success/failure messages; integration issues are an internal operational concern.

4. Wrong-drug errors are treated as urgent, since they can indicate a patient on the incorrect arm/regimen.

Example successful response

Example failed response

Who to contact for failures

• Errors about a subject ID or site → contact the client

• Errors about forms/fields → contact the client

• System errors from Rave itself → Medidata support & the client

Configuration

These elements are agreed per study and per environment, and drive the integration's behavior:

Glossary

• EDC — Electronic data capture system; the source of truth for clinical trial data. All current integrations use Medidata Rave.

• RWS — Rave Web Services, Medidata's API for exchanging CDISC ODM v1.3 data with third-party systems. This integration was built against the Rave Web Services for Rave 5.6.4 User Guide.

• CDISC ODM — the XML standard used for the clinical data payloads.

• Subject ID — the trial's patient identifier; stored in SureAdhere as the MRN.

• Trial arm — the treatment group; matched to a SureAdhere regimen template by name.

• Log line — a repeating row on a Rave form; each patient-drug-day of adherence data is one log line.

• Exposure — Rave's term for medication-taken data (the daily adherence records).

• DOT / VDOT — (Video) Directly Observed Therapy.