Testing the Response Server

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

Assumptions

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

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

Set Up a Test Environment

To set up a testing environment:

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

Test Enrollment

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

Test Data Submission

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

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

Withdraw From a Study

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

Troubleshooting

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

Incorrect Module Properties

Error: If you see an Error Message similar to

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

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

Related Topics