Provisioning a new study

Sage Bionetworks Policies for Study Creation

Studies provisioned to support clinical studies may only be created under the direction of the Director of Technology Services.  Prior to creating a new study in Bridge Server, the Director will review the contract and SOW describing Sage's role in the study with Sage's President and any other Leadership Team members involved in the project.  The study will not be configured to allow participants to start using the service until the contract is in place, and Sage's data governance team has reviewed and approved the study.

Bridge Server engineers may create studies as needed for test purposes, as long as they do not contain any data produced from sources other than the Bridge Server or internal App engineering teams.

Engineering Process for Provisioning the Study

To provision a new study you must have administration credentials for the Bridge account with Stormpath, Amazon AWS, and an admin account in the Bridge API study (available in every environment). Your admin credentials are assumed to be set in your bridge-sdk.properties file in the example below.

First, using the Java SDK, create the basic information for a new study. It will not have any users but it will have basic defaults for subpopulations, consents, email templates and the like. For example:

NOTE: This code is out-of-date with the most recent REST SDK.

public class CreateStudy {
    public static void main(String[] args) {
        Config config = ClientProvider.getConfig();
        config.set(Environment.PRODUCTION);
        config.set(Props.STUDY_IDENTIFIER, "api");
        
        Session session = ClientProvider.signIn(config.getAdminCredentials());
        AdminClient client = session.getAdminClient();        
 
        Study study = new Study();
        study.setIdentifier("new-study-identifier");
        study.setName("New Study Name");
        study.setSponsorName("New Study Sponsor");
        study.setSupportEmail("email@sponsor.org");
        study.setConsentNotificationEmail("email@sponsor.org");
        study.setTechnicalEmail("email@sponsor.org");
        client.createStudy(study);
        session.signOut();
    }
}

This will create the study in the specified environment.

In Amazon AWS you will need to go into SES and add the support email address to the list of verified email addresses, because study emails will be sent using that email address. The recipient of that address will get a request from Amazon to confirm the address can be used to send email on their behalf.

Now sign in to the Stormpath UI (https://enterprise.stormpath.io/login) and navigate to the list of Stormpath directories. The study will have its own directory, named something like "new-study-identifier (prod)" (given the identifier above). Go into that study and create some developer accounts for the study developers.

Creating these accounts is straightforward but be sure to assign the "developer" and/or "researcher" groups to the accounts, as needed (we directly map our application roles to Stormpath's groups). Do not assign the "admin" group to study developers: this is for Sage administrators only.

Finally, In the current Stormpath UI, there is a way to select these accounts and send reset password emails to all the accounts in bulk. In practice you might need to contact users to notify them this will be coming before they receive it, or it can be confusing. At that point, they should be able to sign in to the researcher UI at https://research.sagebridge.org and fill out their study configuration.

Lab Studies

For studies conducted entirely in the lab, there are some additional considerations. 

1. Studies are created with a required, default consent. This should be toggled to no longer be required. Users of the API will never receive a 412 (consent required) response;
2. Email verification should be turned off. The email addresses created for credentials will not be end-user email addresses, and the study is not public, so this is not needed;
3. Enable Bridge management of external IDs. Now credentials can only be created with an external ID that will be used as the code to "register" an app with the study.

In the Bridge Study Manager, by default, a study in this state will have a "Lab Codes" section in navigation. There you can add the codes you want to enter into the phones. These will be added along with credentials.

Right now, we expect the following pattern. Let's say you want a researcher to enter the code "AX019" into the phone, and the support email for the study is support@study.com. When you add this under Lab Codes:

• The external ID "AX019" is added to Bridge. It'll be exported with all data sent from the phone registered with this code.
• A pair of credentials is created, with an email of support+AX019@study.com, and a password of AX019
• The app developer will build a UI that accepts a code, and uses the generated email and password values to sign in the device.
• In the lab, a researcher enters this code into a device, probably noting the subject who received the phone and thus, has been assigned this code.

For this reason, the codes you select for a lab study should be as secure as a good password, because they are used to authenticate with a public API.

Adding Push Notification Support

You will need to manually configure SNS for mobile push notification support. For each platform, you will create an Application in the SNS console, that generates what is called a platformARN. The process to do this is complicated, see http://docs.aws.amazon.com/sns/latest/dg/SNSMobilePush.html for explanations of how to set up the six different push notification systems that currently exist. Depending on the platform you will need to register the client application with the notification service, and copy various keys, certificates, and so forth to SNS.

When you create this, please follow this naming convention: "{studyIdentifier}-{environment: local, dev, staging, prod}". So we can find the endpoint later. If that's not unqiue, add the platform as well, either "-android" or "-ios" to the name.

As currently implemented, we only have support for Android and iOS. If we were to support Amazon Fire, we would need to introduce it as another platform, because although it is based on Android, it has been forked, and has a separate notification service.

Then, in the researcher UI under "Push Notifications > Settings", enter the ARN for this application for the given platform. Save the study.