Response Server API

2021-06-12

This topic is under construction.

LabKey's mobile client API provides enrollment services and data storage for mobile phone client applications. Participants, using a mobile application, can request enrollment in a study, withdraw from a study, and optionally, have their data deleted upon un-enrollment.

Survey responses are stored in dynamically generated tables on the server.

Upgrade note: In earlier versions, the controller name "mobileAppStudy" was used. This has been changed to "response" as of release 21.3 (March 2021). The old name will still work, but should be updated for future releases.

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:

MethodURL
POST/response-enroll.api

ParametersTypeValues/Description
studyId (required)stringstudy identifier: A pre-existing study on the server.
token (required)stringenrollmentToken: Enrollment token string provided by the participant. Token validation is case-insensitive. The token is used only once for enrollment; previously enrolled tokens cannot be used again.
allowDataSharing (required)stringWhether the participant consents to sharing data with third parties. Valid values: "true", "false", "NA"

Response:

ParamsValues
successboolean
exceptionstring;
data
{
"appToken": string (the participant ID)
}
errors
[
{
"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:

MethodURL
GET/response-validateEnrollmentToken.api

ParamsTypeValues/Description
studyId (required)stringstudy identifier: A pre-existing study on the server.
token (required)stringenrollmentToken: Enrollment token string provided by the participant. Token validation is case-insensitive. The token is used only once for enrollment; previously enrolled tokens cannot be used again.

Response:

ParamsValues
successboolean; false
exceptionstring;
errors
[
{
"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:

MethodURL
POST/response-processResponse.api

ParamsValues
response
{ 
"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:

ParamsValues
successboolean

WithdrawFromStudy

Withdraw (un-enroll) a participant from a study. Option to retain or delete data.

Request:

MethodURL
POST/withdrawFromStudy.api

ParamsTypeValues/Description
participantId (required)stringparticipant identifier; The "appToken" value returned at enrollment.
delete (optional)booleanOptional boolean to delete the withdrawn participant's response data. Defaults to FALSE.

Response:

ParamsValues
exceptionstring
successboolean
statusstring

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:

MethodURL
POST/response-resolveEnrollmentToken.api

ParameterTypeValues
token (required)stringEnrollment token provided by the participant.

Response:

ParamsValues
exceptionstring

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 in the GitHub documentation here:

Query Example: Get Participant Response

To fetch responses for a provided question, activity and study identifiers, you can use LabKey’s executeSQL api.

Request:

MethodURL
POST/response-executeSQL

ParameterTypeValues/Description
sqlstringquery to retrieve response
participantIdstring 

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.)

Note that prior versions of this API used the controller name "mobileAppStudy" where you see "response" in the above examples.

On Success

When an action is successful, the server responds with a JSON object with the following format.
{
"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

Error responses have the following format:
{  
"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

The following error cases are handled:
MessageFieldCause
Invalid input formatformThe data provided in the API could not be deserialized properly.
StudyId is required for enrollmentformEmpty or no studyId provided.
Study with studyId "XXX" does not existstudyIdInvalid studyId provided.
Token already in useformThe provided token already has a participant id associated with it in the study's container.
Invalid token: "YYY"tokenThe checksum for the token is incorrect.
Unknown token: "ZZZ"tokenThe token provided has a valid checksum but it is not associated with the given studyId.
Token is not associated with a study IDtokenThere is no study associated with the submitted token.
Token is requiredformThe study associated with the given studyId requires an enrollment token to be provided.

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:

Attributetype/valuesDescription
propertyIdstringA unique identifier under study for participant property.
propertyNamestringA user friendly name for participant property. eg: Date Of Appointment.
propertyTypePreEnrollment/PostEnrollmentThis defines what type of participant property it is.
propertyDataTypestringThe type of the property (string, boolean, etc)
shouldRefreshbooleanWhether to refresh participant property value periodically or not.
dataSourceExternalSystem/OtherDefines from where the value will be populated.
statusactive/deactivatedStatus of participant property
valuedepends on typevalue of participant property sent by external system

Related Topics