Mobile Client API

FDA MyStudies Help
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.

Methods

Method NameDescription
enrollEnrolls a participant in a study on the server. The response includes a globally unique <application-token>; to be used in subsequent communication from the mobile app.

Parameters:
-- studyId (required) - A pre-existing study on the server.
-- token (required) - 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) - Whether the participant consents to sharing data with third parties. Valid values: "true", "false", "NA"

Afterwards, all submissions to the server are done using the <application-token>.
validateEnrollmentTokenValidates 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.

Parameters:
-- Same params as enroll above.
resolveEnrollmentTokenGiven 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.

Parameters:
-- token (required) - Enrollment token provided by the participant.
withdrawFromStudyUn-enrolls a participant. Option to retain or delete data.

Parameters:
-- participantId (required) - The <application-token> provided upon enrollment success.
-- delete - Optional boolean to delete the withdrawn participant's data. Defaults to FALSE.
processResponseSaves survey responses to the study.

Parameters:
-- No parameters in the URL string, but the JSON object provided in the POST body contains the <application-token>.

Examples

Example URLs to invoke:

http://localhost:8080/mobileappstudy-enroll.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA

http://localhost:8080/mobileappstudy-validateEnrollmentToken.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA

http://localhost:8080/mobileappstudy-withdrawFromStudy.api?participantId=<app-token>&delete=<boolean>

http://localhost:8080/mobileappstudy-processResponse.api? (The <app-token> is provided in the posted JSON body.)

On Success

When an action is successful, the server responds with a JSON object with the following format.
{
"success" : true
"data" :
{
"appToken" : "<app-token>",
}
}

In the case of validateEnrollmentToken, pre-enrollment properties will be returned.

{
"success": true,
"data": {
"preEnrollmentParticipantProperties": [
{
"propertyId": "ExternalConsentStatus",
"value": "Fully Consented"
}, {
"propertyId": "Cohort",
"value": "Traditional Diet"
}
]
}
}

On Error

Error responses have the following format:
{  
"exception" : "<message>",
"success" : false,
"errors" : [
{
"msg" : "<message>",
"field" : "form|studyId|token",
"id" : "form|studyId|token",
"message" : "<message>"
}
]
}

As an example, an invalid enrollment token might generate:

{
"success": false,
"exception": "InvalidToken",
"errors": [{
"message": "Invalid token supplied",
"field": "EnrollmentToken",
"id": "abcd1234"
}]
}

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