• 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