This topic describes the older interface for configuring the Response Server. If your new Response Server study folder shows a Study Setup web part, follow this topic. If the web part is My Studies Response Server, STOP and use the current topic: 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
• Set Study ID
• Update Metadata
• 7.5 Generate Tokens
• 7.6 Set Module Properties
• 7.7 Enrollment Test

Each data partner owns a project on LabKey Server, and each study resides in a different subfolder of the parent project. After a participant completes a survey, the mobile application sends the response to the server where it is stored in the appropriate study subfolder.

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

Create a Project

A site administrator can create a new project.

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

Create a Subfolder

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

Assign Permission Roles to Users

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

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

Permissions are assigned for each container (project or folder) and can be inherited in subfolders. To assign permissions for a folder, select (Admin) > Folder > Permissions. Add users (or project groups of users) to the desired roles.

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

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

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.

Once tokens have been generated, the admin can review each batch, see at a glance how many were generated, how many have been used, and open each batch to find available tokens for distribution.

Set Module Properties

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

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

If the last two parameters are not configured, the SurveyMetadataDirectory will be used to find the metadata file. If none of the parameters are configured, an error will be generated. The name of the survey metadata file in the SurveyMetadataDirectory should be of the form <studyId>_<activityId>_<version>.txt.

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

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

Enrollment Test

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

Related Topics

• Testing the Response Server
• Mobile Client API