Table of Contents

guest
2020-11-30
FDA MyStudies Overview
FDA MyStudies: Technical Setup Document
Response Server: Set Up
   Enrollment Tokens
User Registration Server: Set Up
Mobile Client API
Survey Designs and Responses
Data Sharing Consent
Testing the Response Server
Response Processing
Querying the Response Server
External Documentation Resources

FDA MyStudies Overview


The FDA MyStudies platform provides all of the components necessary to support data collection from mobile applications and the storage of collected data in a compliant data environment. This help section contains documentation and links to background information to help you set up and use MyStudies. The topics below are intended for developers and administrators who wish to set up a MyStudies instance for collecting data from patients. Set up requires the deployment and configuration of the following components:
  • the Registration Server where participants sign up and create an account
  • the Mobile Client App into which participants enter data
  • the Response Server which handles and stores the responses sent by the Mobile App
  • the Web Configuration Portal, or "Study Designer", where administrators design research questionnaires
There is a separate documentation site for the FDA COVID-19 MyStudies app, with information about using that application for the electronic consent portion of the overall MyStudies functionality.

Technical Setup for FDA MyStudies

An earlier version of this topic is available as a PDF on GitHub.

Response Server Topics

Registration Server Topics

Web Configuration Portal Topics

Topics for Mobile App Developers

Related Topics




FDA MyStudies: Technical Setup Document


This topic is under construction.

This document covers the technical setup for the WCP Application, User Registration Server, iOS App, Android App, and Web Resources.

An earlier version of this topic is available as a PDF on GitHub.

1 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 provides corresponding ‘metadata’ webservices to the mobile apps, and to the Response server that holds the data or ‘responses’ provided by participants as a result of their participation in the mobile-app based study.

The WCP application is built on Java.

The WCP allows you to

  • Create New Studies or View/Edit/Manage existing ones.
  • For each study,
    • Set up Study Information and Settings
    • Set up Eligibility and Informed Consent Modules
    • Set up Study Activities (Surveys or Questionnaires, and Active Tasks)
    • This includes setting up activity content and schedule
    • Set up Study Resources
    • Send out Study-specific Push Notifications
    • Take actions with a Study such as Launch Study, Publish Updates, Deactivate etc.
  • Manage Users of the WCP as a Superadmin User or User who has the required permissions (also referred to as Admins, WCP ‘Users’ would typically belong to the research team carrying out the study and setting up content for it)
  • Manage App-level Notifications
Push Notifications: Notification content that is 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 that are the intended audience for the notification.

User Registration Server

(‘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 for 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 Mobile App Users

Mobile Applications

  • FDA MyStudies comprises of iOS and Android mobile apps intended for study participants to use. These apps helps capture study data from participants via surveys and active tasks, after taking them through a process of ascertaining 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

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

2 WCP and Webservices Setup Instructions

2.1 Prerequisites

Prior to installation, the following setup is required:

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

2.1.2 Tomcat 8: The link below will assist you in downloading and installing Apache Tomcat, and using many of the Apache Tomcat features. 2.1.3 MySQL 5.6: The link below describes how to obtain and install MySQL or to upgrade an existing version of MySQL to a newer version. 2.1.4 Maven: The link below will assist you in installing Maven 2.1.5 Git Repository: Source code for WCP application and Web Services is available at:

2.2 Configuration

2.2.1 Initial Configuration:

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

hphcAuditLogs folder should be created inside the server and the path should be configured inside application.properties for fda.logFilePath parameter. Ex: fda.logFilePath=/usr/local/hphcAuditLogs/

2.2.2 Properties Files

application.properties file should be downloaded from the root folder of the GitHub MyStudies repository and stored in the system/server. The file path is given below:

The following configurations within the file need to be changed:
OriginalChanges to make
smtp.portvalue=25#Should be changed to actual SMTP port
smtp.hostname=127.0.0.1#Should be changed to actual SMTP IP
fda.imgUploadPath=<Tomcat installed path>/webapps/fdaResources/#<Tomcat installed path> will be changed to actual path
acceptLinkMail =http://localhost:8080/fdahpStudyDesigner/createPassword.do?securityToken=#localhost:8080 will be changed to host/domain name
login.url=http://localhost:8080/fdahpStudyDesigner/login.do#localhost:8080 will be changed to host/domain name
signUp.url=http://localhost:8080/fdahpStudyDesigner/signUp.do?securityToken=#localhost:8080 will be changed to host/domain name
db.url=localhost/fda_hphc
db.username=****
db.password=****
#“db.username” value will be changed to actual username of database.
#“db.password” value will be changed to actual password of database.
hibernate.connection.url=jdbc:mysql://localhost/fda_hphc
hibernate.connection.username=****
hibernate.connection.password=****
#“hibernate.connection.username” value will be changed to actual username of database.
#“hibernate.connection.password” value will be changed to actual password of database.
fda.smd.study.thumbnailPath = http://localhost:8080/fdaResources/studylogo/
name.fda.smd.study.pagePath = http://localhost:8080/fdaResources/studypages/
fda.smd.resource.pdfPath = http://localhost:8080/fdaResources/studyResources/
fda.smd.questionnaire.image=http://localhost/fdaResources/questionnaire/
fda.smd.gatewayResource.pdfPath=http://localhost:8080/fdaResources/gatewayResource/App_Glossary.pdf
fda.smd.pricaypolicy=https://www.fda.gov/AboutFDA/AboutThisWebsite/WebsitePolicies/fda.smd.terms=
https://www.fda.gov/AboutFDA/AboutThisWebsite/WebsitePolicies/
#“localhost” will be changed to host/domain
Folder for Audit log files: 
fda.logFilePath="/usr/local/hphcAuditLogs/#Create a folder "hphcAuditLogs" inside the server and update to the same
User registration server root URL: 
fda.registration.root.url = https://hphc-fdama.labkey.com#https://hphc-fdama.labkey.com – Should be replaced with actual URL

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 the below parameters in 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 file for web application available at /src/main/resources folder inside project directory. Obtain the file, and then the changes below are required: https://github.com/PopMedNet-Team/FDA-My-Studies-Mobile-Application-System/tree/2019.10/WCP/fdahpStudyDesigner/src/main/resources

OriginalChanges to make
max.login.attempts=3#Maximum continuous fail login attempts by a user.
password.resetLink.expiration.in.hour=48#Reset password link will expire after the specified hours.
password.expiration.in.day=90#User password expiration in days.
lastlogin.expiration.in.day=90#User will get locked if he/she has not logged in for specified number of days.
password.history.count=10#User cannot reuse the last 10 generated passwords for change password.
user.lock.duration.in.minutes=30#User lock duration in minutes after crossed Maximum continuous fail login attempts limit.
fda.smd.notification.title=HPHC My Studies#Local notification title.
fda.smd.email.title=The HPHC My Studies Platform Team#Email notification title

2.2.3 Settings for Bundle Id and App Token

authorizationResource.properties file for web services application can be found at /studyMetaData/src/main/resources folder inside project directory. Given below are the changes that would need to be made in this file: https://github.com/PopMedNet-Team/FDA-My-Studies-Mobile-Application-System/tree/2019.10/WCP-WS/src/main/resources

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

bundleID and AppToken are security parameters, used to carry out communicate between the WCP and other client applications, via the WCP webservices.

There will be 3 unique bundleID values and 3 unique AppToken values required to be created. Each of these bundleiD-AppToken sets will need to be used with the 3 types of client applications that will communicate with the WCP respectively i.e. MyStudies iOS apps, MyStudies Android apps, and the MyStudies Response Server.

2.3 Build

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

mvn clean install

2.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 was created with StudyMetaData-0.0.1-SNAPSHOT.war name, change the file name from StudyMetaData-0.0.1-SNAPSHOT.war to StudyMetaData.war before deploying to tomcat wabapps.

2.5 Test the application(s)

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

Web application:

Will redirect you to login page. The default username and password is:
User name: superadmin@gmail.com
Password: Password@1234

Web services:

Will display “It Works!”

3 User Registration Web Services

3.1 Getting Started

The User Registration web services are built on the LabKey environment. To start this project, you need to set up the 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 different folder/name please update path in settings.gradle, build.gradle of distributions folder and commands accordingly)

Switch to the release 2019.10 branch and then do git pull.

3.2 Build

3.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 run icon in your IDE

Use this API to ping the local server after it is started with the Run action mentioned above, to verify if the web services are running locally:

To open the LabKey Portal 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 in 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

3.3 Multiple App support

MyStudies supports multiple apps with a single deployment of the platform. In order to manage the data of different apps, the User-Reg server follows a specific project and folder structure for each app:

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

3.3.1 Folder Creation:

The base project (OrgID folder) will hold all information for this organization. Within it, one or more folders for each app (AppID folder(s)) will store the app level data and the subfolders (StudyID folder(s)) will hold all study level data.

Note: For the User-reg server to handle App & Study level data, the following steps need to be followed before publishing the study:
  • If a study with a new AppId is created in WCP server, then the App Folder and Study Folder should be created on the User Registration server’s Labkey Portal interface, with AppId and StudyId as the names respectively.
  • If a study with an already existing AppId is created in WCP server, then only the Study Folder needs to be created.
For more on AppId and StudyId, refer to SECTION: 7.1

Following are the steps to create the folders in the User Registration server and steps to view the data on the server: (Note that for a production/live environment, access to data can be restricted as required by controlling access to the server and also with user permissions on the Labkey Portal.)

Step 1: Create a project to capture all app level data. Choose folder type "Collaboration".

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 APPID of the application in the value of StudyId for the new project you just created, shown here named "Test". Save this change.

Step 4: In the project, create a subfolder to hold all the study level data. Use the "Collaboration" type.

Step 5: 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 "STUDY ID" as the value of StudyId for the new folder (shown here "Test-study").

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

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

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

Step 9: 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:

3.3.2 App Properties API

If a new app is created in WCP server, then the following API should be called manually before publishing the study. This API helps populate the User Registration Server with app-specific data and files that it requires to operate the mobile apps. Please ensure the API is loaded with values as applicable to your app.

Note that the platform may 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.

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

"orgId":"OrgName", // org ID (correctly this value of the orgID has been hardcoded in the code base, so do not change this; this field may be made configurable via WCP in the future)

"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 mails 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 not 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. In case 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.

}

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.

4 iOS Setup

4.1 Introduction

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

4.2 Requirements

4.2.1 IDE Xcode 11 and above can be used to run application. You can install Xcode from MAC App Store.

4.2.2 iOS Application is supported only on iOS 11 and above versions.

4.3 Xcode Setup

After successful installation of xcode follow below steps

4.3.1 Setup Developer Credentials

  • Open Xcode and go to Preferences.
  • Click on Accounts on top menu.
  • Click on (plus) icon and Choose Apple ID.
  • Sign In with Apple developer account.
4.3.2 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 bundle identifier.
4.3.3 Enable for Push Notification Note: To know more on Xcode and above setup Refer to Apple official guide to Xcode Setup

4.4 How to open Project in Xcode

  • Download the project from Github or clone.
  • To open 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.

4.5 How to change Server URLs

Note: Once your Registration, WCP & Response Server are setup please follow below steps.

4.5.1 Setup study configuration After an application is setup on WCP server and after creating the study (REFER SECTION: 7.1), you will need to add your “Application Identifier” into info.plist file.

  • Replace the value for ApplicationID in info.pist file.
4.5.2 Registration Server
  • Look for “RegistrationServerConfiguration.swift” file in Navigator Section and tap on it.
  • Add your Production and Development Server URLs.

4.5.3 WCP Server

  • Look for “WCPConfiguration.swift” file in Navigator Section and tap on it.
  • Add your Production and Development Server URLs.
  • Update your Username (represented as bundle id) and AuthToken (represented as appToken) to call WCP Server API. Please refer to (SECTION: 2.2.3)

4.5.4 Response Server Look for “ResponseServerConfiguration.swift” file in Navigator Section and tap on it. Add your Production and Development Server URLs.

4.6 How to Build and Run

Application can be run on iPhone Simulator OR iPhone Device.

4.6.1 Run on Simulator

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

4.6.2 Run on Device

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

iPhone name will be listed under Device, select iPhone and click on Play button.

4.7 How to setup Standalone Study App

Note: You need to create the standalone study on WCP server first & get the studyID. Once standalone study setup is finished please follow below steps (REFER SECTION: 7.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 & Search for “standalone” 5. Under User-Defined, set the “IS_STANDALONE_STUDY” value as true for both debug and release.

6. Build and run the project.

4.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 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.

5 Android Setup

5.1 Introduction

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

5.2 Requirement

5.2.1 IDE Environment Setup Download Android Studio from the following link and set up the environment.

5.2.2 Android OS Support
  • The application can be run on Android OS starting from Kitkat and up to Pie.

5.3 Steps to pull code from Github

  • a. After setting up the IDE environment do integrate 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 Git Repository URL field.
  • d. Set the path to which Project has to clone in Parent Directory field.
  • e. Give Directory name in Directory Name field.
  • f. Click on Clone button which will download the source code and user can open the MyStudies source code in new window.

5.4 Initial Setup

5.4.1 App Setup

Go to com.harvard package in fda directory and open the AppConfig.java file. Do the following steps:

  • a. To build the app as Standalone update following variable as (REFER SECTION: 7.1)
    public static String AppType = Standalone;
    public static String StudyId = "STUDY ID PROVIDED IN WCP";
  • b. To build the app as GateWay update following variable as (REFER SECTION: 7.1)
    public static String AppType = GateWay;
    public static String StudyId = "NOT REQUIRED FOR GATEWAY APP(CAN LEAVE IT AS EMPTY)";
  • c. Update APP_ID_VALUE variable with the APP ID provided in WCP. (REFER SECTION: 7.1)
  • d. To authenticate the client to make API calls to WCP server, update the value of API_TOKEN with the <value of android.bundleid>:<value of android.apptoken>.(REFER SECTION: 2.2.3)
5.4.2 Push Notification Setup
  • a. Go to your Firebase project
  • b. Set up Push Notification for Android
  • c. Download the json file and replace the google-services.json file in app/src/fda directory.
  • d. Send the Server Key (from Cloud Messaging section of Firebase) in App Properties API.(REFER SECTION 3.3.2)
5.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

5.5 Steps to change API URL

Go to utils package from base package com.harvard.fda in main directory (circled above) and open Urls.java file to put in your server URLs:

  • Update the constant BASE_URL_WCP_SERVER, with the WCP server URL.
  • Update the constant BASE_URL_REGISTRATION_SERVER, with the User Registration server URL
  • Update the constant BASE_URL_RESPONSE_SERVER, with the Response Server URL.

5.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 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 values directory and change information appropriate to your application including App Introduction screen text.

5.7 Steps to install Android app

App can be installed to device or emulator from Android Studio by clicking on the Run button in the Menu bar (image1), which will open a window to choose between emulator and device (image2).

(image 1: icon in circle is the Run button)

(image2: this image shows real connected devices and available virtual devices or emulators):

5.8 Creating the Android app build

  • a. First increment the versionName and versionCode in build.gradle file in App Directory from Project Explorer.
  • b. Click on Build Variants and in Android Studio and click on the area where debug text is displayed.
  • c. Select 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 on Choose existing button.
    • Enter Key store password as “welcome”.
    • Key alias: fda
    • Enter Key password as “welcome”.
    • Click Next.
  • 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.

6 Response Server Setup

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

7 Create Study 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.

7.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)

7.1.1 Basic information

  • Here, the Admin should enter a Study ID (which should be unique for each study) App ID, Study Name, Study Category, Research and Data partners, Study Description and select Standalone or Gateway as the Study Type. (All studies marked as Gateway would appear in a single ‘gateway’ model app. If a Study is marked as Standalone, it would not appear in the Gateway app and instead a single ‘Standalone’ mobile app can be created that will house just that one study.)
  • To have a gateway app, create multiple studies under a single AppId and all of those studies will be visible in the mobile app that has that AppId
  • To have a standalone app, create a single study for a unique AppId and the corresponding mobile app will correspond to that one study only.
  • OrgId (to tie the app to an Organization name) is not supported to be configured via WCP UI as of now, this value has been hardcoded to ‘OrgName’ in the code base for now, and can be changed directly in the code, if necessary. However, in the future, the WCP UI may be enhanced to make this value configurable by the Admin.
  • If Admin chooses Study Type as Gateway, a Study Thumbnail Image should be uploaded as well.

7.1.2 Settings & Admins

Here, the Admin can choose the platform(s) supported, set Enrollment as being open or closed for the study, choose Yes or No to allow Enrollment Date to be used as an Anchor Date to scheduling study activities or resources, set options to retain data for a participant when they leave a study, allow/deny participants to rejoin study once they leave it and define confirmation text for users when they attempt to leave the study.

7.1.2.5 Overview

  • In Overview, the Admin can add multiple pages for a study, which will be reflected in the Mobile app under Study Overview screens.
  • Each Page contains Title, Description and an Image. Admin can also add a Study Video URL on the first page of the Study Overview.

7.1.3 Eligibility

  • In Eligibility section, Admin can choose and set up content for the desired method to be used for ascertaining participant eligibility - Token Validation Only, Eligibility Test Only or Token Validation & Eligibility Test.

7.1.4 Consent section

  • In Consent Sections, the Admin can add ResearchKit/ResearchStack based (pre-formatted mobile UI) or Custom consent section types and fill in content accordingly.
  • Each consent section contains 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 needed to pass the test.
  • In the Review Consent screen, the Admin can choose from either the auto-generated consent document (Concatenated Consent Sections) or create a Custom consent document to be used in the app.
7.1.5 Study Activities – Questionnaires
  • The admin can create questionnaires with a combination of Instruction Steps, Question Steps and Form Steps.
  • Each Question Step comprises of Step-level Attributes, Question-level and Response-level Attributes that offer a number of 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.
  • A number of scheduling options are provided that the admin can choose from to determine the schedule of the survey in the mobile app.

7.1.6 Study Activity – Active Tasks

  • 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 schedule of the active task in the mobile app.

7.1.7 Resources

  • 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.

7.1.8 Notifications

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

7.1.9 Actions

  • In this section, the Admin sees various Actions that can be taken with a Study.
  • Admins can choose to publish the study as an upcoming one, launch the study to start enrolling participants and collecting data, publish updates ongoing to existing studies or Pause/Resume or deactivate them.

7.2 App and Study Folder in User-Reg Server

Create App and Study folders for your app on the User Registration Server (REFER SECTION 3.3).

7.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.)

7.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.
  • 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) 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 into the Study, you can participate in activities that are 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.
  • At the app level, there are other miscellaneous features such as a Notifications section, Account/Preferences section and provisions for participants to provide feedback or contact a designated email inbox for enquiries.

Related Topics




Response Server: Set Up


This topic explains how to set up the response server to begin collecting data from the mobile apps. Each data partner owns a project on LabKey Server, and each study resides in a different subfolder of the parent project. After a participant completes a survey, the mobile application sends the response to the server where it is stored in the appropriate study subfolder.

Enrollment is accomplished by the use of enrollment tokens. A set of enrollment tokens are generated for a given study and distributed to prospective participants as tickets for enrollment in that study. Upon successful enrollment, the server provides the mobile client with a globally unique application token, which the server uses to identify the appropriate study folder and participant on all subsequence communications.

Create a Project

A site administrator can create a new project.

  • Create a new project on the server. The project will serve as the parent container for the study subfolders.

Create a Subfolder

  • Create a new folder of type Mobile App Study within the project.

Assign Permission Roles to Users

LabKey uses a role-based system for assigning individual permissions at different levels. Some important roles for the MyStudies system:

  • Site or Project Admin: Can create new users and assign permissions.
  • Folder Administrator: Can generate and view tokens, make changes to folder permissions, add webparts to pages, plus all actions an Editor can do.
  • MyStudies Coordinator: (Coming soon with LabKey release 20.11) This role can be added onto a Reader or Editor role and gives permission to create and view tokens, but none of the other additional permission granted to folder administrators.
  • Editor: Can read/insert/update response data and create new grid views to share with others.
  • Reader: Can read response data and create new grid views for themselves, but not to share.
Permissions are assigned for each container (project or folder) and can be inherited in subfolders. To assign permissions for a folder, select (Admin) > Folder > Permissions. Add users (or project groups of users) to the desired roles.

For example, you might have a team of researchers to assign to the "Reader" role in a given study folder. One, but not all, of these users might also be assigned to a role that lets them generate tokens.

Learn more about assigning roles to users (and groups of users) in this topic: Configure Permissions

Set Study ID

  • In the panel Study Setup, enter a Study Id. This will be the id used by the mobile application.
  • Select Enable Response Collection. This makes the study open for enrollment and able to store response data.
  • Click Submit.

Generate Tokens

The data partners distribute enrollment tokens to potential participants.

Permissions required:
  • Currently, the role "Folder Administrator" or higher is required to generate tokens.
  • Beginning with version 20.11 of LabKey Server, users with "Reader" or higher PLUS the new role "MyStudies Coordinator" will be able to generate tokens.

Enrollment tokens are specific to the container in which they are generated. A mobile app attempting to enroll using a token from a different study will not be successful and will receive an error message from the server.

  • In the panel Enrollment Token Batches click New Batch.
    • Note that if you do not have administrator permission, this action will not succeed.
  • In the Generate Tokens pop up dialog, specify the number of tokens to generate. Base your selection on the number participants you expect to enroll. Options:
    • 100
    • 1,000
    • 10,000
    • Other <enter custom number of tokens>
  • Click Submit.
Once tokens have been generated, the admin can review each batch, see at a glance how many were generated, how many have been used, and open each batch to find available tokens for distribution.

Set Module Properties

Certain module properties must be defined in order to know where to retrieve the metadata about the study activities that the server is receiving responses for. This metadata is used to create the schema where the response data is stored. This metadata can be retrieved either from a file on the server or from a service (API). In a production system, the service will likely be used.

  • In your study folder, go to (Admin) > Folder > Management > Module Properties tab.
  • Set the following properties, as appropriate. Note that the following properties can be set at three different container scopes: for the Site as a whole, for the current project as a whole, or for a single study subfolder. Enter your values at the Site or Project level will cause them to applied to any other subfolders in scope. Usually you will want to set these at the Site level.
    • SurveyMetadataDirectory - The directory on the server that holds the survey design metadata files. For use in testing or when the metadata service is not available.
    • MetadataServiceBaseURL - The base URL for the Activity Metadata service. Should be an absolute URL that ends with /StudyMetaData; see example below. Note that this URL must NOT end with a question mark.
    • MetadataServiceAccessToken - App token to be passed in request headers to the Activity Metadata Service to identify this client.
If the last two parameters are not configured, the SurveyMetadataDirectory will be used to find the metadata file. If none of the parameters are configured, an error will be generated. The name of the survey metadata file in the SurveyMetadataDirectory should be of the form <studyId>_<activityId>_<version>.txt.

The following screenshot illustrates using a metadata service for the entire LabKey Server site:

The following screenshot illustrates using a local directory only applying the path to the current study subfolder (most useful for development and local testing):

Enrollment Test

To test your set up, enroll (and unenroll) a fictional participant, see Testing the Response Server.

Related Topics




Enrollment Tokens


This topic is under construction.

Generate Tokens

The data partners distribute enrollment tokens to potential participants.

Permissions required:
  • Currently, the role "Folder Administrator" or higher is required to generate tokens.
  • Beginning with version 20.11 of LabKey Server, users with "Reader" or higher PLUS the new role "MyStudies Coordinator" will be able to generate tokens.

Enrollment tokens are specific to the study container in which they are generated. A mobile app attempting to enroll using a token from a different study will not be successful and will receive an error message from the server.

  • In the panel Enrollment Token Batches click New Batch.
    • Note that if you do not have administrator permission, this action will not succeed.
  • In the Generate Tokens pop up dialog, specify the number of tokens to generate. Base your selection on the number participants you expect to enroll. Options:
    • 100
    • 1,000
    • 10,000
    • Other <enter custom number of tokens>
  • Click Submit.
Once tokens have been generated, the admin can review each batch, see at a glance how many were generated, how many have been used, and open each batch to find available tokens for distribution.



User Registration Server: Set Up


This topic describes how to set up and build the APIs required for the FDA MyStudies mobile app Registration Server.

FDA-User Reg WS

This project is developed using the Spring MVC framework in a LabKey development environment. You will find it on github here:

An earlier version of this documentation page is also available on GitHub:

Getting Started

To build this project you need to set up a LabKey development machine. Follow the instructions in this topic:

Next, clone git repositories including UserReg-WS into the /server/modules folder in your enlistment.

Switch to the release 2019.10 branch and git pull.

In your settings.gradle file, find the commented out line with this text: //include ":server:modules:workflow" Underneath this line, add the following two lines. (Note that these might change in the future if folder structure is changed.)

include ":server:modules:UserReg-WS" 
include ":server:modules:UserReg-WS:distributions:Registration"

Generate Local Build

Once the setup is done, build the distribution with this command:

gradlew cleanBuild deployApp

Run and Test

Click the Run (or Debug) icon in your IDE:

Test this URL:

Production Builds

To generate a production build use the below commands:

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

Once the build is completed, you will find the distribution file at this path, where <LABKEY_HOME> is the root of your LabKey enlistment:

<LABKEY_HOME>/dist/Registration



Mobile Client API


This topic is under construction.

LabKey's mobile client api provides enrollment services and data storage for mobile phone client applications. Participants, using a mobile application, can request enrollment in a study, withdraw from a study, and optionally, have their data deleted upon un-enrollment.

Survey responses are stored in dynamically generated tables on the server.

Methods

Method NameDescription
enrollEnrolls a participant in a study on the server. The response includes a globally unique <application-token>; to be used in subsequent communication from the mobile app.

Parameters:
-- studyId (required) - A pre-existing study on the server.
-- token (required) - Enrollment token string provided by the participant. Token validation is case-insensitive. The token is used only once for enrollment; previously enrolled tokens cannot be used again.
-- allowDataSharing (required) - Whether the participant consents to sharing data with third parties. Valid values: "true", "false", "NA"

Afterwards, all submissions to the server are done using the <application-token>.
validateEnrollmentTokenValidates an enrollment token, but does not actually enroll the participant. When successful, returns a JSON object that includes the names and values of all pre-enrollment participant properties associated with that participant.

Parameters:
-- Same params as enroll above.
resolveEnrollmentTokenGiven a valid enrollment token, returns the studyId associated with the folder where the token was generated, whether or not that token has already been used for enrollment.

Parameters:
-- token (required) - Enrollment token provided by the participant.
withdrawFromStudyUn-enrolls a participant. Option to retain or delete data.

Parameters:
-- participantId (required) - The <application-token> provided upon enrollment success.
-- delete - Optional boolean to delete the withdrawn participant's data. Defaults to FALSE.
processResponseSaves survey responses to the study.

Parameters:
-- No parameters in the URL string, but the JSON object provided in the POST body contains the <application-token>.

Examples

Example URLs to invoke:

http://localhost:8080/mobileappstudy-enroll.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA

http://localhost:8080/mobileappstudy-validateEnrollmentToken.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA

http://localhost:8080/mobileappstudy-withdrawFromStudy.api?participantId=<app-token>&delete=<boolean>

http://localhost:8080/mobileappstudy-processResponse.api? (The <app-token> is provided in the posted JSON body.)

On Success

When an action is successful, the server responds with a JSON object with the following format.
{
"success" : true
"data" :
{
"appToken" : "<app-token>",
}
}

In the case of validateEnrollmentToken, pre-enrollment properties will be returned.

{
"success": true,
"data": {
"preEnrollmentParticipantProperties": [
{
"propertyId": "ExternalConsentStatus",
"value": "Fully Consented"
}, {
"propertyId": "Cohort",
"value": "Traditional Diet"
}
]
}
}

On Error

Error responses have the following format:
{  
"exception" : "<message>",
"success" : false,
"errors" : [
{
"msg" : "<message>",
"field" : "form|studyId|token",
"id" : "form|studyId|token",
"message" : "<message>"
}
]
}

As an example, an invalid enrollment token might generate:

{
"success": false,
"exception": "InvalidToken",
"errors": [{
"message": "Invalid token supplied",
"field": "EnrollmentToken",
"id": "abcd1234"
}]
}

Error Cases

The following error cases are handled:
MessageFieldCause
Invalid input formatformThe data provided in the API could not be deserialized properly.
StudyId is required for enrollmentformEmpty or no studyId provided.
Study with studyId "XXX" does not existstudyIdInvalid studyId provided.
Token already in useformThe provided token already has a participant id associated with it in the study's container.
Invalid token: "YYY"tokenThe checksum for the token is incorrect.
Unknown token: "ZZZ"tokenThe token provided has a valid checksum but it is not associated with the given studyId.
Token is not associated with a study IDtokenThere is no study associated with the submitted token.
Token is requiredformThe study associated with the given studyId requires an enrollment token to be provided.

Participant Properties

The WCP (web configuration portal) can provide definitions for participant properties to be included with other information in the mobile app study. For example, if an application wants to survey participants prior to a next appointment, data needs to be stored for each participant about the timing of appointments for that particular participant. When provided, the list of participant property definitions is stored in the study folder, and this list can be queried via the standard selectRows API. In the example, the mobile app is able to ascertain when to send the next survey.

Properties can be either pre- or post-enrollment; though query is typically done only of post-enrollment properties. When the application retrieves values from participant properties, they will see only the properties for the specific participant they are viewing.

Participant properties are keyed on the enrollment token, and post-enrollment properties can also be queried by participantID. The specific participant properties available for a given application will vary. You can see the listing in the MobileAppResponse schema, under Participant Properties.

Participant Property Attributes

When participant properties are defined and passed to the response server, they have the following attributes:

Attributetype/valuesDescription
propertyIdstringA unique identifier under study for participant property.
propertyNamestringA user friendly name for participant property. eg: Date Of Appointment.
propertyTypePreEnrollment/PostEnrollmentThis defines what type of participant property it is.
propertyDataTypestringThe type of the property (string, boolean, etc)
shouldRefreshbooleanWhether to refresh participant property value periodically or not.
dataSourceExternalSystem/OtherDefines from where the value will be populated.
statusactive/deactivatedStatus of participant property
valuedepends on typevalue of participant property sent by external system

Related Topics




Survey Designs and Responses


Survey Designs

Client developers design a survey in JSON and provide either an API that can be used to retrieve this JSON or a JSON file located in a particular directory that can be read when processing responses.

Example

Survey Response Documents

The survey responses are submitted to the server as a JSON object. See example below:

The tables where LabKey stores the survey responses are dynamic generated, meaning the tables are automatically created based on a given survey design. For this reason, the way you structure your survey questions, determines the list schemas on the server, which in turn determines how analysts query the data.

Example

Survey Questions

Electronic data capture surveys are composed of a variety of question types. Review the options available in the core LabKey documentation:

Using the "Other" Option

Mobile App surveys support the option to have questions with an "Other" answer option for multiple choice questions, including those where many answers are allowed. The submitting user checks "Other" and also has the option to enter arbitrary text.

For example, a question "What medications are you taking?" could list a few common options, as well as an "Other" option for unlisted entries. Parameters in the definition of an "other" question are:

  • textfieldReq: (Boolean) Whether custom text input is shown to the respondent
  • placeholder: (String) The string to show in an empty field (prior to entry).
  • isMandatory: (Boolean) Whether completion of the text field is required if the Other option is checked.
The metadata for a multiple choice question including an "Other" option will take this form:
"textChoices" -
[
{
"text" - String
"value" - String
"detail" - String; nil
"exclusive" – Boolean
"destination" - String
"other": {
"textfieldReq" - Boolean
"placeholder" - String
"isMandatory"- Boolean
}
}
];
"selectionStyle" - String; Single/Multiple

The name of all the selected values, including the "Other" option is stored in the main result column. Any text entered as part of the Other option is stored in another column named with a _text extension. i.e. "ResponseColumn_text". If the user did not enter text, or if the Other option hasn’t been selected, this column is null.

Submitting Survey Responses to the Server

Mobile apps submit data to the server using a POST URL, with the body of the POST being a JSON survey response document.

Related Topics




Data Sharing Consent


The Web Configuration Portal supports a Data Sharing Consent workflow for capturing the participant's willingness to share data with with third parties for research. This is in addition to the primary consent they provide to the organization conducting the study.

There is a separate documentation site for the FDA COVID-19 MyStudies app, with information about using that application for the electronic consent portion of this functionality.

When in use, the mobile app needs to provide the collected flag value to the Response server, and then the Response server needs to store the provided value, associate it with that participant’s record, and provide the value to analysts when they view or retrieve response data. Note that the Response server simply conveys the value of the flag; it has no ability to enforce behavior. The onus is on the analyst to take the appropriate action (e.g., filtering on the flag column, sharing data or not).

Functional Design

The Response server stores the allowDataSharing flag values in the column: mobileappstudy.Participant.AllowDataSharing. The Participant table is already available in the response lists, so this new column is also available for adding to grids via Customize Grid.

Checking the box for "Allow Data Sharing" in Customize Grid makes that column available in the grid for viewing, filtering, sorting, export, API querying, etc. LabKey SQL queries can also use this column.

Related Topics




Testing the Response Server


This topic explains how to manually test the enrollment and data submissions methods described in the topic Mobile Client API.

Assumptions

We assume that you have already completed the following set up steps, all described in the topic Response Server: Set Up:

  • A parent project has been created.
  • A subfolder of type 'Mobile App Study' has been created.
  • A StudyId has been specified and data submission has been enabled in the subfolder.
  • Enrollment tokens have been generated.

Set Up a Test Environment

To set up a testing environment:

  • Complete all of the steps above in Assumptions.
  • And follow steps below:
When manually testing the submission method, it is useful to get a complete view of the enrollment tokens, participant ids, and app tokens in one grid. To make this grid do the following:
  • Go to the study folder to be tested.
  • In the panel Enrollment Token Batches, select a batch of (already generated) enrollment tokens. (Click a value in the Batch Id column.)
  • On the Enrollment Tokens grid, select (Grid Views) > Customize Grid.
  • Under Available Tokens check the box for Show Hidden Fields.
  • Open the node Participant Id, and place checkmarks next to Participant Id and App Token.
  • Click Save and save the grid as the default view.
  • Now you have a table of available App Tokens to use in testing.
It is also convenient to add the Lists web part and the mobileappstudy schema to your study folder, so you can easily track submitted data and any errors that arise.
  • To add the Lists web part:
    • Enter > Page Admin Mode.
    • In the lower left corner of the page, click the dropdown Select Web Part, and select Lists. Click the Add button. (Before the submission of data there are no Lists yet. Once data has been submitted and processed, the data, partitioned into Lists, will appear here.)
  • To add the mobileappstudy schema:
    • Again click the dropdown Select Web Part, and select Query.
    • For Web Part Title enter 'mobileappstudy'.
    • On the Schema dropdown select mobileappstudy.
    • Click Submit.
    • Click Exit Admin Mode to hide the page editing tools.

Test Enrollment

  • To test your set up, enroll a fictional participant in the study by calling an URL like the following.
    • For <server>, if you are working on a local machine use 'localhost:8080'. Or substitute the domain name appropriate for your set up, such as 'myserver.labkey.com'.
    • For <study-id>, substitute the value you have specified for the target subfolder.
    • For <enrollment-token>, substitute one of the enrollment token values generated in that folder.
http://<server>/mobileappstudy-enroll.api?studyId=<study-id>&token=<enrollment-token>
  • Successful enrollment will produce a response like the following:
{
"data" : {
"appToken" : "2b277794d8f209a05e9259b076362bda"
},
"success" : true
}
  • Copy the appToken value for further testing. LabKey Server uses this appToken value in all future communications to figure out (1) where to save submitted data and (2) which participant the data pertains to.

Test Data Submission

LabKey Server provides a built-in tool for testing the submission process:

  • The built-in tool is located at the following URL, substituting <server> as appropriate to your environment.
    • Note: we have also had success testing via the Chrome plugin Postman.
http://<server>/query-APITest.view
  • In Post URL enter an URL like the following:
http://<server>/mobileappstudy-processResponse.api?
  • In Post Body enter the survey responses as a JSON object. Download a sample object is available at: InitialSurvey_v2.2.1.json
  • In the JSON object, substitute the participantId value with one of the appTokens (not enrollment token) provided to you on successful enrollment of a participant.
  • Click the Post button.
  • On successful submission, the Response body panel will display the following:
{
"success" : true
}

Withdraw From a Study

  • To withdraw the fictional participant, and delete any submitted survey responses, call the action withdrawFromStudy.api, where <appToken> is the appToken for the withdrawing participant.
.../withdrawFromStudy.api?delete=TRUE&participantId=<appToken>

Troubleshooting

If test does not produce the success message, an admin or troubleshooter can check the Response table for possible error status messages. Select (Admin) > Go To Module > Query. Open the mobileappstudy schema and click the Response table. Click View Data. Scan or filter the Status column for any errors, and for these, check the Error Message column.

Incorrect Module Properties

Error: If you see an Error Message similar to

There were problems storing the configuration. Received response status 400 using uri https://SERVER_NAME/StudyMetaData/activity?%2FparticipantProperties&studyId=STUDYID_001"

Solution: Notice the "%2F" in the path - this encoded slash indicates an incorrect creation of the full URI. Check the setting of the module property "MetadataServiceBaseUrl" to confirm that it ends with "StudyMetaData" and does not end with a question mark.

Related Topics




Response Processing


Submitted data, in the form of JSON objects, is stored in the Response table. The Response table holds the raw JSON objects before they are parsed into the individual data tables. The Response table also forms a dashboard for viewing errors associated with parsing and for manually kicking off reprocessing of responses.

Parsing and Processing

The Responses table keeps track of whether responses were parsed successfully or not. Unsuccessfully parsed responses can be re-processed. Common errors in processing include:

  • A question’s answer is not the expected type.
  • A table name doesn’t match any List in the schema.
  • A column in the response does not exist in the expected List.
  • The format of the response JSON does not match the expected format.
To view the Responses table:
  • Go to (Admin) > Developer Links > Schema Browser, open the schema mobileappstudy, and click Response, then View Data.
    • OR
  • To create a handy link on your study page, add a Query web part to display the mobileappstudy schema. For details see Set Up a Test Environment.

Reprocessing

From the Response table, editors can see the status of an event and can reprocess only responses that have not previously been successfully processed. Reprocessing is useful if the errors were caused by bugs in the processing code that have since been fixed. To reprocess, select the checkbox of a record(s) and click Reprocess.

Editing

To edit, hover over a row to expose the (pencil) icon for editing. There is no ability to edit the responses before reprocessing.

Processed Data and Dynamic List Creation

Successfully processed data is stored in simple tables called "Lists". The names of the tables and their columns are determined by the shape of the survey document submitted.

There is a List for each activity (e.g., InitialSurvey, WeeklySurvey, MonthlySurvey, ActiveTask1, etc.). The activity List contains the participantId and a column for each single-valued response in the survey. These are responses whose type is one of the following:

  • scale
  • continuousScale
  • textScale
  • valuePicker
  • boolean
  • numeric
  • timeOfDay
  • date
  • text
  • email
  • timeInterval
  • height
  • location
For these responses, the column name is the same as the key value for the question.

For example, the response JSON submitted under the activity "InitialSurvey":

"results" : [
{
"resultType" : "date",
"key" : "dueDate",
"value" : "2017-10-17"
}
]

results in a List named "InitialSurvey" with a field "DueDate":

InitialSurvey
DueDate

For each multi-valued response (i.e., those of type imageChoice, textChoice, or grouped), there is a separate List with a name that follows the pattern <survey name><key>.

For example, the following response JSON:

"results" : [
{
"resultType" : "textchoice",
"key" : "supplements",
"skipped" : false,
"value" : [
"Q10",
"B12"
]
}
]

results in the following tables and fields:

InitialSurvey
InitialSurveySupplements
Supplements

For grouped results in which each response in the group is single-valued, there is a new List created that corresponds to the grouped response’s key and with a column in the table for each response within the group. For imageChoice and textChoice fields, there is a List for the response with the column name corresponding to the response key.

For grouped results in which there are responses that are multi-valued, there is a List created that corresponds to the grouped response’s key value with a column in the table for each single-valued response in the group. There is also a separate List created for each multi-valued response in the group. The name of the List is <survey name><group response key><response key> and it contains a foreign key to the grouped result List.

For example, the following response JSON:

"results" : [
{
"resultType" : "grouped",
"key" : "rx",
"value" : [
{
"resultType" : "textchoice",
"key" : "medName",
"value" : [
"Acetaminophen"
]
}
]
}
]

results in the following Lists and fields

InitialSurvey
InitialSurveyRx
InitialSurveyRxMedName
MedName

The following three active task types are supported as special grouped results for which certain specific fields will be created in their corresponding Lists.

resultTypeFields
fetalKickCountercount (Integer), duration (Integer)
towerOfHanoipuzzleWasSolved (Boolean), numberOfMoves (Integer)
spatialSpanMemoryscore (Integer), numberOfGames (Integer), numberOfFailures (Integer)

When a survey design contains one of the resultTypes shown above, a List will be created just as with a grouped result containing the fields indicated.

For grouped results within grouped results, we’ll generate Lists recursively according to the above pattern.

The List structure is denormalized so all Lists contain the ParticipantId column, which makes it easier to perform filtered queries on any of the Lists. (This is the rowId from the participant table in the mobileAppStudy schema.)

Lists natively support many data analysis and reporting features, including

  • Filtering survey results by a particular participant to track changes to that participant’s responses over time.
  • Unioning multiple Lists based on a participant id to view all of that participant’s responses from multiple surveys.
  • Creating plots and visualizations.
  • Exporting all or filtered results to Excel, text, or other common formats.
  • Using the SAS API, Rlabkey API, or other language bindings to extract responses into SAS, R, or another tool/language.

Response Forwarding

An administrator can configure the Response Server to forward responses to another server. For instance, copying processed responses to a remote Salesforce server might be required in a particular kind of study.

Folder administrators can enable and disable response forwarding for a given folder with two types of authorization:

  • Basic Authorization: Provide a username and password, plus the endpoint URL.
  • OAuth: Provide a token request URL, token field, header name, and endpoint URL.
  • Disabled: (Default) Disable forwarding.
  • Select (Admin) > Folder > Management.
  • Click the Response Forwarding tab.
  • By default, forwarding is disabled. To enable, choose one of the options and enter the required information.
  • Click Submit.

Once response forwarding is enabled, a pipeline job is enabled to post the responses to the configured external server. This job will run every 5 minutes as well as after every successful response processing, as long as the job is 'succeeding'. The forwarding status is recorded in the Responses table.

  • Processed: A response that has been processed but not yet successfully forwarded.
  • Forwarded: A response that has been successfully forwarded.
  • Error: An error was seen at the last processing attempt.
The pipeline job queries the Response table for every row whose status is "PROCESSED", but not yet "FORWARDED". For each such row, post the response JSON and the corresponding enrollment token to the configured URL, authorizing the request by conveying configured credentials via basic authentication; wait for the external system to respond:
  • If the external system responds with "success", the status of the corresponding row in the Response table is updated to "FORWARDED" and this response will be never sent again.
  • If any failure occurs (can't connect, timeout, failure response), the job exits immediately and the Response server will wait and re-try that post at the next 5 minute interval.
If a full batch of responses is sent successfully, the external system will be flagged as "succeeding", otherwise, it will be flagged as "failing."

Responses that have been already forwarded successfully will not be reforwarded.

Related Topics




Querying the Response Server


This topic explains how to retrieve data from the server in order to create reports and visualizations.

Data can be read from the server using two methods in LabKey's mobile app study API:

  • selectRows: read response values from one or more columns with options to filter and sort the rows
  • executeSQL: execute an arbitrary SQL SELECT query on the response schema, allowing for complex joins and transformations on the data
All data retrieval is filtered to a single participant (the participant corresponding to the app token accompanying the retrieval request). Also, all data retrieval is constrained to a single schema on the server named "MobileAppResponse". This means you cannot SELECT or JOIN to other tables outside this schema.

selectRows

Uses all the parameters from LABKEY.Query.selectRows, with the following differences:

  • schemaName is ignored, since MobileAppResponse is hardcoded in this context.
  • participantId is added. Its value is the <appToken>.
The general pattern for invocation is:
http://<server>/mobileappstudy-selectRows.api?participantId=<appToken>&queryName=<queryName>

where:

  • <appToken> is the unique string associated with a given participant and study folder. The <appToken> is provided to the mobile app when a participant successfully enrolls in the study.
  • <queryName> is the name of some table in the schema MobileAppResponse.
An example invocation:
http://myserver.com/mobileappstudy-selectRows.api?participantId=a1f4960d78bcc08295807901a3b74ad&queryName=InitialSurvey

The server will respond with the data in JSON format:

{
"schemaName" : "MobileAppResponse",
"queryName" : "InitialSurvey",
"formatVersion" : 8.3,
"metaData" : {
"importTemplates" : [ {
"label" : "Download Template",
"url" : "/labkey/query/MyProject/MyStudy/exportExcelTemplate.view?schemaName=list&query.queryName=InitialSurvey&headerType=Name"
} ],
"root" : "rows",
"totalProperty" : "rowCount",
"description" : null,
"id" : "Key",
"fields" : [ {
"ext" : { },
"name" : "ParticipantId",
"align" : "right",
...

executeSQL

Uses all the parameters from LABKEY.Query.executeSql, with the following differences:

  • schemaName is ignored, since MobileAppResponse is hardcoded in this context.
  • participantId is added. Its value is the <appToken>.
The following parameters are required:
  • sql
  • participantId
The general pattern for invocation is:
http://<server>/mobileappstudy-selectRows.api?participantId=<appToken>&sql=<sqlQuery>

where:

  • <appToken> is the unique string associated with a given participant and study folder. The <appToken> is provided to the mobile app when a participant successfully enrolls in the study.
  • <sqlQuery> is some query on a table or tables in the schema MobileAppResponse. SQL queries passed via the URL should be URL encoded.
For example, the following queries the InitialSurvey table with 'SELECT * FROM InitialSurvey', shown in its URL encoded form:
http://myserver.com/mobileAppStudy-executeSQL.api?participantId=ca1f4960d78bcc08295807901a3b74ad&sql=SELECT%20*%20FROM%20InitialSurvey

The following example adds a date filter 'SELECT * FROM InitialSurvey WHERE DueDate = '2017-12-12'', shown in its URL encoded form:

...mobileAppStudy-executeSQL.api?
participantId=ca1f4960d78bcc08295807901a3b74ad&
sql=SELECT%20*%20FROM%20InitialSurvey%20WHERE%20DueDate%20=%20%272017-12-12%27

Complex joins and unions can be provided in the sql parameter, for example, the following joins to the InitialSurveyRxGroup table:

SELECT InitialSurvey.ParticipantId,
InitialSurvey.DueDate,
InitialSurvey.PlannedPregnancy,
InitialSurvey.FolicAcid,
InitialSurveyRxGroup.Medication AS MedicationName
FROM InitialSurvey
INNER JOIN InitialSurveyRxGroup ON InitialSurvey.ParticipantId = InitialSurveyRxGroup.ParticipantId

Reference




External Documentation Resources


Other technical documents and set up guides:
There is a separate documentation site for the FDA COVID-19 MyStudies app, with information about using that application for the electronic consent portion of this functionality.