FDA MyStudies: Technical Setup Document

FDA MyStudies Help
This topic is under construction. The GitHub source repository has moved and some links in this documentation have not been updated to point to the new locations.

This document covers the technical setup for the components that make up the FDA MyStudies Mobile Application System:

  • the Registration Server where participants sign up and create an account (UserReg-WS)
  • the Mobile Client App into which participants enter data (Android or iOS)
  • the Response Server which handles and stores the responses sent by the Mobile App (Response)
  • the Web Configuration Portal where administrators design research questionnaires (WCP and WCP-WS)
The GitHub repository for this open source project is here:

Sections

1 Introduction

This document provides deployment instructions for the FDA MyStudies platform open-source code present in the FDA-MyStudies GitHub repository. It serves as a deployment guide for technical teams and explains how the different components of the platform can be set up and used.

2 High-Level Technical Architecture

Web Configuration Portal (WCP)

The Web Configuration Portal is a web-based application that provides mechanisms to create and manage content for studies that can be made available to patients/participants via the mobile apps. It also offers corresponding "Study Metadata" webservices to the mobile apps, and to the Response server that holds the data or "responses" provided by participants due to their participation in the mobile-app based study.

The WCP application is built on Java.

The WCP allows you to:

  • Manage WCP users (also referred to as Admins, WCP ‘users’ would typically be researchers, clinicians, or study administrators involved in carrying out a study)
  • Manage app-level notifications
  • Create new studies or view/edit existing ones
  • Set up:
    • Study information and settings
    • Eligibility and informed consent modules
    • Study activities (surveys or questionnaires, and active tasks)
      • This includes setting up activity content and schedules
    • Study resources for each study
  • Send out study-specific push notifications
  • Take actions with a study such as launch study, publish updates, deactivate, etc.
Push Notifications:

Notification content created in the WCP is sent over to the User Registration Server, whose web services are utilized for the same. The User Registration server then actually sends out the notification to mobile app users, who are the intended audience for the notification.

User Registration Server

(Here ‘User’ refers to the mobile app user or study participant)

The User Registration server is built on the LabKey framework. It leverages LabKey’s User and Registration modules to provide registration services to mobile app users. It helps manage the mobile app user’s app activity and maintains the user’s app usage and study participation metadata. This server, however, does not contain any actual study ‘Response’ data (Response data is saved in the Response server against an anonymized Participant ID).

The User Registration server is thus primarily used for the following:

  • User registration (handling app sign up and sign-in related flows)
  • User profile and app-level preferences
  • User’s app usage and study-specific participation metadata (study participation status, activity completion status, etc.)
  • Firing push notifications to the mobile app users

Mobile Applications

  • FDA MyStudies comprises iOS and Android mobile apps intended for study participants to use. These apps help capture study data from participants via surveys and active tasks, after taking them through a process of testing their eligibility to participate in the study, and providing electronic informed consent.
  • The iOS app leverages Apple’s ResearchKit framework and the Android app leverages ResearchStack to present studies for users to enroll and take part in.

Response Server

The Response server is built by LabKey. It is the data store for the responses captured from mobile app users. It also provides access to this data to authorized members of the research team, for analysis purposes.

The Response Server thus primarily facilitates the following:

  • Participant enrollment into a study
  • Response data storage
  • Access to the Response data for analysis

3 WCP and Webservices Setup Instructions

3.1 Installation Required

Prior to installation, the following setup is required:

3.1.1 Java 8: The link below gives instructions for installing the JDK and JRE on Oracle Solaris, Windows, Linux, and OS X computers.

3.1.2 Tomcat 8: The link below will help you download and install Apache Tomcat and use many of the Apache Tomcat features 3.1.3 MySQL 5.6 or 5.7: The link below explains how to install MySQL or upgrade an existing MySQL version to a newer version. 3.1.4 Maven: The link below will assist you in installing Maven 3.1.5 Git Repository: Source code for WCP application and Web Services is available at:

3.2 Configuration

3.2.1 Initial Configuration:

HPHC_My_Studies_DB_Create_Script.sql: This script file should be executed in MySQL. It is found inside the sqlscript folder at this path:

hphcAuditLogs: This folder should be created inside the server and the path should be configured inside application.properties for fda.logFilePath parameter.
  • Example: fda.logFilePath=/usr/local/hphcAuditLogs/
3.2.2 Properties Files

The template_application.properties file should be downloaded from the WCP folder of the GitHub MyStudies repository and renamed to application.properties and stored in the system/server. Make necessary changes in the file based on your application configuration. The file path is given below:

Changes in Tomcat Configuration File:

Below are the changes required to the Tomcat context.xml file which can be found at:

  • <tomcat installed path>/tomcat/conf/
Add these parameters in the context.xml file inside <context> tag.
<Parameter name="property_file_location_prop" value="/usr/local/" override="1"/>
<Parameter name="property_file_name" value="application" override="1"/>
<Parameter name="property_file_location_config" value="file://usr/local/application.properties" override="1"/>
<Parameter name="property_file_location_path" value="/usr/local/application.properties" override="1"/>

messageResource.properties: This file for web application is available at /src/main/resources folder inside the project directory. Make necessary changes in the file based on your application configuration.

3.2.3 Bundle Id and App Token Settings

authorizationResource.properties file for web services application can be found at /studyMetaData/src/main/resources folder inside project directory. These are the changes required:

{Unique Identifier}=android.apptoken	#Unique Android dentifier.
{android bundleid}=android.bundleid
{Unique Identifier}=ios.apptoken #Unique iOS identifier.
{iOS bundleid}=ios.bundleid
{Unique Identifier}=labkey.apptoken #unique LabKey response server identifier.
{LabKey Unique String}=labkey.bundleid

bundleID and AppToken are the security parameters used for communication between WCP-WS and other applications.

  • bundleID: the unique identifier for the authentication of client applications (e.g., Android, iOS, LabKey response server).
  • AppToken: You have to create three AppTokens, one for each application, to communicate with WCP-WS. You need to create an AppToken, one each for Android, iOS, and the Response server, the three applications that communicate with the WCP-WS. Once the AppToken is created, all the communications will take place through this unique token. If a request originates from any other application, the authentication will fail.
  • Mobile web services communication should take place through the bundleID and AppToken.
3.2.4 Set super admin email id

HPHC_My_Studies_DB_Create_Script.sql file can be found at https://github.com/FDA-MyStudies/WCP/tree/develop/sqlscript. Update the "your email address" text with the email id that you want to keep as super admin for WCP application in HPHC_My_Studies_DB_Create_Script.sql file.

3.3 Build

To build the application(s), run the command given below from the project root folder(s):

mvn clean install

3.4 Deployment

Once the build is successful, the .war files will be generated in the target folder. To deploy, copy these .war files and paste them inside the ‘webapps’ folder of the Tomcat installation path and restart the server.

If your StudyMetaData project is created with StudyMetaData-0.0.1-SNAPSHOT.war name, change the file name to StudyMetaData.war before deploying to the Tomcat webapps.

3.5 Test the application(s)

After deploying the builds, hit the following URLs to verify the application status:

Web application:

http://localhost:8080/fdahpStudyDesigner	# NOTE: In place of localhost:8080, use your configuration.
This will redirect you to the login page. Use forgot password to change the password for the email id you have provided in step 3.2.4 and use the new password to login into the application.

Web services:

http://localhost:8080/StudyMetaData/ping	# NOTE: In place of localhost:8080, use your configuration.

This will display “It Works!”

4 User Registration Web Services

4.1 Getting Started

The User Registration web services are built on the LabKey environment. To start this project, you need to set up a LabKey development machine. The link given below will guide you through this process:

Once the LabKey development environment is set up, clone the GitHub repositories such as 'UserReg-WS' into the /server/modules folder. (If checked out into a different folder/name please update path in settings.gradle, build.gradle of distributions folder and commands accordingly.)

Switch to the primary branch and then do a git pull.

4.2 Build

4.2.1 User Registration Web Services

In your settings.gradle file, find the commented out lines with this text:

// The line below is an example of how to include a single module
//include ":server:modules:workflow"
Underneath this line, add these two lines:
include ":server:modules:UserReg-WS"
include ":server:modules:UserReg-WS:distributions:Registration"

To generate a local build, use the below command:

gradlew cleanBuild deployApp

Once the build is successful, click the icon in your IDE.

Use this link to ping the local server after it is started, to verify that the web services are running locally:

http://localhost:8080/labkey/fdahpUserRegWS/ping.api

To open the LabKey home page of the (local) User Registration server, use:

To generate a production build, use the following commands:

gradlew deployApp -PdeployMode=prod
gradlew -PdeployMode=prod :server:modules:UserReg-WS:distributions:Registration:distribution

Once the build is completed, you will find the distribution file at the path given below, where <LABKEY_HOME> is the root folder where you have cloned the LabKey code:

  • <LABKEY_HOME>/dist/Registration
To deploy the UserReg-WS module to the production server, please refer to:

4.3 Multiple App support

The MyStudies platform supports multiple apps with a single deployment. The User-Reg server follows a specific project and folder structure (Org project, App folder, and Study folder) to handle all the data accordingly:

  • A Project named for the Organization (OrgID) with
  • A Folder inside it for each App (AppID) plus
  • One or more Study folder(s) within these (StudyID).
The data is sent by the mobile application to the specific Study folder that matches this three level naming structure.

4.3.1 Folder Creation:

The following steps describe the folder creation process for the user registration server. The folder hierarchy to be followed is: Org folder -> App folder -> Study folder.

The App folder will hold all the app-level data, and the Study folder will store all the study-level data. The Org folder helps identify the organization to which the apps and inherent studies belong. Users can be assigned permissions to the various hierarchies of folders, as required, using the LabKey user management features.

Note: For the User-reg server to handle App & Study level data, the following steps need to be followed before publishing the study:
  • Folder creation: If a study with a new OrgId and AppId is created in WCP server, then the Org, App, and Study Folders should be created on the User Registration server, with OrgId, AppId, and StudyId as the names respectively.
    • If a study with an already existing AppId (and thus OrgId) is created in WCP server, then only the Study Folder needs to be created within it.
    • Note that for a production/live environment (as well as a staging environment) access to data can be restricted as required by controlling access to the server and user permissions on the LabKey folders.
    • Also note that there is no change required in the folder creation process on the Response Server.
  • Firing App Properties API: More about this is given in the last part of this document.

Following are the steps to create the folders in the User Registration server and steps to view the data on the server:

Step 1: Create a project for the organization if one does not already exist. The name must be the same as the value of OrgID used on the WCP. Choose folder type "Collaboration" and accept other defaults.

Step 2: Select (Admin) > Folder > Management, click the Folder Type tab and make sure that the FdahpUserRegWS module is checked.

Step 3: Still in the folder management section, click the Module Properties tab and add the OrgID as used on the WCP in the value of StudyId for the new project you just created, also named with the "OrgID" used on the WCP. Save this change.

Step 4: In the project, create a subfolder to hold all the data for this app - each organization may have one or more AppIDs in use on the WCP. For each one, you need a folder named the same as the "AppID". Use the "Collaboration" type and accept other defaults.

Step 5: Select (Admin) > Folder > Management, click the Folder Type tab and make sure that the FdahpUserRegWS module is checked. Click the Module Properties tab and add the AppID of the application in the value of StudyId for the new folder you just created, also named AppID. Save this change.

Step 6: Next, within the AppID folder, create a subfolder to hold all the study level data. The name of this folder must be the same as the "StudyID" used on the WCP. Use the "Collaboration" type and accept other defaults.

Step 7: In the new folder, select (Admin) > Folder > Management, click the Folder Type tab and make sure that the FdahpUserRegWS module is checked. On the Module Properties tab, enter the StudyID value used on the WCP as the value of StudyId for the new folder also named the same StudyID value.

Step 8: To view the data, create external schemas. Select > Developer Links > Schema Browser. Click Schema Administration, then New External Schema.

Step 9: Enable the below tables in the schema to view app level data (i.e. at the AppID level):

  • apppropertiesdetails
  • authinfo
  • loginattempts
  • passwordhistory
  • userappdetails
  • userdetails

Step 10: Enable the below tables in the schema to view study level data (i.e. in the StudyID subfolder):

  • participantactivities
  • participantstudies
  • studyconsent

Step 11: Add a Query web part and choose the schema to view the data. Add a Files web part to view the associated files. Do this at both the project level (App level data) and subfolder level (Study level data). The two levels are shown below:

4.3.2 App Properties API (will be automated in the future)

If a new app is created in the WCP server, i.e., if a new App ID is introduced, then the following API should be called manually before publishing the study and after creating the Org, App, and Study level folders in the User Reg server. This API helps to populate the user registration server with app-specific data and files required to operate the mobile apps. Please ensure the API is loaded with values as applicable to your app.

Note that the platform will be enhanced in the future to provide an interface in the WCP for managing such app-level properties and content and automating the transfer of these values to the user registration server with the API. That is one of the objectives of the MAMO feature.

The API’s generic template is provided below for reference:

POST: {Base url of user-Reg-WS}/fdahpUserRegWS/appPropertiesUpdate.api Content-Type: application/json { "appId": "", // app ID

"orgId":"", // org ID

"androidBundleId":"", // Android app package name

"androidServerKey":"", // Android push notification (fcm) server key

"iosBundleId":"", // iOS app bundle id

"iosCertificate":"", // base64 format text of iOS push notification certificate

"iosCertificatePassword":"", // password of the certificate

"email":"", // email from which mail needs to be sent

"emailPassword":"", // password of the mail id (Not required for production environment)

"registerEmailSubject":"", // email subject for signup mail

"registerEmailBody":"<html><body><div style='margin:20px; padding:10px; font-family: sans-serif; font-size: 14px;'><span>Hi, </span><br/><br/><span>Thank you for registering with us! We look forward to having you on board and actively taking part in<br/>research studies conducted by xxxxxx. </span><br/><br/><span>Your sign-up process is almost complete. Please use the verification code provided below to<br/>complete the Verification step in the mobile app. </span><br/><br/><span><strong>Verification Code:</strong> <<< TOKEN HERE >>> </span><br/><br/><span>This code can be used only once and is valid for a period of 48 hours only. </span><br/><br/><span>Please note that registration (or sign up) for the app is requested only to provide you with a <br/>seamless experience of using the app. Your registration information does not become part of <br/>the data collected for any study housed in the app. Each study has its own consent process <br/> and no data for any study will be collected unless and until you provide an informed consent<br/> prior to joining the study </span><br/><br/><span>For any questions or assistance, please write to <a>Contact Email Address</a> </span><br/><br/><span style='font-size:15px;'>Thanks,</span><br/><span>The xxxxxx Team</span><br/><span>----------------------------------------------------</span><br/><span style='font-size:10px;'>PS - This is an auto-generated email. Please do not reply. </span></div></body></html>", // email subject for signup mail, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

"forgotPassEmailSubject":"", // email subject for 'Password Help' email

"forgotPassEmailBody":"<html><body><div style='margin:20px;padding:10px;font-family: sans-serif; font-size: 14px;'><span>Hi,</span><br/><br/><span>Thank you for reaching out for password help.</span><br/><br/><span>Here is a temporary password which you can use to sign in to the (app name) App.<br/> You will be required to set up a new password after signing in.</span><br/><br/><span><strong>Temporary Password:</strong> <<< TOKEN HERE >>> </span><br/><br/><span>Please note that this temporary password can be used only once and is valid for a period of 48 hours only.</span><br/><br/><span>For any questions or assistance, please write to <a> Contact Email Address </a> </span><br/><br/><span style='font-size:15px;'>Thanks,</span><br/><span>The xxxxxx Team</span><br/><span>----------------------------------------------------</span><br/><span style='font-size:10px;'>PS - This is an auto-generated email. Please do not reply. If you did not request password help, please visit the app and change your password as a precautionary measure. </span></div></body></html>" // email Body for Password Help email, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

"feedbackEmail":"", // email to which 'feedback' mail needs to be sent

"contactUsEmail":"", // email to which 'contact us' mail needs to be sent

"appName":"", // name of the application

"methodHandler":false

}

Important Notes:
  • The body of the emails need to be in HTML format and the <<< TOKEN HERE >>> part represents the identifier for the verification code or temporary password dynamically generated for that email.
  • All fields in the API are mandatory.

After setting up the folder structure and calling the API as described above, publish the study from the WCP application, and start using the mobile app.

5 iOS Setup

5.1 Introduction

This section explains how to setup the FDA MyStudies iOS app and install and run it on an iPhone.

5.2 Requirements

5.2.1 IDE

Xcode 11 and above can be used to run application. You can install Xcode from the Mac App Store.

5.2.2 iOS

The application is supported only on iOS 13 and above versions.

5.3 Xcode Setup

After successful installation of xcode follow below steps:

a. Setup Developer Credentials

  • Open Xcode and go to Preferences.
  • Click on Accounts on top menu.
  • Click on the icon and Choose Apple ID.
  • Sign In with Apple developer account.
b. Change Bundle Identifier
  • Enter a new bundle identifier for your application.
  • Choose Code Signing to “Automatically manage signing” and Xcode will take care of registering the bundle identifier.
c. Enable for Push Notification Note: To learn more about Xcode and above setup, refer to Apple's official guide to Xcode Setup

5.4 How to open Project in Xcode

  • Download the project from GitHub or clone.
  • To open a project in Xcode go to the project location on your Mac Machine and look for the file named “HPHC.xcworkspace” and double-tap on it.

5.5 How to change Server URLs

Note: Once your registration is complete and the WCP & Response Server are set up, please follow the below steps.

5.5.1 Set up study and API configuration After the application is set up on the WCP server and after creating the study (REFER SECTION: 8.1), you will need to add the following settings in "Default.xcconfig", shown in the image below.

  1. WCP_URL
  2. RESPONSE_URL
  3. REGISTRATION_URL
  4. APPLICATION_ID
  5. ORGANIZATION_ID
  6. STANDALONE_STUDY_ID
  7. USERNAME_KEY: This is ios.bundleid (Refer to section: 3.2.3)
  8. PASSWORD_VALUE: This is ios.apptoken (Refer to section: 3.2.3)

5.6 How to Build and Run

The application can be run on an iPhone Simulator OR iPhone Device.

5.6.1 Run on Simulator

To run on the simulator, select a simulator from the simulator listing and click on the Play button.

5.6.2 Run on Device

To build and run the application on your iPhone device, connect your phone with a power cable to the Mac machine.

The iPhone name will be listed under Device. Select 'iPhone' and click on the Play button.

5.7 How to set up a Standalone Study App

Note: You need to create the standalone study on the WCP server first & get the studyID. Once the standalone study setup is finished please follow the below steps (REFER SECTION: 8.1)

1. Open the project workspace in Xcode.

2. Replace the StandaloneStudyId value with studyID in Info.plist

3. Make sure OrganizationID & ApplicationID is same in the Info.plist from the same WCP server.

4. Go to main target build settings & look for “standalone”

5. Under User-Defined, set the “IS_STANDALONE_STUDY” value to true for both debug and release.

6. Build and run the project.

5.8 Apply Your Branding

  • AppIcon & Launch Image
    • Replace your AppIcon and launch Images into Assets.xcassets under the AppIcon & LaunchImage respectively.
  • Change Display Information
    • There are some informational content items that can be directly changed at file level and are not required to be changed at the code level.
    • Look for file Branding.plist and change information appropriate to your application.
  • App Introduction Changes
    • App Introduction screen can also be changed at file level.
    • Look for GatewayOverview.plist file and change information appropriate to your application.

6 Android Setup

6.1 Introduction

This section explains how to setup the FDA MyStudies Android app and install and run it on an Android device.

6.2 Requirements

6.2.1 IDE Environment Setup

Download Android Studio from the following link and set up the environment.

6.2.2 Android OS Support
  • The application can be run on Android OS right from the Nougat version and up to Android 10.

6.3 Steps to pull code from GitHub

  • a. After setting up the IDE environment do integrate the GIT version control system.
  • b. Copy the app’s source code link from the GitHub repo.
  • c. Open Android Studio and go to File > New > Project from version control > Git. This will open a window and then copy the link to the Git Repository URL field.
  • d. Set the path to which the project has to be cloned in the Parent Directory field.
  • e. Give Directory name in Directory Name field.
  • f. Click on the Clone button which will download the source code, and the user can open the 'MyStudies' source code in the new window.

6.4 Initial Setup

6.4.1 App Setup

Create apikey.properties file in the home directory of the project and add the following details (for the android.bundleid, refer to section: 3.2.3):

apikey="android.bundleid:android.apptoken" 
app_id_key="applicationId"
app_id_value="xxxx"
org_id_key="orgId"
org_id_value="xxxx"
study_id="xxxx"
base_url_wcp_server= "https://wcp_base_url/StudyMetaData/"
base_url_registration_server="https://registration_sever_base_url/fdahpUserRegWS/"
base_url_response_server="https://response_server_base_url/"

6.4.2 Push Notification Setup

  • a. Go to your Firebase project.
  • b. Set up push notifications for Android.
  • c. Download the JSON file and replace the google-services.json file in the app/src/fda directory.
  • d. Send the Server Key (from Cloud Messaging section of Firebase) to App Properties API.(REFER SECTION 4.3.2)
6.4.3 Update the Map key (com.google.android.maps.v2.API_KEY) in Android Manifest file in app/src/main directory and app/src/fda directory

6.6 Apply Your Branding

  • AppIcon & Launch Screen: To update these, the following changes have to make in src/fda directory:
    • a) Replace ic_launcher.png in mipmap-hdpi, mipmap-mdpi, mipmap-xhdpi, mipmap-xxhdpi, mipmap-xxxhdpi directories with respective resolutions for App icon updates.
    • b) Replace fda_logo1.png, fda_logo2.png in drawable-560dpi, drawable-xhdpi, drawable-xxhdpi, drawable-xxxhdpi directories with respective resolutions for updating launch screen logos and update the activity_splash.xml file in the layout directory for launch screen UI.
  • Change Display Information & App Introduction Changes: There are some informational content items in the app that can be directly changed at file level, and not required to be changed at the code level. Look for file strings.xml in the values directory and change information appropriate to your application including App Introduction screen text.

6.5 Steps to Install Android app

The app can be installed to the device or emulator from Android Studio by clicking on the Run button in the Menu bar, which will open a window asking you to choose between emulator and device.

6.6 Creating the Android app build

  • a. First increment the versionName and versionCode in the build.gradle file in App Directory from Project Explorer.
  • b. Click on Build Variants in Android Studio and click on the area where debug text is displayed.
  • c. Select the release option from the list.
  • d. Click on Build from the menu bar and select Generate Signed APK.
  • e. Download the keystore.jks from the following link <Keystore Location>
  • f. In the new window opened enter the details about keystore:
    • Key store path: Browse to the path of the downloaded keystore by clicking the Choose existing... button.
    • Enter Key store password.
    • Key alias: fda
    • Enter Key password.
    • Click the Next button.
  • g. In the new window enter the details:
    • Enter the APK Destination Folder to which the build will be generated.
    • Select release as Build Type
    • Select the check box V1(Jar Signature)
    • Click Finish, which will generate the Android build.

7 Response Server Setup

Please refer to LabKey documentation on the Response Server setup in this topic:

8 Create Your Study on WCP and Run

Once you have set up all the different components and applications of the MyStudies solution, you are ready to create your study via the WCP, publish it to the mobile app, and run through the user flow of a study participant who would use the mobile app to participate in the study. Given below is a high-level description of the process you would need to employ for the same.

8.1 Create the study in WCP

Sign in to the WCP, and click on Studies > Create New Study. Follow the series of steps shown below to set up content for your study.

(The WCP user is referred to as ‘Admin’ in the sections below)

8.1.1 Basic information

  • Here, the Admin should enter a Study ID (which should be unique for each study), Study name, Study category, research and data partners, tentative duration, study tagline, study description, etc.
  • Each study that you create will have a Study ID and be associated with an App ID, as well as an Org ID. The App ID and Org ID indicate the mobile app and organization with which the study is associated.
    • The App ID for a study must be configured in the basic information screen (read more about app types and app IDs below).
    • The Org ID field is not supported for configuration via the UI as of now but hardcoded in the backend and mobile apps with a default value. These Org IDs can be updated as required if the studies running on the deployment are associated with different organizations and if you wish to identify studies by the organization at the database level or have other use cases to address based on the Org ID.
  • The platform supports two mobile app models: Gateway and Standalone.
    • Gateway apps are those which house multiple studies, whereas standalone apps are those that have a single study each.
    • Multiple mobile apps of each type (gateway and standalone) can be supported with a single deployment of the platform.
    • Each app created off the platform must have a unique App ID.
  • The Basic Information screen will allow you to specify if your study should belong to a gateway or standalone app.
    • A study thumbnail image should be uploaded for a study being added to a Gateway app; this appears in the Gateway app’s study list screen.
  • You would need to provide an ‘App ID’ for the study in the corresponding field on the Basic Information screen. This identifies the specific app that the study must appear in.
    • If you want to add a study to an existing Gateway app, provide the app's App ID here. If adding the study to a new app (Gateway or Standalone), add a new unique App ID into this field.
    • Note that standalone studies would always need a new unique App ID to be created. Refer to image below:

8.1.2 Settings & Admins

  • Here, the Admin can configure certain settings for the study and manage users or “Admins" who can view or edit the study.
  • Some of the key study settings here are mobile platform(s) supported for the study, enrollment being open or closed for the study, allowing enrollment date to be used as an Anchor Date for scheduling study activities and resources, etc.

8.1.3 Overview

  • In Overview, the Admin can add multiple pages for a study, reflected in the mobile app under Study Overview screens.
  • Each page contains a Title, Description, and Image. Admin can also add a study video URL on the first page of the Study Overview.

8.1.4 Eligibility

  • In the Eligibility section, the Admin can choose and set up content for the desired method to be used for determining participant eligibility:
  • Token Validation Only
  • Token Validation and Eligibility Test
  • Eligibility Test Only.
Once the study is launched, then the Admin will not be able to edit the Eligibility type.

8.1.5 Consent Section

  • In Consent Sections, the Admin can add ResearchKit / ResearchStack based (pre-formatted mobile UI) or custom consent section types and fill in the content accordingly.
  • Each consent section contains a title, display title, summary, and elaborated content.
  • The admin can also choose to display the consent section as a visual step in the mobile app.
  • The admin can allow participants to take a comprehension test of the consent material and set up comprehension test questions and a minimum score to pass the test.
  • In the Review Consent screen, the Admin can either choose from the auto-generated consent document (Concatenated Consent Sections) or create a Custom consent document to be used in the app.
  • Consent by a LAR (Legally Authorized Representative): This will add functionality to the study's consent module in the mobile app to allow the app user to provide consent on behalf of the participant as a LAR. The study will continue to support direct consent even if this setting is enabled. The app user can choose one of two consent methods as applicable to them and will be guided through the rest of the app's consent process accordingly.
  • Additional signature lines for study staff: This feature will enable additional signature lines in the finalized PDF document to accommodate required study staff signatures.

8.1.6 Participant Properties

  • The admin can create external properties that can define Anchor dates for activities, tasks, or resources.
  • This is not a mandatory step to create the study.

8.1.7 Study Activities – Questionnaires

  • The admin can create questionnaires with a combination of Instruction Steps, Question Steps, and Form Steps.
  • Each question step comprises Step-level, Question-level, and Response-level attributes that offer several provisions to design the kind of questionnaire and study experience you need.
  • A Form Step is essentially a set of Question Steps in the mobile app; all questions that belong to a form appear on a single screen.
  • Many scheduling options are provided that the admin can choose from to determine the schedule of the survey in the mobile app.

8.1.8 Study Activity – Active Tasks

  • The Admin can choose to add active tasks to the study from the options available in the WCP.
  • Once an active task is selected, the admin needs to fill in values for its configurable attributes.
  • A number of scheduling options are provided that the admin can choose from to determine the active task schedule in the mobile app.

8.1.9 Resources

  • The Admin can add resources’ content either using a text editor or by uploading a PDF. These resources will be reflected in Mobile app in the Resources section of the study.
  • Resources can be made available in the app for specific time periods using the Period of Visibility settings. There is also a provision to notify mobile users when a new resource is available.

8.1.10 Notifications

  • Admins can create and send study-specific push notifications to participants
  • Notifications can either be sent out immediately or scheduled for a date and time.

8.1.11 Actions

  • In this section, the admin sees the various actions that can be taken with a study.
  • Admins can choose to publish the study as test mode or live mode. Each mode can be published as an upcoming one, launch the study to enroll participants, collect data, publish updates ongoing to existing studies, or Pause/Resume or deactivate them.

8.2 App and Study Folder in User-Reg Server

Since the MyStudies application supports multiple apps, the User-Reg Server should hold its data accordingly. So before publishing the study from WCP Server, Org Folder, App folder, and Study Folder need to be created in User-Reg Server (REFER SECTION 4.3).

Note: For each app created, users should do a fresh signup since user data is not shared among different applications.

8.3 Create Study on Response Server, and Generate Enrollment Tokens

  • Once your study has been set up on the WCP, and the Response Server setup is ready too, login to the LabKey admin portal
  • Create your Project.
  • Create your Study space/folder using the same Study ID you used to create the Study in the WCP.
  • Once this is done, enrollment tokens can be created for the Study (if Token Validation method is being used for ascertaining eligibility), these are distributed to users of the mobile app to participate in the study.
(Please refer to LabKey documentation for more details on steps to set up a study on the Response Server.)

8.4 Study Participation using the mobile application

  • Launch the mobile app installed on your phone
  • Sign up with a valid email ID and password and follow the instructions to set up your user account.
    • (Note that mobile app users would need to sign up separately for each of the apps created using the platform.)
  • After successful sign up, if using a gateway type of app, there would be list of studies to choose from (all published to the app using the WCP).
  • Pick a study for which you have the enrollment token and proceed, OR, choose a study that does not require a token to be used but has an eligibility questionnaire/test instead.
  • Participants can search using the enrollment token to find the study that he/she wants to enroll in.
  • To join the selected study, complete the Enrollment Token Validation/ Eligibility steps and the Informed Consent process. This involves reviewing consent sections, taking a comprehension test (if available for the study), completing the legally authorized representative section (if enabled for the study), and then doing a final review of and agreeing to the full Consent Document. The process ends with an e-signature after which the app generates a signed consent document PDF.
  • Once in the study, you can participate in activities listed out as per the schedule in which they are to be taken.
  • You can also view various statistics and trends on the study dashboard and access study resources.
  • There are also other miscellaneous features at the app level such as a ‘Notifications’ section, Account/Preferences section, and provisions for participants to provide feedback or contact a designated email inbox for inquiries.

Related Topics