• FDA's MyStudies Application Technical Background

• 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

Technical Setup for FDA MyStudies

Begin here:

• FDA MyStudies: Technical Setup Document

Response Server Topics

• Response Server: Get a Distribution - Build a standalone distribution of the Response Server (i.e., a standard LabKey Server distribution plus the Response module).
• 7: Response Server Setup - How to set up the server to enroll participants and receive data.
• Response Processing - How to parse raw JSON responses into data tables.
• Response Forwarding - Forward responses to another server.
• Testing the Response Server - Testing your set up with fictional participants.
• Querying the Response Server - Querying collected data.

Registration Server Topics

• User Registration Server Set Up - Build the APIs required for the Registration Server.
• Limit Login Attempts - Limit the number of attempted logins.
• Set Up User Account Expiration Date - Set a date after which user accounts expire.
• Disable Inactive Accounts - Disable user accounts that inactive.
• Audit Process Notifications - Control notifications when problems arise with auditing.

Web Configuration Portal Topics

• Web Configuration Portal Set Up
• Data Sharing Consent

Topics for Mobile App Developers

• Mobile App Quick Overview for Research
• Mobile Client API - How mobile apps use the client API.

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

Sections

• 1 Introduction
• 2 High-Level Technical Architecture
• Multiple Language Support
• 3 WCP and Webservices Setup Instructions
• 3.2 Configuration and Setting Properties
• 4 User Registration Web Services
• 4.3 Multiple App Support: Folder Creation and Configuration
• 5 iOS Setup
• 6 Android Setup
• 7 Response Server Setup
• 8 Create Your Study on WCP and Run

1 Introduction

This documentation 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.

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

Multiple Language Support

When you configure a study, you have the option to elect whether to support multiple languages for the user. Beginning with version 21.10 (October 2011), English is the default and Spanish language is also supported.

Note that all administrative actions for setting up the study and resources for researchers/data analysts will be presented in English. The multiple language support applies only to the information and messages shown to the user of the mobile app.

Administrators can Enable Multiple Language Support when defining a study on the WCP, providing both English and Spanish question and answer options. For studies with both defined, the version supplied to the user will be determined by the settings on the mobile device.

If a language other than Spanish is selected on the device, the questions and responses will default to English.

3 WCP and Webservices Setup Instructions

To set up the WCP and Webservices and web services, follow the instructions here:

• 3: WCP and Webservices Setup

• 3.1 Installation Required
• 3.2 Configuration
• 3.2.1 Initial Configuration
• 3.2.2 Properties Files
• 3.2.3 Bundle Id and App Token Settings
• 3.2.4 Set Super Admin Email ID
• 3.3 Build
• 3.4 Deployment
• 3.5 Test the Application(s)

4 User Registration Web Services

To set up the User Registration Server and web services, follow the instructions here:

• 4: User Registration Web Services

• 4.1 Getting Started
• 4.2 Build
• 4.3 Multi App Support
• 4.3.1 Folder Creation
• 4.3.2 App Properties API

5 iOS Setup

To set up the FDA MyStudies iOS app and install and run it on an iPhone, follow the instructions here:

• 5: Building the IOS App

• 5.2 Requirements
• 5.3 Xcode Setup
• 5.4 How to Open Project in Xcode
• 5.5 How to Change Server URLs
• 5.5.1 Set up study and API configuration
• 5.5.2 Registration Server
• 5.5.3 WCP Server
• 5.5.4 Response Server
• 5.6 How to Build and Run
• 5.7 How to set up a Standalone Study App
• 5.8 Apply Your Branding
• Appendix: Build at the Command Line

6 Android Setup

To set up the FDA MyStudies Android app, and install and run it on an Android device, follow the instructions here:

• 6: Build the Android App

• 6.1 Introduction
• 6.2 Requirements
• 6.3 Steps to Pull Code from GitHub
• 6.4 Initial Setup
• 6.5 Apply Your Branding
• 6.6 Steps to Install Android app
• 6.7 Creating the Android app build
• Appendix: Build at the Command Line

7 Response Server Setup

To set up the Response Server, follow the instructions here:

• 7: Response Server Setup

• 7.1 Create a Project
• 7.2 Create a Subfolder
• 7.3 Assign Permission Roles to Users
• 7.4 Study Setup
• 7.5 Generate Tokens
• 7.6 Set Module Properties
• 7.7 Enrollment Test

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

Details for creating a new study in the WCP are covered in this topic:

• 8: WCP - Create New Study

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

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

• 7: Response Server Setup
• 8: WCP - Create New Study
• 5: Building the IOS App

This topic covers how to set up the WCP and WCP-WS web services. This is section 3 of the overall setup process covered in: FDA MyStudies: Technical Setup Document.

• 3.1 Installation Required
• 3.2 Configuration
• 3.2.1 Initial Configuration
• 3.2.2 Properties Files
• 3.2.3 Bundle Id and App Token Settings
• 3.2.4 Set Super Admin Email ID
• 3.3 Build
• 3.4 Deployment
• 3.5 Test the Application(s)

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.

• https://www.java.com/en/download/

3.1.2 Tomcat 8

The link below will help you download and install Apache Tomcat and use many of the Apache Tomcat features

• https://tomcat.apache.org/tomcat-8.0-doc/setup.html

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.

• https://dev.mysql.com/doc/refman/5.7/en/installing.html

3.1.4 Maven

The link below will assist you in installing Maven

• https://maven.apache.org/install.html

3.1.5 Git Repository

Source code for WCP application and Web Services is available at:

• https://github.com/FDA-MyStudies/FDA-My-Studies-Mobile-Application-System
• The following modules are to be used:
• WCP (Source code of the WCP): https://github.com/FDA-MyStudies/WCP
• WCP-WS (Source code of WCP Web Services): https://github.com/FDA-MyStudies/WCP-WS
• fdaResources (This will be available in WCP repo. <Tomcat installed path>/web apps/)

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:

• https://github.com/FDA-MyStudies/WCP/tree/develop/sqlscript

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

• https://github.com/FDA-MyStudies/WCP

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

• <tomcat installed path>/tomcat/conf/

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

• https://github.com/FDA-MyStudies/WCP/blob/develop/fdahpStudyDesigner/src/main/resources/messageResource.properties

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:

• https://github.com/FDA-MyStudies/WCP-WS/blob/develop/src/main/resources/authorizationResource.properties

{Unique Identifier}=android.apptoken	#Unique Android identifier.
{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 and update "your email address" text in HPHC_My_Studies_DB_Create_Script.sql file with the email id that you want to keep as super admin for WCP application. Use forgot password functionality to set a password.

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.

Web services:

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

This will display “It Works!”

Next Steps

Continue with setup in the main document

Related Topics

• FDA MyStudies: Technical Setup Document

• 4.1 Getting Started
• 4.2 Build
• 4.3 Multi App Support
• 4.3.1 Folder Creation
• 4.3.2 App Properties API

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:

• https://www.labkey.org/Documentation/wiki-page.view?name=devMachine

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"

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:

http://localhost:8080/labkey/home/project-begin.view?

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

• https://www.labkey.org/Documentation/wiki-page.view?name=moduleDevelopmentDeployment

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

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.

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

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.

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

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.

Next Steps

Continue the setup instructions in the main document

Related Topics

• FDA MyStudies: Technical Setup Document

• 5.1 Introduction
• 5.2 Requirements
• 5.3 Xcode Setup
• 5.4 How to Open Project in Xcode
• 5.5 How to Change Server URLs
• 5.6 How to Build and Run
• 5.7 How to Set Up a Standalone Study App
• 5.8 Apply Your Branding
• 5.9 Next Steps
• Appendix: Build at the Command Line

5.1 Introduction

This topic covers how to set up the FDA MyStudies iOS app and install and run it on an iPhone. This is section 5 of the overall setup process covered in: FDA MyStudies: Technical Setup Document

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.

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

• Create push notification certificates for newly created applications.
• Encode the .p12 file to Base64 test and send this in App Properties API.(REFER SECTION 4.3.2)
• For more information, visit the official Apple page for Establishing a Certificate-Based Connection to APNs

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), 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 (REFER SECTION: 8) please follow the steps below:

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.

5.9 Next Steps

Continue with set up in the main document.

Appendix: Build at the Command Line

It may be desirable to build your MyStudies iOS app at the command line (rather than in the GUI of Xcode) as with CI/CD or other automation. This next section will serve as a brief overview and basic example of building and testing the iOS app using the Xcode CLI tool "xcodebuild". Refer to Github Actions configuration (.github/workflows/Build-iOS.yml) in the repo when configuring similar CI/CD automation on other platforms.

For the purposes of code validation, valid iOS code-signing is not necessary. Building with valid code-signing falls outside the scope of this guide.

These instructions assume Xcode 11 is being used from /Applications/Xcode_11.X.app.

Appendix.1 Set Xcode Code-Signing Environment Variables

The primary purpose of these is to disable code-signing:

export CODE_SIGN_IDENTITY=''
export CODE_SIGNING_REQUIRED='NO'

Appendix.2 Set Xcode Architecture Environment Variable

The following environment varaible limits the code to being compiled only for the CPU architecture of the machine running Xcode and is desirable to avoid building for iOS device architectures for the purposes of code validation:

export ONLY_ACTIVE_ARCH='YES'

Appendix.3 Change to the "HPHC" Directory Within the Repo

Some steps of the build process assume that you are in the "HPHC" directory, which is a sub-directory of the root of the repo:

cd HPHC

Appendix.4 Build

To build, use xcodebuild from the HPHC directory. You may need the full path to xcodebuild, and must substitute your platform, OS, and name settings in the -destination argument:

/Applications/Xcode_11.7.app/Contents/Developer/usr/bin/xcodebuild clean build -workspace HPHC.xcworkspace -scheme HPHC -destination "platform=iOS Simulator,OS=13.7,name=iPhone 11"

If you are using a GitHub Actions config instead of including the specific versions in the command string you could define a "matrix.destination" such as:

strategy:
      matrix:
        destination: ["platform=iOS Simulator,OS=13.7,name=iPhone 11"]

Then run, using syntax like:

xcodebuild clean build 
  -workspace HPHC.xcworkspace 
  -scheme HPHC 
  -destination "${{ matrix.destination }}"

Appendix.5 Test

xcodebuild test 
            -workspace HPHC.xcworkspace 
            -scheme HPHC 
            -destination "${{ matrix.destination }}"

References

• https://github.com/FDA-MyStudies/iOS/blob/48a6e770ac1428261043100fe2084210d41a9a50/.github/workflows/Build-iOS.yml
• https://github.com/FDA-MyStudies/iOS/blob/48a6e770ac1428261043100fe2084210d41a9a50/.github/workflows/lint-iOS.yml
• Output of runs: https://github.com/FDA-MyStudies/iOS/runs/2839702321

Related Topics

• FDA MyStudies: Technical Setup Document

• 6.1 Introduction
• 6.2 Requirements
• 6.3 Steps to Pull Code from GitHub
• 6.4 Initial Setup
• 6.5 Apply Your Branding
• 6.6 Steps to Install Android app
• 6.7 Create the Android App Build
• 6.8 Next Steps
• Appendix: Build at the Command Line

6.1 Introduction

This topic explains how to setup the FDA MyStudies Android app and install and run it on an Android device. This is section 6 of the overall setup process covered in: FDA MyStudies: Technical Setup Document

6.2 Requirements

6.2.1 IDE Environment Setup

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

• https://developer.android.com/studio

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

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.5 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.6 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.7 Create 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.

6.8 Next Steps

Continue with set up in the main document.

Appendix: Build at the Command Line

It may be desirable to build your Android app at the command line, particularly for use with automation. This next section will serve as a brief overview and basic example of building and testing the app in this way.

The Android app repo uses gradle to execute builds. Gradle operates on a self-bootstrapping basis, meaning that you do not specifically need to install gradle beforehand, as gradle will take care of "installing itself" the first time you run the build. Other LabKey projects also use gradle, and you can learn more about using gradle with LabKey in this section of the LabKey Server documentation (opens in a new tab): Gradle Build Overview

Appendix.1 Set Up the Android SDK

You'll need the Android SDK from either the "Android Studio" desktop app or the "commandline-tools".

Ensure that the Android SDK license is accepted. The license acceptance process is specific both to the OS you're using and to how you installed the Android SDK. And as such, is not specifically covered by this guide. You will need to have accepted the Android SDK/Android Studio licenses to proceed.

• Attempting to build without accepting the licenses results in error messages like the one below:

  You have not accepted the license agreements of the following SDK components: [Android SDK Platform 23, Android SDK Build-Tools 23.0.1]. Before building your project, you need to accept the license agreements and complete the installation of the missing components using the Android Studio SDK Manager.

Appendix.2 Ensure Gradlew is Executable

Building is done using the gradlew script. On platforms other than Windows, to ensure this script is executable, run:

chmod a+x ./gradlew

As with most gradle projects, you can use the following command to see what tasks are available in this repo:

./gradlew tasks

Appendix.3 Set Environment Variables

Set the $ANDROID_HOME environment variable. The value of this environment variable is specific both to the OS you're using and to how you installed the Android SDK. Determining the path to your Android SDK is not covered by this guide.

Ensure that the $JAVA_HOME environment variable is set correctly. At time of writing, this repo expects to use JDK version 1.8/8

Running ./gradlew build without setting the $JAVA_HOME environment variable results in error messages like the one below:

FAILURE: Build failed with an exception.

* What went wrong:
Could not create an instance of type org.gradle.initialization.DefaultSettings_Decorated.
> Could not initialize class org.codehaus.groovy.runtime.InvokerHelper

Appendix.4 Configure Code Signing for the App

Code signing for the app must be configured. Learn more in the official documentation on the Android developer site:

• https://developer.android.com/studio/publish/app-signing

Appendix.5 Build the App

If your goal is simply to determine if the project builds at all, you can now run gradle with ./gradlew build without filling in apikey.properties.

• You'll find the resultant .apk files under the app/build/outputs/apk/fda/debug and app/build/outputs/apk/fda/release directories.
• These .apk files are explicitly untracked in the repo as is common for binary artifacts, so you won't see them in git status after building them.

./gradlew build

Related Topics

• FDA MyStudies: Technical Setup Document

• 7.1 Create a Project
• 7.2 Create a Subfolder
• 7.3 Response Server Site Settings
• 7.4 Study Configuration
• Set Study ID
• Update Metadata
• 7.5 Assign Permission Roles to Users
• 7.6 Generate Tokens
• 7.7 Enrollment Test

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

If you are adding a study to an existing project, navigate to that location. A site administrator can create a new project, typically named for the app or organization performing the studies.

• Create a new project on the server. The project will serve as the parent container for the study subfolders.
• Choose folder type "Collaboration".
• For now, leave the permissions limited to your own user ID until you have correctly configured the folder. See below for how to add additional authorized users.

Create a Subfolder

Within the project:

• Create a new folder of type "MyStudies Response".
• For now, leave the permissions limited to your own user ID until you have correctly configured the folder. See below for how to add additional authorized users.

In your new folder, you will see the MyStudies Response Server panel, which will guide you in setting up your study, then provide a quick view dashboard of the configuration to others.

Response Server Site Settings

A one-time setup step for the Response Server is for a site administrator to connect it to the WCP, or otherwise provide metadata for testing. This configuration was previously done using module properties with similar names.

If you see a message in the MyStudies Response Server panel like the following:

Response Server Site Settings are not configured. Click here to configure them.

• Click the word "here" to configure.
• A site administrator can also directly access this page via (Admin) > Site > Admin Console > Configuration > Response Server Configuration.

Configure how to load metadata. An option to load metadata from files is provided for local testing. For operational servers, you'll use Load metadata from WCP server.

• Provide:
• WCP Base URL: The base URL for the Activity Metadata service. Should be an absolute URL that ends with /StudyMetaData. Note that this URL must NOT end with a question mark.
• Username: The username to use to authenticate against the WCP server, NOT the Response Server.
• Password: The password for that username on the WCP.
• Click Save And Finish.

Local Testing File Option

If you want to use the Load metadata from files (used for local testing) option, provide the directory on the server that holds the survey design metadata files. These metadata files should be of the form <studyId>_<activityId>_<version>.txt.

Study Setup

Once the site settings are configured, you can configure the study folder itself to collect the correct responses.

Set Study ID

• In the MyStudies Response Server panel, you'll see a red indicating the study needs to be configured. Click either "Study Configuration" or the word "here" in the message to configure it.

• You will now be on the MyStudies Response Server tab of the (Admin) > Folder > Manage page.

• Enter the StudyID value exactly as it appears on the WCP. In concert with the site settings you entered above, this will route the expected responses for this study to this folder.
• Check the box for Enable Response Collection. This makes the study open for enrollment and able to store response data.
• Click Save.

Update Metadata

Click Update Metadata on the Study Setup panel (shown above) to proactively create or update the response schema based on the latest study metadata in the WCP. Note that this step is not required for successful response submission (the response schema is updated automatically when a response indicates a newer version is available), but can assist administrators who wish to pre-populate participant properties or create queries and reports before response data is submitted.

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.

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

Generate Tokens

The data partners distribute enrollment tokens to potential participants.

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 "MyStudies Coordinator" or admin 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.

Enrollment Test

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

Related Topics

• Testing the Response Server
• Mobile Client API

Generate Tokens

The data partners distribute enrollment tokens to potential participants.

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 "MyStudies Coordinator" or admin 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.

• 7.1 Create a Project
• 7.2 Create a Subfolder
• 7.3 Assign Permission Roles to Users
• 7.4 Study Setup
• Set Study ID
• Update Metadata
• 7.5 Generate Tokens
• 7.6 Set Module Properties
• 7.7 Enrollment Test

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.

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

Study Setup

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.

Update Metadata

Click Update Metadata in the Study Setup panel (shown above) to proactively create or update the response schema based on the latest study metadata in the WCP. Note that this step is not required for successful response submission (the response schema is updated automatically when a response indicates a newer version is available), but can assist administrators who wish to pre-populate participant properties or create queries and reports before response data is submitted.

Generate Tokens

The data partners distribute enrollment tokens to potential participants.

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 "MyStudies Coordinator" or admin 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.

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.

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

• Testing the Response Server
• Mobile Client API

This topic is part of the FDA MyStudies: Technical Setup Document. It covers the details for section creating a new study in the WCP from this point in the setup process.

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.

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.

Related Topics

• FDA MyStudies: Technical Setup Document

The automation consists of two components, described in these topics:

• Installation Script Automation: Accelerates the installation of LabKey and/or MyStudies servers and can be used in on-premise installations or in cloud deployments
• AWS (Terraform) Deployment Automation: A full featured automated deployment of the required infrastructure to deploy a functional MyStudies Application Infrastructure. This automation leverages the Install Script automation to deploy MyStudies Application servers with AWS.

• Overview
• Supported Operating Systems
• Quick Start
• Reference

What does this script automate?

Supported Operating Systems

• Amazon Linux 2
• Centos 7
• RedHat RHEL 8
• Ubuntu 20.04

Quick Start

Example Usage: Install MyStudies Registration Server

sudo su -
git clone https://github.com/FDA-MyStudies/install-script.git
cd ./install-script
source ./sample_registration_envs.sh 
./install-labkey.bash

Example Usage: Install MyStudies Response Server

sudo su -
git clone https://github.com/FDA-MyStudies/install-script.git
cd ./install-script
source ./sample_response_envs.sh
./install-labkey.bash

Example Usage: Install MyStudies WCP Server

sudo su -
git clone https://github.com/FDA-MyStudies/install-script.git
cd ./install-script
source ./sample_wcp_envs.sh 
./install-wcp.bash

Reference

A substantial list of configurable environment variables is documented in the repo ReadMe file here:

• https://github.com/FDA-MyStudies/install-script#inputs-reference

Related Topics

• FDA MyStudies Infrastructure Deployment Automation
• Deployment Automation with Terraform

• Overview
• Deployment Considerations
• Deployment Options
• Quick Start
• Troubleshooting

Overview

This topic example describes how to deploy a functional MyStudies Application Server Environment in AWS using the MyStudies Terraform Module with the following features:

• VPC
• Bastion Host
• Application Load Balancer
• TLS/SSL Certificate
• Route 53 DNS Domain Records
• Secrets Management
• Security Groups
• Registration Application Server
• Registration Database Server
• Response Application Server
• Response Database Server
• WCP Application Server
• WCP Database Server

Deployment Considerations

The MyStudies AWS Terraform Module is designed to deploy the components required to operate a functional test/evaluation MyStudies Application deployment. However, the example configuration does not take into account the requirements that should be considered for an organization to operate a system that collects Personal Health Information (PHI). Organizations planning to deploy MyStudies for PHI use will need to take into account several factors not covered by this example including but not limited to: security, backups, data retention, regulatory compliance requirements, privacy etc.

Deployment Options

• The MyStudies AWS Terraform module allows the MyStudies Administrator to choose options for deployment such as EC2 instance size, data volumes and sizes, and choices to use local or remote (dedicated) database server options. Each of these options can affect the cost of operating the MyStudies environment and care should be taken on how these choices will impact the operating costs of the deployment
• The example MyStudies deployment defaults to storing the Terraform state on the Administrators workstation. Administrators are strongly encouraged to configure the deployment to store the Terraform state in a S3 Bucket. More information about storing Terraform state remotely is available here:
• https://www.terraform.io/language/state/remote

Quick Start

The MyStudies AWS Terraform Module includes a sample deployment example which is configured to deploy an functional application server environment.

Prerequisites

• AWS Account
• AWS IAM User Account with appropriate permissions to deploy AWS resources
• AWS Access Keys for the IAM User and the administrator workstation configured with the AWS Access Keys, Profile and ENV variables
• Administrator computer configured with AWS credentials and Terraform 1.2.x installed
• An existing Route53 DNS domain configured in the target AWS account
• At least one new or existing AWS EC2 Key Pair. Two are recommended - one pair for the bastion host and one pair for the application servers

Quick Start deployment steps

Clone the MyStudies Terraform Module repo to an administrator computer:

git clone https://github.com/FDA-MyStudies/terraform-aws-mystudies.git

CD to the examples/sample-deployment directory:

cd ./terraform-aws-mystudies/examples/sample-deployment

Review and edit the terraform.tfvars configuration file - configuring appropriate values (e.g domain name, key pairs, WCP administrator email addresses etc.)

Deploy the infrastructure with terraform:

terraform init
terraform plan
terraform apply

Terraform will deploy the required resources and application servers, and will start the applications. The system is now ready for administrators to complete the initial configuration and setup. For information on how to complete initial setup follow this guide:

• FDA MyStudies: Technical Setup Document

Clean up - How to remove the deployed environment

cd ./terraform-aws-mystudies/examples/sample-deployment
terraform destroy

Troubleshooting

How to SSH to instances

Example: SSH to MyStudies-Response server:

cd ./terraform-aws-mystudies/examples/sample-deployment
ssh -F ssh_config.txt mystudies-response

Secrets Management

Secrets Management is a component of the MyStudies Terraform Module. Random secrets are generated automatically for database admin, application connections etc. The Module utilizes the AWS Systems-Manager Parameter Store to securely store and retrieve secrets. Should you require access to the application secrets, you may view them in the AWS Systems Manager Parameter Store Web Console.

Partial/Staged Deployment Considerations - Out of order deployment consequences

The MyStudies Module has options to enable/disable each application server and associated RDS server. Administrators should take into consideration that these options are evaluated during initial deployment and have some consequences. For example if you initially choose to use local application databases and later want to use RDS (dedicated database servers) your applications will have been configured to use local databases, and the module does not take into account changing from local to RDS databases in a staged deployment. If you find yourself in that situation you have two options:

• Backup the local database and restore the DB to the RDS database server and manually configure the applications to use the RDS server database connection

• Abandon the local database and application server and redeploy a new application server. To do so, simply terminate the application server in the AWS EC2 console and redeploy with the MyStudies Terraform Module

Related Topics

• FDA MyStudies Infrastructure Deployment Automation
• Deployment Automation with Terraform
• FDA MyStudies: Technical Setup Document

Migration to GitHub

You'll find the source code and more detail here:

• https://github.com/FDA-MyStudies/FDA-My-Studies-Mobile-Application-System

Version 22.3 (March 2022)

• Support for multiple languages.

Version 21.11 (November 2021)

• Spanish language support. The app can present questions in Spanish or English to users. All admin and researcher review of data is in English.

Version 21.3 (March 2021)

• Consent by Legally Authorized Representative (LAR)
• Include "Additional Signature" line in consent document

Version 20.11 (November 2020)

New Features:

• New "MyStudies Coordinator" role lets a user generate and see tokens without full admin permissions

Version 20.3 (March 2020)

New Features:

• Data Sharing Consent flag
• Participant Properties available, keyed on enrollment token

Version 2019.10 (October 2019)

New Features:

• Schedule study activities and resources based on study enrollment (or other WCP-configured date elements) as Anchor Date.
• Support multiple mobile apps from a single instance of the Web Configuration Portal (WCP)
• Ability to include an “other” open-text option in single/multi select questions
• Automatically forward survey responses stored in Response Server to external systems
• Partition user email addresses by folder in the Registration Server

• Compatibility with LabKey Server 19.2.X

Version 2019.05 (May 2019)

New Features:

• Ability to schedule study activities and resources based on study enrollment (or other WCP-configured date elements) as Anchor Date.

• iPhone X, XR, XS
• iOS 11.x and 12.x
• ResearchKit 2.0+
• Android KitKat to Pie
• ResearchSTack 1.1.1
• Compatibility with LabKey Server 19.1.X
• Mutating APIs have been updated to require HTTP POST

Version 2017.01 (January 2017)

• Original features and API

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:

• UserReg-WS

Getting Started

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

• Set Up a LabKey Development Machine

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:

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

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

The FDA MyStudies 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.

Topics

• Web Configuration Portal API: The Web Config Portal services provide access to Gateway, Study and Activities meta data and configurations.
• WCP - Schemas and Structures: Consolidated schema and structures for the Web Configuration Portal (WCP).
• User Registration Server API: User/Registration Services provide mechanisms to register users, manage their profiles, settings, preferences, activity and progress in the app.
• Response Server API: Response services provide ways to enroll participant in a study, submit responses, and fetch responses from the Response Server.

Appendix 1 - Phase 2A Changes Description

WCP Services

The Web Config Portal services provide access to Gateway, Study and Activities meta data and configurations.

• Headers for WCP Services
• GetGatewayAppResourcesInfo
• GetStudyList
• GetStudyBasicInfo
• GetEligibilityConsentMetadata
• GetConsentDocument
• GetResourcesForStudy
• GetStudyInfo
• GetStudyActivityList
• GetStudyActivityMetadata
• GetStudyDashboardInfo
• GetTermsPolicy
• GetNotifications
• GetAppUpdates
• GetStudyUpdates
• GetParticipantProperties

Headers for WCP Services

Request header for all WCP requests:

Response header for all WCP requests:

GetGatewayAppResourcesInfo

Service to get Gateway info and Gateway resources data.

Request:

Response:

[
  {
    "image":string, link
    "title":string,
    "text":string,
    "videoLink":string
  }
]

[
  {
    "resourceId":string,
    "title":string,
    "type":string, html/pdf
    "content":string text/pdf link 
  }
]

GetStudyList

Service to get all the configured studies from the WCP.

Request:

Response:

[
  {
    "studyId":string,
    "studyVersion": string,
    "title":string,
    "category":string,
    "sponsorName":string,
    "tagline":string,
    "status":string, active/upcoming/closed
    "logo":string, link
    "settings": {
      "enrolling":bool,
      "platform":string, ios/android/all
      "rejoin":bool
    }
  }
]

GetStudyBasicInfo

Service to get all the configured studies from the WCP.

Request:

Response:

[
  {
    "studyId":string,
    "studyVersion": string,
    "title":string,
    "category":string,
    "sponsorName":string,
    "tagline":string,
    "status":string, active/upcoming/closed
    "logo":string, link
    "settings": {
      "enrolling":bool,
      "platform":string, ios/android/all
      "rejoin":bool
    }
  }
]

GetEligibilityConsentMetadata

Get eligibility and consent info for the provided study identifier.

Request:

Response:

{
  "type":string, token/test/combined
  "tokenTitle":string,
  "test": [
    <refer to "WCP - Schema and Structures" for step structures>
  ],
  "correctAnswers": [
    {
      "key":string,
      "answer":bool
    }
  ]
}

{
  "version":string,
  "visualScreens": [
    {
      "type":string,
      "title":string,
      "text":string,
      "description":string,
      "html":string,
      "url":string,
      "visualStep":bool
    }
  ],
  "comprehension": {
    "passScore":Integer,
    "questions": [
      {
        <refer to "WCP - Schema and Structures" for step structures>
      }
    ],
    "correctAnswers": [
      {
        "key":string,
        "answer":[string],
        "evaluation":string any/all
      }
    ]
  },
  "sharing": {
    "title":string,
    "text":string,
    "shortDesc":string,
    "longDesc":string,
    "learnMore":string,
    "allowWithoutSharing":bool
  },
  "review": {
    "reasonForConsent":string,
    "reviewHTML":string,
    "consentByLAR":string,
    "additionalSignature":string,
    "signatures":string array
  }
}

GetConsentDocument Get consent document by passing the consent version or the activity id and activity version for the provided studyId.

Request:

Response:

{
  "version": string,
  "type":string, text/html
  "content": string
}

GetResourcesForStudy

Get resources metadata for the provided study identifier.

Request:

Response:

[
{
  "title":string,
  "type":string, html/pdf
  "resourcesId":string,
  "content":string, text/pdf link 
  "audience":string, all/limited
  "availability":{
    "availableDate":string, availability start date
    "expiryDate":string, availability end date
    "startDays":integer, elapsed days from anchor date (positive value) or
 days before anchor date (negative value)
    "endDays":integer,  elapsed days from anchor date (positive value) or
 days before anchor date (negative value)
    "availabilityType": string, Regular/AnchorDate
    "sourceType": string, EnrollmentDate/ActivityResponse/ParticipantProperty
    "propertyMetadata": {
      "propertyType": string, PreEnrollment / PostEnrollment,
      "propertyId": string,
      "propertyDataFormat": string,  
      "shouldRefresh": bool, true/false
      "dataSource": string, ExternalSystem / Other
      "status": string, active / deactivated
      "externalPropertyId": string, 
      "dateOfEntryId": string
    },
    "sourceActivityId":string,
    "sourceKey":string,
    "sourceFormKey": string,
    "startTime": string, HH:mm:ss
    "endTime": string  HH:mm:ss 
  }
}
]

GetStudyInfo

Request:

Response:

[
  {
    "type": string, video
    "image":string, link
    "title":string,
    "text":string, 
    "videoLink":string
  }
]

{
  "type": string, enrollment-date/date-question
  "questionInfo": {
    "activityId":string,
    "activityVersion": string,
    "key": string  question key
  }
}

{
  "type":string, delete_data/ask_user/no_action
  "message":string
}

GetStudyActivityList

Get all the activities in the provided study identifier.

Request:

Response:

[
  {
    "activityId":string,
    "activityVersion":string,
    "title":string,
    "type":string, task/questionnaire
    "startTime": string,
    "endTime": string,
    "branching":bool,
    "lastModified":string,
    "state": string,
    "taskSubType":string, towerOfHonoi/spatialSpanMemory/fetelKick
    "schedulingType": string, Regular/AnchorDate
    "anchorDate": {
      "sourceType": string, EnrollmentDate/ActivityResponse/ParticipantProperty
      "sourceActivityId": string, activityId
      "sourceKey": string, question Key
      "sourceFormKey": string,
      "propertyMetadata": {
        "propertyId":string,
        "propertyType": string, PreEnrollment / PostEnrollment
        "propertyDataFormat": string,  
        "shouldRefresh": bool, //true/false
        "dataSource": string, ExternalSystem / Other
        "status": string, active / deactivated,
        "externalPropertyId": string, 
        "dateOfEntryId": string
      },
      "start": {
        "anchorDays": integer,
	"time": string  HH:mm:ss
      },
      "end": {
        "anchorDays": integer,
	"repeatInterval": integer,
	"time": string  HH:mm:ss
      }
    }
    "frequency": 
      {
      "type":string,
      "addNewRuns": bool,
      "runs":  Array of runs for within a day and manual type
        [
        {
          "startTime":string,
          "endTime":string
        }
        ]
      }
      "anchorRuns": [{
        "startDays": integer,
        "endDays": integer,
        "time": string  HH:mm:ss
      }]
    }
]

GetStudyActivityMetadata

Get the activity metadata for provided study and activity identifier.

Request:

Response:

{
  "type": string, task/questionnaire
  "metadata": 
  {
    "studyId":string,
    "activityId":string,
    "version":string,
    "name":string,
    "lastModified":string,
    "startDate":string,
    "endDate":string
  }
  "steps": [
    {
      <refer to "link" href="/FDAMyStudiesHelp/wiki-page.view?name=wcpSchemas">Schema and Structure for step structures>
    }
  ]
}

GetStudyDashboardInfo

Get dashboard metadata for the provided study identifier.

Request:

Response:

{
  "statistics":[
    {
      "title":string,
      "displayName":string,
      "statType":string,
      "unit":string,
      "calculation":string,
      "dataSource": 
      {
        "type":string, questionnaire/active task
        "key":string, step key
        "activity": {
          "activityId": string,
          "version": string
        }
      }
    }
  ],
  "charts":[
    {
      "title":string,
      "displayName":string,
      "type":string,
      "scrollable": bool,
      "configuration": {
        "subType": string,
        "settings": [
          {
            "barColor": string
          }
        ]
      },
      "dataSource":
        {
          "type":string, questionnaire/active task
          "key":string, step key
          "activity": {
            "activityId": string,
            "version": string
          }
          "timeRangeType":string, days_of_week/days_of_month/weeks_of_month/months_of_year/runs
          "startTime":string,
          "endTime":string
        }
    }
  ]
}

GetTermsPolicy

Get terms and policy for the provided study identifier.

Request:

Response:

GetNotifications

Fetch available notifications.

Request:

Response:

[
  "notificationId":string,
  "type":string,
  "subtype":string,
  "studyId":string,
  "audience":string,
  "title":string,
  "message":string,
  "date":string
]

GetAppUpdates

Check for app updates

Request:

Response:

{
  "latestVersion": string,
  "forceUpdate": string
}

{
  "latestVersion": string,
  "forceUpdate": string
}

GetStudyUpdates

Request:

Response:

{
  "consent":bool,
  "activities": bool,
  "resources": bool,
  "info": bool,
  "status": string
}

GetParticipantProperties

Get list of ParticipantProperties for the study

Request:

Response:

{
  "studyId":string,
  "studyVersion": string
}

[
  {
    "propertyId": string,
    "propertyName": string,
    "propertyType": string,
    "propertyDataType": string,
    "shouldRefresh": bool,
    "dataSource": string,
    "status": string,
    "version": string
   }
]

Related Topics

• WCP - Schemas and Structures
• Mobile Client API
• User Registration Server API
• Response Server API

This document covers the consolidated schema and structures for the Web Configuration Portal (WCP).

• Updates
• Steps
• Instruction Step
• Question Step
• Form Step
• Active Task Step
• Activity
• Questionnaire
• ActiveTask

Updates

Mar 20,2019 v1.7

• Added “other” in Question Step of multiple choice

Nov 20,2017 v1.6

• Added “operator” in Question Step for each destination
• Added “kickCount” for Fetel Kick Active Task Format
• Added “dateRange” for Date Type Question Format

Mar 16, 2017 v1.5

• Expanded text choices array for text scale, text choices and value pickers.

Mar 5, 2017 v1.4

• Added Destinations structure for question step
• Updated Form Step result structure. It is array of array(iterations) of question results.
• Removed configuration from the activity metadata.

Feb 22, 2017 v1.3

• Added TowerOfHanoi and SpatialSpanMemory in supported active task types.
• Updated Active Task type to ‘task’ from ‘activeTask’

Feb 16, 2017 v1.2

• Changed Active Task Step result to “grouped” result
• Added activityRunId to activity result metadata

Feb 09, 2017 v1.1

• Changed ‘info’ to ‘metadata’ in Activity Metadata Structures
• Changed ‘response’ to ‘data’ in Activity Result Structures
• Changed ‘description’ to ‘text’ in Active Task Step

Feb 08, 2017 v1.0

• Consolidated schema and structure document

Steps

• Instruction Step
• Question Step
• Form Step
• Active Task Step

Instruction Step

Question Step

[
  {
    "condition": string,  default for no condition
    "destination": string,  completion for last 
    "operator": string  e/gt/lt/gte/lte/range/ne for formula based branching
  }
]

QuestionResultType:

• scale
• continuousScale
• textScale
• valuePicker
• imageChoice
• textChoice
• boolean
• numeric
• timeOfDay
• date
• text
• email
• timeInterval
• height
• location

• Scale
• "maxValue" - Int; Max:10000
• "minValue" - Int; Min:-10000
• "default" - Int
• "step" - Int; Min:1, Max:13
• "vertical" - Bool
• "maxDesc" - String
• "minDesc" - String
• "maxImage" - Image
• "minImage" - Image
• ContinuousScale
• "maxValue" - Number
• "minValue" - Number
• "default" - Number
• "maxFractionDigits" - Integer
• "vertical" - Bool
• "maxDesc" - String
• "minDesc" - String
• "maxImage" - Image
• "minImage" - Image
• TextScale
• "textChoices" -

  [ 
    {
        "text": string,
        "value": string,
        "detail": string, nil 
        "exclusive": bool  true
    }
  ]; Min:2, Max:8

• "default" - Int
• "vertical" - Bool
• ValuePicker
• "textChoices" -

  [ 
    {
      "text": string,
      "value": string,
      "detail": string,  nil 
      "exclusive": bool, true
    }
  ];

• ImageChoice
• "imageChoices" -

  [
    {
      "image": string,
      "selectedImage": string,
      "text": string,
      "value": string
    }
  ];  Image Size 45px-60px

• TextChoice
• "textChoices" -

  [ 
    {
      "text": string,
      "value": string,
      "detail": string, nil
      "exclusive"	: bool,
      "other": {
        "placeholder": string,
        "isMandatory": bool,
        "textfieldReq": bool
      }
    }
  ];

• "selectionStyle" - String; Single/Multiple
• Numeric
• "style" - String; Integer/Decimal
• "unit" - String
• "minValue" - Number
• "maxValue" - Number
• "placeholder" - String
• Date
• "style" - String; Date/Date-Time;
• "minDate" - Date; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "maxDate" - Date; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "default" - Date
• “dateRange” - String; (untilCurrent/afterCurrent/custom)
• Text
• "maxLength" - Int; =0 -> No max length
• "validationRegex" - String
• "invalidMessage" - String
• "multipleLines" - Bool
• "placeholder" - String
• Email
• "placeholder" - String
• TimeInterval
• "default" - Number
• "step" - Integer; In minutes 1-30
• Height
• "measurementSystem" - String; Local/Metric/US
• "placeholder" - String
• Location
• "useCurrentLocation" - Bool

Question Result:

• "resultType" - String; QuestionResultType
• "key" - String
• "startTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "endTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "skipped" - Boolean
• "value" - ResultFormat

• Scale
• "value" - Double
• ContinuousScale
• "value" - Double
• TextScale
• "value" - String
• ValuePicker
• "value" - String
• ImageChoice
• "value" - String
• TextChoice
• "value" - [String]
• Boolean
• "value" - Boolean
• Numeric
• "value" - Double
• TimeOfDay
• "value" - String; "HH:mm:ss"
• Date
• "value" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• Text
• "value" - String
• Email
• "value" - String
• TimeInterval
• "value" - Double
• Height
• "value" - Double
• Location
• "value" - String; (lat,long)

Form Step

Form Result:

• "resultType" - String; "grouped"
• "key" - String
• "startTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "endTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "skipped" - Boolean
• "value" - [[QuestionResult]] Array of number of iterations of Q-results

Active Task Step

ActiveTaskType:

• fetalKickCounter
• spatialSpanMemory
• towerOfHanoi

• excludeInstructions
• excludeConclusion
• excludeAccelerometer
• excludeDeviceMotion
• excludePedometer
• excludeLocation
• excludeHeartRate
• excludeAudio

• FetalKickCounter
• "duration" - Number; in hours
• “kickCount” - Number
• SpatialSpanMemory
• “initialSpan” - Integer
• “minimumSpan” - Integer
• “maximumSpan” - Integer
• “playSpeed” - Integer
• “maximumTests” - Integer
• “maximumConsecutiveFailures” - Integer
• “customTargetImage” - Image
• “customTargetPluralName” - String
• “requireReversal” - Bool
• TowerOfHanoi
• "numberOfDisks" - Integer;

• "resultType" - String; ActiveTaskType (“grouped”)
• "key" - String
• "startTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "endTime" - String; "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
• "value" - ActiveTaskResult

• FetalKickCounter

  [
    {
      "resultType": string,  numeric
      "key": string,  duration
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": double
    } ,
    { 
      "resultType": string,  numeric
      "key": string,  count
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": double
    }
  ]

• SpatialSpanMemory

  [
    {
      "resultType": string,  numeric
      "key": string,  score
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": Integer
    } ,
    {
      "resultType": string,  numeric
      "key": string,  number of games
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": Integer
    },
    {
      "resultType": string,  numeric
      "key": string,  number of failures
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": Integer
    }
  ]

• TowerOfHanoi

  [
    {
      "resultType": string,  numeric
      "key": string,  puzzle was solved
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": bool
    } ,
    {
      "resultType": string,  numeric
      "key": string,  number of moves
      "startTime": string, null
      "endTime": string, null
      "skipped": bool, false
      "value": Integer
    }
  ]

Activity

• Questionnaire
• ActiveTask

Questionnaire

{
  "studyId": string,
  "activityId": string,
  "name": string,
  "version": string,
  "lastModified": string,
  "startDate": string,
  "endDate": string
}

Questionnaire Result:

• "type" - String; "questionnaire"
• "metadata" - Dictionary;

  {
    "studyId": string,
    "activityId": string,
    "version": string,
    "activityRunId": string
  },

• "participantId" - String
• "data" - Dictionary;

  {
    "startTime": string,
    "endTime": string,
    "results": [StepResult]
  }

Active Task

{
  "studyId": string,
  "activityId": string,
  "name": string,
  "version": string,
  "lastModified": string,
  "startDate": string,
  "endDate": string
}

Active Task Result:

• "type" - String; "task"
• "metadata" - Dictionary;

  {
    "studyId" string,
    "activityId" string,
    "version" string,
    "activityRunId" string
  },

• "participantId" - String
• "data" - Dictionary;

  {
    "startTime": string,
    "endTime": string,
    "results": [StepResult]
  }

Related Topics

• Mobile Client API
• Web Configuration Portal API

User/Registration Services

User/Registration Services provide mechanisms to register users, manage their profiles, settings, preferences, activity and progress in the app.

• Headers for User/Registration Services
• RegisterUser
• ConfirmRegistration
• ResendConfirmation
• LoginUser
• LogoutUser
• ForgotPassword
• ChangePassword
• GetUserProfile
• UpdateUserProfile
• GetStudyState
• UpdateStudyState
• UpdateEligibilityConsentStatus
• GetConsentDocument
• UpdateActivityState
• GetActivityState
• WithdrawFromStudy
• Deactivate Account
• Feedback
• ContactUs
• Refresh Token
• Send Notifications
• App Properties
• Appendix - Email Body

Headers for User/Registration Services

Request header for all user/registration requests (auth and userId is not required for login/registration/forgot password)

Response header for all user/registration requests

RegisterUser

Register new user.

Request:

Response:

ConfirmRegistration

Confirm user registration.

Request:

Response:

ResendConfirmation

Resend confirmation email.

Request:

Response:

LoginUser

Login user.

Request:

Response:

LogoutUser

Logout user.

Request:

Response:

ForgotPassword

Request to reset password.

Request:

Response:

ChangePassword

Request to change password.

Request:

Response:

GetUserProfile

Request:

Response:

{
  "emailId": string
}

{
  "remoteNotifications": bool,
  "localNotifications" :bool,
  "touchId" :bool,
  "passcode" :bool,
  "locale" :string,
  "reminderLeadTime": string
}

UpdateUserProfile

Update user profile on server.

Request:

{
  "remoteNotifications": bool,
  "localNotifications": bool,
  "touchId": bool,
  "passcode": bool,
  "reminderLeadTime" :string,
  "locale": string
}

{
  "os": string, android/ios
  "appVersion": string,
  "deviceToken": string
}

{
  "studyId": string,
  "participantId": string,
  "enrolledDate": string
}

Response:

GetStudyState

Request:

Response:

[
  {
    "studyId": string,
    "status": string,
    "enrolledDate": string,
    "participantId": string,
    "bookmarked": bool,
    "completion": integer,
    "adherence": integer,
  }
]

UpdateStudyState

Update study state

Request:

[
  {
    "studyId": string,
    "status": string,
    "enrolledDate": string,
    "participantId": string,
    "bookmarked": bool,
    "completion": integer,
    "adherence": integer
  }
]

Response:

UpdateEligibilityConsentStatus

Update eligibility and consent status.

Request:

{
  "version": string,  consent version
  "status": string,  completed/pending
  "pdf": string   base-64 encoded string
}

Response:

GetConsentDocument

Download consent PDF from server by passing studyId and consent version. If no consent version is provided, latest version of consent should be returned.

LabKey will also use this service, in that case, user id in header params should be treated as app token/participant id.

Request:

Response:

{
  "version":string,  consent version
  "type": string,  application/pdf
  "content": string  base-64 encoded string
}

UpdateActivityState

Update activity state.

Request:

[
  {
    "activityId": string,  activity identifier
    "activityVersion": string, activity version
    "activityRunId": string, activity run identifier
    "activityState": string, activity state
    "bookmarked": bool,
    "activityStartDate": string,
    "activityEndDate": string,
    "anchorDateVersion": string,
    "anchorDatecreatedDate": "string",
    "lastModifiedDate": string,
    "customScheduleRuns": [{
        "runStartDate": string,
	"runEndDate": string
    }],
    "activityRun": {
        "total" :integer,
        "completed" :integer,
        "missed" :integer
    }
  }
]

Response:

GetActivityState

Fetch activity state.

Request:

Response:

[
  {
    "activityId": string,
    "activityVersion": string,
    "activityRunId": string,
    "activityState": string,  activity state
    "bookmarked": bool,
    "activityStartDate": string,
    "activityEndDate": string,
    "anchorDateVersion": string,
    "lastModifiedDate": string,
    "anchorDatecreatedDate": string,
    "customScheduleRuns": [{
	"runStartDate": string,
	"runEndDate": string
    }],
    "activityRun": {
        "total":integer,
        "completed":integer,
        "missed":integer
    }
  }
]

WithdrawFromStudy

Request:

Response:

Deactivate Account

Request:

Response:

Feedback

Provide feedback about the app.

Request:

Response:

ContactUs

Request:

Response:

Refresh Token

Get new accesstoken and refreshtoken.

Request:

Response:

Send Notification

For sending notifications.

Request:

[
    {
         "customStudyId": string,
         "notificationText": string,
         "notificationTitle": string,
         "notificationType": string,
         "notificationSubType": string
      }
]

Response:

App Properties

Request:

Response:

Appendix - Email Body

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

Register Email Body

Email subject for signup mail, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

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

Forgot Password Email Body

Email Body for Password Help email, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

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

Related Topics

• Mobile Client API
• Web Configuration Portal API
• WCP - Schemas and Structures
• Response Server API

• Response Services
• Enroll
• ValidateEnrollmentToken
• ProcessResponse
• WithdrawFromStudy
• ResolveEnrollmentToken
• Query APIs
• executeSql
• selectRows
• Query Example: Get Participant Response
• Examples
• On Success
• On Error
• Error Cases
• Participant Properties
• Multiple Language Support

Response Services - API Details

Response services provide ways to enroll participant in a study, submit responses, and fetch responses from the Response Server.

Enroll

Enrolls a participant in a study on the server. The response includes a globally unique participantId (as "appToken" or <application-token>). This participantId is used in subsequent communication with the mobile app.

Request:

Response:

{
  "appToken": string (the participant ID)
}

[
  {
    "msg": string,
    "field": string,
    "id": string, token,
    "message": string,
    "severity": string
  }
]

Afterwards, all submissions to the server are done using the participantID (returned as the "appToken").

ValidateEnrollmentToken

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

Request:

Response:

[
  {
    "msg": string,
    "field": string,
    "id": string, token
    "message": string,
    "severity":string
  }
]

ProcessResponse

Saves survey responses from an activity to the study. No parameters in the URL string, but the JSON object provided in the POST body contains the participantId.

Request:

{ 
  "type": string, questionnaire or activetask 
  "metadata": dictionary; activity info
    { 
      "studyId": string, study identifier 
      "activityId": string, activity identifier
      "name": string, activity name
      "version": string, activity version
      "activityRunId":string  run id for the activity
    }
  "participantId": string, participant identifier
  "data": dictionary; activity info
    {
      "startTime": string, start time of activity
      "endTime": string, end time of activity
      "resultType": string;,
      "results": array  results of each step in activity <refer to the "WCP - Schemas and Structures" topic>>
    }
}

Details of the results array contents can be found here: WCP - Schemas and Structures

Response:

WithdrawFromStudy

Withdraw (un-enroll) a participant from a study. Option to retain or delete data.

Request:

Response:

Resolve Enrollment Token

This API is used to search the study using enrollment token. Given 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.

Request:

Response:

Query APIs

Two LabKey Query APIs are important when working with MyStudies. Both employ special authentication and filtering to just the current participant. Learn more here:

• Querying the Response Server
• selectRows
• executeSql

Query Example: Get Participant Response

To fetch responses for a provided question, activity and study identifiers, you can use LabKey’s executeSQL api.

Request:

Response: Depending on sql query, response varies.

Examples

Example URLs to invoke:

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

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

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

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

On Success

{
    "success" : true
    "data" : 
    {               
        "appToken" : string, participantId
    }
}

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

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

On Error

{  
    "exception" : string,  message
    "success" : false,
    "errors" : [  
        {  
            "msg" : string,  message,
            "field" : string,  form/studyId/token
            "id" : string,  form/studyId/token",
            "message" : string   message
        }
    ]
}

As an example, an invalid enrollment token might generate:

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

Error Cases

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:

Multiple Language Support

Studies may be configured to support user-facing communication in multiple languages. At present, English is the default and Spanish language is also supported.

Note that all administrative actions for setting up the study and resources for researchers/data analysts will be presented in English. The multiple language support applies only to the information and messages shown to the user of the mobile app.

The Response Server collects free-text responses as entered by the participant. The response JSON includes an optional language property in the metadata. This gets parsed, translated into a friendly name, and saved in a new column in the Response table. Language codes and names are sourced from

• https://developer.box.com/guides/api-calls/language-codes/

• English: Token is required.
• Spanish: Se requiere un token.

Related Topics

• Querying the Response Server
• Survey Designs and Responses
• Testing the Response Server
• Data Sharing Consent
• Mobile Client API
• User Registration Server API
• Web Configuration Portal API
• WCP - Schemas and Structures

• Survey Designs
• Survey Response Documents
• Survey Questions
• Using the "Other" Option
• Submitting Survey Responses to the Server

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.

• Survey Design Schema v2.4: surveyDesignSchema_v2.4.json

Example

• Example survey design v.2.3 : InitialSurveyDesign_v2.3.json
• the JSON schema to which it conforms: surveyDesignSchema_v2.3.json

Survey Response Documents

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

• Survey Response Schema v2.3: surveyResponseSchema_v2.3.json

Example

• Example survey response document: InitialSurvey_v2.2.1.json
• the JSON schema to which it conforms: surveyResponseSchema_v2.2.json

Survey Questions

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

• Electronic Data Capture (EDC)

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.

"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

• Mobile Client API
• Testing the Response Server

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

• Mobile Client API

• Assumptions
• Set Up a Test Environment
• Test Enrollment
• Test Data Submission
• Withdraw from a Study
• Troubleshooting

Assumptions

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

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

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

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

https://<server>/response-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.

https://<server>/query-APITest.view

• In Post URL enter an URL like the following:

https://<server>/response-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

When testing is completed, you may wish to delete the test data from the tables so that it is not mixed in with future participant response data. When a participant withdraws from the study, their data will be deleted.

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.

https://<server>/response-withdrawFromStudy.api?delete=TRUE&participantId=<appToken>

Withdrawing from a study is available in the app inself under Resources > Leave Study.

Troubleshooting

If your test does not produce a 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.

• Select (Admin) > Site > Admin Console.
• Click View Site Errors Since Reset or View All Site Errors.
• Search from the bottom for the most recent errors and warnings.

Incorrect Module Properties: MetadataServiceBaseUrl

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.

Incorrect Module Properties: MetadataServiceAccessToken

Error: If you see an error with Response status 401 and a correct-looking path for results including the studyId, like:

https://SERVER_NAME/StudyMetaData/participantProperties?studyId=STUDYID_001"

Solution: Check the module property "MetadataServiceAccessToken" to confirm that it did NOT inadvertently get set to the AppId or StudyId. This property should only have a site-level setting that is an apparently random long string.

Related Topics

• Examples: Controller Actions

• Parsing and Processing
• Reprocessing
• Editing
• Processed Data and Dynamic List Creation
• Response Forwarding

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.

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

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.

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

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

Related Topics

• Data Grids
• 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

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

http://<server>/response-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.

http://myserver.com/response-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>.

• sql
• participantId

http://<server>/response-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.

http://myserver.com/response-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:

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

Related Topics

• Proactively create schema before Responses are received

Reference

Learn more in the GitHub documentation here:

• Query.selectRows
• Query.executeSql

• Mobile App Quick Overview for Research
• MyStudies on iOS
• User Registration Server Set Up
• Web Configuration Portal Set Up
• Response Server: Get a Distribution - Build a standalone distribution of the Response Server (i.e., a standard LabKey Server distribution plus the Response module).