EDC API Best Practices

Error Detection

Inner vs. Outer Response - Create Subject (1)

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Study Country] with name [Belgium] not found"
            "study_country": "Belgium"
            "site": "103",
            "subject": "103-001"            
        }
    ]
}

Inner vs. Outer Response - Create Event Groups (2)

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States", 
            "site": "101",
            "subject": "101-001",
            "eventgroup_name": "egIRT_INFO",
            "eventgroup_sequence": 1
        },
        {
            "responseStatus": "FAILURE",
            "errorMessage": "[Subject] with name [101-021] not found"
            "study_country": "United States",
            "site": "101",
            "subject": "101-021",
            "eventgroup_name": "egIRT_INFO"
        }
    ]
}

Strategy

If creating an integration into Vault EDC, what is your error detection overall strategy?

• Do you examine each response for success before moving on to a sequential / next call?
• What sort of alerting / process kicks off when there is an error?
  
• How do you avoid things falling through the cracks? (data out of synch with the EDC system)
• What about the mistake / update scenarios in the source system? What happens when your source data changes, mistake or otherwise, how do you push the data in, where an update might have a different course of action from the initial add?

Inner vs Outer Response Status

Watch the inner vs. outer success/fail statuses in API responses!

• The Vault API is designed such that most API endpoints allow multiple actions of that type in the same request.
  
• As such, the status of each entry in the request is embedded at the inner level, responseStatus.
  
• The outer responseStatus is largely an indication that 'yes, you reached the server, and it attempted an action (or actions)'.
  
• The examples to the right include:
  • Attempt to Create Subjects (Casebooks) - one - that fails
  • Attempt to Create Event Groups - two - where one succeeds, one fails

Audit 2.0 Live Capture

EDC's bulk API request processing model commits all valid records within a payload and only rolls back entries that encounter errors. This behavior is applicable when the EDC Audit 2.0 Live Capture feature is active and affects all API versions.

Endpoint Processing Behavior

Below are endpoint processing behavior definitions for bulk API processing. Understanding which processing behaviors apply to each endpoint helps ensure your retry logic handles failures correctly.

• All or Nothing (before EDC Audit 2.0 Live Capture): If the action on a single object fails, the system does not persist changes to any object.
• Batches of 20 Subjects (before EDC Audit 2.0 Live Capture): If one object in a batch fails, then the objects for all 20 subjects in that batch fail. The second batch of 20 may still succeed.
• Partial Success & Failure(with EDC Audit 2.0 Live Capture): Success always persists for all objects of a subject. Failure is always by subject, and no changes persist for that subject. For example, if only one subject out of 100 subjects fails, only that one subject’s objects do not persist. Changes to the objects for all other 99 subjects persist, and the system reports them as a success.

The table below shows which endpoints the EDC Audit 2.0 Live Capture feature affects and their processing behaviors:

Endpoint	Before	After
Update Subject	All or nothing	Partial Success and Failure
Update Event	All or nothing	Partial Success and Failure
Update Event	Omitting the visit method and externally owned method parameters (or null) did not explicitly set the Externally Owned flag to false. The system does not record the implicit action in the Audit Trail.	Omitting or passing null explicitly assigns the Externally Owned flag to false. The action appears in the Audit Trail as: "Visit Method unset as owned by another system".
Set Coding Suggestions	All or nothing	Partial Success and Failure
Create Protocol Deviation	All or nothing	Partial Success and Failure
Update Protocol Deviation	All or nothing	Partial Success and Failure
Inactivate Protocol Deviation	All or nothing	Partial Success and Failure
Submit Form	24.1 version forward All or nothing	24.1 version forward Partial Success and Failure
Reopen Submitted Forms	24.1 version forward All or nothing	24.1 version forward Partial Success and Failure
Set Event as Did Not Occur	All or nothing	Partial Success and Failure
Create Event	All or nothing	Partial Success and Failure
Open Queries by Event ID	Batches of 20 Subjects	Partial Success and Failure
Open Queries by Item ID	Batches of 20 Subjects	Partial Success and Failure
Close Queries (by ID/Batch)	Batches of 20 Subjects	Partial Success and Failure

Error Handling & Retry Guidance

When redesigning your integration's error-handling and retry logic, keep the following principles in mind:

Inspect individual payload statuses:

• Do not rely solely on the top-level HTTP response code or a global success/fail flag. A bulk request can return a successful top-level status even if individual records within that payload fail.
• Always parse the response array to check the execution status of each individual entry.

Avoid uninspected bulk retries:

• The system commits successful records to the database while it rolls back failed ones.
• Resending an uninspected entire bulk payload after a failure attempts to re-execute already-persisted data.

Implement granular retry logic:

• If you encounter a Data Not Saved error for a specific record, isolate that individual record and correct any potential data edge cases, if applicable. Your integration should only queue and retry the specific records that explicitly returned a failure status.
• This process does not apply to validation errors.

Study Design

Forms for Integration

For an inbound integration to Vault EDC:

• If possible, avoid Form designs that involve both user entered data and integrated data. Users will open the Form when the integration does not expect such, among many other timing related potential issues.
• If the data is semi-consistent from the upstream system from Vault EDC, consider:
  • A template of Forms, 100% read only in their own dedicated Event Group.
    
  • The approach can make use of Copy Event Group function in Studio to port the consistent Form designs to new Studies.
    
  • Using cross Form derived rules, the read only remote system data can be pulled/copied or referenced in the main Study design.

Repeating Events

• A repeating visit in Vault EDC increments the eventgroup_sequence values (1, 2, .. etc).
  
• Although there is an Event sequence property on Event level, current system design yields that as a 1, always.
  
• Instead, the Event Group is used for both single repeating Events (e.g. Unscheduled), or series of Events (e.g. Day 1, Day 8, Day 15.. but by Cycle)

API Account for Integrations

Security Policy

• The suggested approach for the API account performing an integration is one where the Vault Security Policy has No Password Expiration checked.
  
• In this way, a recurring integration is not at risk of having an expired password upend the important push or pull of information.

Study Access and Training

• An API user is no different from any other Study user.
  
• Typically, users must go through / pass training before their Study access is truly enabled.
  
• For an API / system user, ensure to check the Ignore LMS Status, Assume Trained attribute on the account (typically). Otherwise the API user won’t find the Study (or Studies) intended.
  
• The action is not necessary if the specific Vault is not activated to required LMS training before Study access is granted. (e.g. test / sandbox Vaults)

Sequences

• The various design levels of a Study - Event Group, Form, Item Group - can repeat, or not repeat.
  
• When they do not repeat the Create / Upsert endpoints do not require the specific indication of, say: "eventgroup_sequence": 1 in the request body.
  
• That said, consider always including these regardless, as it makes for a more consistent request/response match

Inspecting Before Doing

• Strive to inspect the existing Forms / Events before attempting an action to push data into the Study.
  
• Does the Subject even exist?
  
• Does the target area of data (Form, Event Group, etc) exist?
• If a Form is submitted, it must first be opened for edit via the Edit Submitted Forms endpoint before proceeding with the update of data using endpoints like Set Form Data or Upsert Form Data.
  
• TIP: The Combination Update Form Data endpoint is the most efficient approach (details below)

Create vs Upsert

• Various API endpoints started as only create actions (POST), where the intended location must *not exist for the action to be successful. (Exception: Set Form Data used for updating existing)
• Later releases included PUT action, which does no action when the location already exists (e.g. repeating Event Group, Form, or Item Group)
• The upsert option is a better option, since specific sequences can be indicated at the various design levels, with the result being either an add (if does not exist) or a skipped action.
  
• Update ‘2nd time in’ scenarios benefit from this approach.

Combination API for Form Data

• The EDC API's first release was #19R3*
• As releases progressed for the EDC API, endpoints were largely one to one with an action by an end user, and are used in a specific sequence. Examples:
  • Create Subjects (Casebooks)
  • Create Event Groups
  • Set Event Date
  • Create Forms (when repeating)
  • Set Form Data
  • Submit Form
• The sequence described above is common for an IxR vendor pushing data into EDC. But, it is a distinct API call to be made, each of the steps
• At API version 23R1, the Combination Update Form Data was introduced to allow for 'many in one' ability when updating Form data. Although it will not create Subjects, it will perform all of these in one request:
  • Create Forms (when repeating and not present)
  • Edit Submitted Forms (when the Form is currently in submitted state)
    
  • Create Itemgroups (when repeating and are not present yet)
  • Set Form Data
  • Submit Form

Locked / Frozen Forms

• Frozen and Locked are not automatable through the API, by design. These were/are human decisions to stop actions from happening.
• Depending on the data location, Locked and Frozen statuses differ in ability to push data into Vault EDC:

Area	Status	Add/Update Data	Add/Update Queries
Study	Locked	Disallowed	Disallowed
Site	Locked	Disallowed	Disallowed
Subject	Locked	Disallowed	Disallowed
Subject	Frozen	Disallowed	Allowed
Event	Locked	Disallowed	Disallowed
Event	Frozen	Disallowed (event date changes)	Allowed (on event date)
Form	Locked	Disallowed	Disallowed
Form	Frozen	Disallowed	Allowed

Change Reasons

• For the update of a Form data, a change_reason is only used when there is an update/change to existing values, after there has been at least one submit of the Form.
  
• Change reasons can be included for the initial set of data, but they are ignored, instead the default 'changes before submission' is used.
  
• That said, it is easier to send a change_reason with all Form updates. In this way you don’t have to track necessarily that it's the 1st or later touch of the Form data.
• Actions that require a change_reason will default to a system reason, if not provided. Providing one is preferred to better identify the action in the remote system.

Jobs

• The Vault EDC job types that allow for starting, inspecting, and retrieving output follow the Vault platform job flow. That is, a job of Completed status might still potentially have issues (no output file available).
  
• Depending on the job type (Job Summary / Types), a more detailed log style information is usually included in the output.
  
• Both the Vault job log and the content of the job’s output should be inspected.

User Administration

• For updating of users with a EDC Vault, ensure the proper usage depending on the need:
  • For deactivation of an account at the Vault level, this will remove the user from any Studies they otherwise would have had access to, in that Vault.
  • For full deactivation of an account, this will remove the user from all* Vaults (thus all Studies in those Vaults) on that domain. Later reactivation of an account in such a state is then a two-step process. (update of domain status, then update of Vault memberships)
    
  • For Study access deactivation, use the upload users endpoint (CSV or JSON), with a line indicating Study Status = Disabled, to remove access to a single Study.
    
  • Specific site / country access does not need to be removed when disabling Study access, as later a re-activation in the Study might happen, returning the user to the state they were at deactivation in the Study.
• For (CSV or JSON):
  • The structure of user information is the same as performing in the Vault EDC Users UI.
    
  • The template can change from release to release as new properties are introduced.
    
  • If some of the new properties are required, this could upend existing built integrations.
    
  • The API version does NOT refer back and use older templates.
    
  • Consult theClinical Data Help and experiment in pre release Vaults on coming releases when writing user administration integrations.
• IMPORTANT - review the Types of Users sub-section above from the Retrieve Users.