This topic explains how to set up the response server to begin collecting data from the mobile apps.
Each data partner owns a project on LabKey Server, and each study resides in a different subfolder of the parent project. After a participant completes a survey, the mobile application sends the response to the server where it is stored in the appropriate study subfolder.
Enrollment is accomplished by the use of enrollment tokens
. A set of enrollment tokens are generated for a given study and distributed to prospective participants as tickets for enrollment in that study. Upon successful enrollment, the server provides the mobile client with a globally unique application token
, which the server uses to identify the appropriate study folder and participant on all subsequence communications.
Create a Project
- 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.
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.
The data partners distribute enrollment tokens to potential participants. The following explains how to generate tokens for distribution.
Each study container generates its own enrollment tokens. 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 Batch click New Batch.
- 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:
- 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.
- 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):
To test your set up, enroll (and unenroll) a fictional participant, see Testing the Response Server