© 2024 IQVIA - All Rights Reserved

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

Overview

This document describes the requirements and design specifications for the Verified Clinical Trials (VCT) interface with ClinSpark.

ClinSpark can be configured to work with VCT such that over-volunteering checks to occur in an automated and efficient capacity, helping to improve overall clinical trial data quality and processes. These processes happen securely and a clear audit trail is maintained within the application where applicable.

Applicability

This document applies to ClinSpark versions 1.5.0 and greater.

Requirements

The interface requires the following:

  • Verified Clinical Trials database version 1.8.46 or higher

  • ClinSpark versions 1.5.0 or higher

Scope

  1. Functional Requirements

  2. Non-functional Requirements

  3. Design Specifications

Out of Scope

  1. User Requirements Specification (URS) is not included. Foundry Health has reviewed the general requirements of the user community and used these to determine Functional and Non-Functional Requirements for this ClinSpark component.

  2. ClinSpark Infrastructure specification (documented separately)

  3. ClinSpark Architecture specification (documented separately)

  4. ClinSpark Configuration Specification (documented separately)

GxP Applicability

This interface is intended for use within the context of clinical research and clinical trial activities and as such, the user is likely to be subject to applicable GCP regulations and guidelines.

System Impact

Subject/Patient Safety

The design of the interface has low impact on subject/patient safety.

Data Integrity

Testing has occurred to confirm data integrity upon transfer from VCT to ClinSpark.

Demonstration

The following screencast demonstrates the interface on an earlier Clinspark release. While some configuration steps have changed since the screencast was recorded, the general workflow is still applicable to current release builds.

https://vimeo.com/585101459/d48c9ccf29

System Specifications

Functional Requirements

The interface is supported on all systems capable of meeting the requirements to access and use ClinSpark and Verified Clinical Trials web applications.

  • Supports the selection and configuration of appropriate volunteer identification documentation per site.

  • Supports the deployment of standard forms including a ‘VCT’ button to manage the over-volunteering workflow.

  • Supports the one-time verification of a volunteer’s status per cohort per trial.

  • Supports automated user authentication to the VCT portal.

  • Supports the secure transmittal of applicable study, protocol and volunteer details from ClinSpark to VCT.

  • Supports automated verification in VCT, and redirection back to ClinSpark.

  • Supports the update of the Over Volunteering form with the status provided by VCT, and the retrieval and retention of a PDF certificate generated by VCT.

  • Supports the review and comment on the over-volunteering status by site staff.

  • Supports a full audit trail.

Non-functional Requirements

Authorization

The interface is intended to be installed and configured by qualified users.  In most pharmaceutical and associated life-science settings, this is typically governed through an Information Systems/Technology administrator or support team.

Once installed and configured, ClinSpark application users can leverage the interface through the regular use of the ClinSpark application.

Availability

It is expected that the interface be available at time of data collection through ClinSpark.  For this to be fully achieved, the interface must be configured successfully between Verified Clinical Trials and ClinSpark application operating in a functional state.

Maintainability

The interface is reliant on the use of the Verified Clinical Trials web application. It is to be expected that Verified Clinical Trials continue to develop and support their web application, and additional capabilities brought to market. Foundry Health will maintain the interface through ongoing collaboration and support with Verified Clinical Trials, where applicable.

The end user is not able to conduct maintenance activities.

Design Specifications

The interface is established using Hypertext Transfer Protocol (HTTP) redirection.  For secure communications, ClinSpark and VCT has cryptographic assurance that messages are being sent & received by the respective parties.  Public & private keys are used to encrypt and decrypt data exchanged between ClinSpark and VCT.  The interface leverages asymmetric cryptography where each party stores and manages the other’s public key, and the public keys are then used to assert signatures that are to be sent in each message.

Assumptions/Restrictions

End users are responsible for the setup and configuration of their own Verified Clinical Trials accounts, subject, and protocol configurations. End users are encouraged to work with VCT on their own setup and configuration parameters, prior to the use of the interface in ClinSpark.

ClinSpark Configuration

General Settings

Foundry Health staff (superadmin users) must enable the VCT interface via system-wide configuration setting. The interface is typically enabled during customer onboarding phases, but otherwise, must be enabled at request via the Service Desk.

Site Configuration

Each study site utilizing the interface must be configured with VCT specific parameters.  Users with access to the Administration > Sites component can modify these settings.

Endpoint URL

The VCT endpoint URL is where users are redirected to as part of the interface workflow. Customers must set this value on site configurations depending on how they want to test and/or use the interface.

For regular use, we recommend that the production endpoint be setup in the PROD MAIN instance, and the testing endpoint setup in the PROD TEST instance.

Lower environments such as VAL, UAT, or Sandbox should use the Testing endpoints.

Per GDPR specifications, VCT has established separate URLs for EU and non-EU customers.

Partner ID

The VCT interface partner ID is required per HTTP POST specification.

This value must always be set to ‘foundry-health’.

Study Configuration

Each study can enable or disable VCT support as needed.

When this setting is disabled, VCT interactions will not be available on study over-volunteering forms.

Multi-site Studies

When a study is setup with more than one site configuration, it’s expected that all study sites have the same configured VCT endpoint URL in order for the integration to work successfully. This is true even under scenarios where only some study site may be using the VCT interface. If customers encounter this multi-site study setup scenario, they should reach out to Foundry Health support if there are any questions on how to best use the interface for that study.

Study Protocol Name

Each study in ClinSpark must have a defined protocol name to use as part of the interface.  These settings can be applied by ClinSpark users with the proper role action to modify study protocol name.

This value must be an exact match the ‘protocol number’ value configured in VCT for the interface to work properly.

Study Metadata & Over-Volunteering Form

An Over-Volunteering Base Form must be applied and appropriately configured as part of study metadata.  This base form enables the use of the Over-Volunteering specialized workflow within the use of a study. Over-volunteering form settings can be reviewed by ClinSpark users with the proper role action to modify study metadata and study library forms.

ClinSpark comes with a Base Form Library that contains a standard Over-volunteering form. By default, the ‘Subject Over-Volunteering’ base form offers sensible defaults for sites to use as a starting point supporting the VCT integration. Sites can define their own Over-Volunteering Forms if they prefer as long as the Form and Items all appropriately contain the Over-Volunteer Base Types.

As part of the default form, there are four items each with a ‘Over Volunteering’ base type associated that serve a function in the interface. Study and volunteer values are passed to VCT during the first part of the workflow, but when users are brought back to ClinSpark, there are over-volunteering details received from VCT which are attached to each of the items if the base types are associated. Here are those item base types:

  • Over Volunteering - Result

  • Over Volunteering - Report

  • Over Volunteering - Violations

  • Over Volunteering - Next Eligibility Date

Of the base types available for use on the form, two are considered non essential to the workflow and will not violate form lock conditions:

  • Over Volunteering - Violations

  • Over Volunteering - Next Eligibility Date

Other base types (Report and Eligibility Result) are required at a minimum for the Over volunteering form and the VCT interface to function properly.

Custom Volunteer Questions

A custom volunteer question, usually correlated with a type of identification value used on passports or government issued IDs, are established for the interface to work as designed. The answer to the question (on volunteer profiles) is passed through to VCT during the over-volunteering check workflow.

While it’s not required that a custom question be in place and populated on volunteer profiles for the interface to function, it’s designed to pass through as much useful volunteer data to VCT to streamline the workflow. Thus it’s strongly recommended that they be established and used.

ClinSpark users with the ‘Administrator’ role are able to setup one or more custom volunteer questions that can be used to define VCT ID types. 

A pattern we commonly see across customers is establishing these custom questions with some field description or help text identifying their use for the VCT interface. This makes it clear to administrators and users that those values are used in the exchange of volunteer data between ClinSpark and VCT.

VCT ID Types

The interface supports configurations of multiple volunteer questions pertaining to multiple identification types.  Different questions can be used on different site requirements, and applied to study configurations accordingly.

VCT ID Type values are applied for each custom question on the ‘Question Code’ field, following a specific code naming convention to ensure that a specific ID type is passed to VCT. For example, the code ‘vctid.DL’ will pass the custom question value as ‘Drivers License’ to VCT.

The accepted ID Type values in the interface are defined by VCT. However, sites determine what types of identification they plan to collect on volunteer profiles and use within their over-volunteering workflows.

Note: Not all of these values may be available in customer VCT environments. Customers are recommended to check available ID types in their VCT environment prior to study use.

  • DL = Driver’s License

  • P = Passport

  • ID = Identification Card

  • GID = State or Govt Issued ID

  • C = National ID or Cedulla

  • IC = Medicare/Medicaid or Insurance Card

  • MIL = Military ID

  • OTHER = Other

  • NOID = Subject did not bring ID

Depending on if sites want to collect and use multiple ID values on a volunteer profile for the over-volunteering workflow, the interface supports logic to determine the order of which questions are used following a ‘vctid%’ pattern. For example: vctid1.P (passport) would take precedence over vctid2.DL (driver’s license).

Volunteer Profile

Volunteer demographics (Name, DOB, Sex) and the answer to custom volunteer questions (VCT ID values) must be present on volunteer records.  These values (first three letters of First & Last name) are passed through to VCT during the workflow initiation.

These settings can be applied by ClinSpark users with the proper role action to modify volunteer profile data.

Data Exchange

Message Exchange Workflow

  1. Upon user initiating the HTTP redirection workflow, ClinSpark issues an HTTP POST to VCT per VCT’s POST specification.

    1. POST contains an HTTP callback URL back to ClinSpark.

    2. ClinSpark provides a message signature using the ClinSpark private key for the callback URL and includes the signature in the POST.

  2. VCT receives the POST and using the ClinSpark public key verifies that the signature for the URL callback matches what was passed in the POST; if invalid signature terminate workflow.

  3. Assuming signature match, move to VCT workflow where user verifies the identity of the volunteer per VCT software.

  4. Upon completion of the VCT workflow, initiate a POST back to ClinSpark using the URL callback described above.

    1. POST will include a VCT signature of the callback URL created using the VCT private key.

  5. ClinSpark will receive the VCT signature with the callback URL, and ClinSpark will verify the signature using VCT public key; if invalid signature terminate workflow.

  6. Assuming signature match, ClinSpark will update relevant Over Volunteering form with the data sent.

VCT API Post HTML Parameters

The following values are passed from ClinSpark to VCT through the API.  These values are applied based on previously mentioned site, study, and volunteer configurations.

Value

Definition

Notes

PartnerID

As defined through site configuration.

Required per HTTP POST specification.

FirstName

Volunteer First Name

The first three values will be passed to VCT.

MiddleInitial

Volunteer Middle Initial

LastName

Volunteer Last Name

The first three values will be passed to VCT.

Gender

Volunteer Sex

This value will appear in the ClinSpark UI as ‘sex’, however, it is required to be passed as ‘gender’ per VCT specification.

DOB

Volunteer Date of Birth

IDType

Identification type associated with a volunteer custom question code.

Defined in custom Volunteer Question setup.

IDType will correspond with the configured ID types presented in VCT configuration.

PartialID

Last 5 values of ID.

The last 5 values of the defined VCT ID, pulled from the volunteer question answer on the volunteer profile.

For example, if the defined ID value is ‘P123987346’, then the interface will pass ‘87346’.

This value is not required, and may not be present in all post messages depending on ID type.

ProtocolNumber

As defined through study configuration; protocol name.

This value must match the ‘protocol number’ value configured in VCT for an exact match to occur.

SubjectNumber

Defined as part of study-specific subject cohort assignment.

Assigned during volunteer activation in applicable cohort assignment.

This value can be modified by qualified ClinSpark users. Whatever value is associated with the study volunteer will be provided to VCT.

SiteUserEmail

Defined as part of ClinSpark user profile.

This represents the research ‘site staff’ email address, associated with the logged in ClinSpark user invoking the interface. This is passed along within the POST message in the workflow to help ‘speed up’ the authentication process through VCT. Email address is an optional configuration value and not required for the interface to otherwise function.

If there is no defined email address for the current ClinSpark user, then email address will not automatically populate on the VCT login screen, and users will be required to authenticate with valid VCT credentials for each over-volunteering check.

If there is a defined email address for the current ClinSpark user, and this matches the VCT username, then users will only be required to authenticate into VCT one time while their login session is active in both systems. Multiple over-volunteering checks done during this period will not require re-authentication in ClinSpark or VCT for an ideal workflow.

Transform Scripts

As part of site configuration, Foundry Health ‘superadmin’ users can define a transform script value. Transform script configurations enables a way to meet site specific requirements for the VCT interface that is otherwise not possible based on the default interface logic.

Certain usage of the transform script may require Foundry Health and VCT to collaborate on parameters passed. If necessary, VCT may need to update their interface to accept different values that are requested to be passed from ClinSpark.

Customers are encouraged to reach out and work with Foundry Health and VCT together to discuss unique requirements that would be defined through use of a transform script. Most commonly, we work with sites to establish transform script logic handling these use cases:

  • Sending Last Name Prefix (EU customers)

  • Sending the unique ClinSpark ‘Volunteer ID’ as ‘Subject Number’

  • Sending VCT the study ‘Cohort’ value from ClinSpark

Last Name Prefix

In some customer VCT configurations, there is an option for users to define ‘Last Name Prefix’ per volunteer. This value is important for properly identifying volunteers with certain Belgium last names. This value is currently not supplied by ClinSpark by default.

The standard transform script logic we use can add Last Name Prefix if a volunteer has multiple ‘tokens’ in their last name. A few examples of what will happen:

  • Van Jones → Van

  • de Vries → de

  • Smith → (nothing is passed in that request parameter)

ClinSpark User Interface

The following describes typical use of the VCT interface in ClinSpark, assuming that all previously noted configurations are in place.

Roles

The interaction of the interface is facilitated by qualified users.  These users must have access to the Study > Subjects module and permissions to initiate Over-Volunteering workflow.

Input Modes

Within the ClinSpark subject component, the user navigates to the Over Volunteering form / tab.

ClinSpark detects that the study in question has been configured to leverage VCT connectivity, and presents the user a button to begin the redirection workflow.

If the ClinSpark user was already logged into VCT in their current browser session, they will automatically be taken to the volunteer overview screen in VCT.  If not, the ClinSpark user will be directed to the VCT authentication page, and asked to log into the VCT site with applicable credentials  to continue.  

During this workflow, data passed from ClinSpark to VCT will be maintained in session.

Upon successful login using VCT credentials, VCT will enforce applicable user access controls.  Users will only see studies and locations that they have access to in VCT.

All form submission details will be auto-populated based on configured ClinSpark site, study, and volunteer parameters.

Users will verify identity of volunteer per VCT software and configuration.

Upon completion of the VCT workflow (submission), user will then be redirected back into ClinSpark.

ClinSpark will update relevant Over Volunteering form with the data provided, based on the VCT base form configuration for that study.

Users will be able to view the over-volunteer report presented by VCT.

As a side note, if multiple over-volunteering checks are done against a given subject using the same form, the results returned from the interface are all captured in the item details. If reports obtained through the interface changed, overwritten versions are retained in Item Audit Trail.

Troubleshooting

Accessing VCT environments

Much like ClinSpark, VCT has established separate testing and production environments to verify different workflows accordingly. These environments are configured in ClinSpark as the endpoint URL for the interface redirect. Credentials in these environments are managed separately by VCT, so it’s best to confirm with VCT what test environments customers are given access to and what credentials are to be used.

Forced Authentication into VCT

The interface is designed to pass the ClinSpark user email address as part of the POST message from ClinSpark to VCT. This is to help speed up the process if the ClinSpark user email address matches the VCT user account, so that users don’t have to re-authenticate into VCT each time an over-volunteering check is done.

While the interface does not require a defined e-mail address to function, having the ClinSpark user email ‘match’ the VCT username is seen as a benefit to most user workflows.

Forced Authentication into ClinSpark

If customers are being forced to re-authenticate into ClinSpark each time they are returned from VCT on over-volunteering checks, then it’s possible that the Foundry Health team may need to investigate a potential infrastructure update related to a change made in Google Chrome version 80 related to SameSite flag cookie enforcement. To address this, please reach out via service desk ticket.

  • No labels