Mobile Client API: /FDAMyStudiesHelp

Mobile Client API

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.

Methods
Examples

On Success
On Error

Error Cases
Participant Properties

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

Methods

Method Name	Description
enroll	Enrolls 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>.
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. Parameters: -- Same params as enroll above.
resolveEnrollmentToken	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. Parameters: -- token (required) - Enrollment token provided by the participant.
withdrawFromStudy	Un-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.
processResponse	Saves 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:

Message	Field	Cause
Invalid input format	form	The data provided in the API could not be deserialized properly.
StudyId is required for enrollment	form	Empty or no studyId provided.
Study with studyId "XXX" does not exist	studyId	Invalid studyId provided.
Token already in use	form	The provided token already has a participant id associated with it in the study's container.
Invalid token: "YYY"	token	The checksum for the token is incorrect.
Unknown token: "ZZZ"	token	The token provided has a valid checksum but it is not associated with the given studyId.
Token is not associated with a study ID	token	There is no study associated with the submitted token.
Token is required	form	The 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:

Attribute	type/values	Description
propertyId	string	A unique identifier under study for participant property.
propertyName	string	A user friendly name for participant property. eg: Date Of Appointment.
propertyType	PreEnrollment/PostEnrollment	This defines what type of participant property it is.
propertyDataType	string	The type of the property (string, boolean, etc)
shouldRefresh	boolean	Whether to refresh participant property value periodically or not.
dataSource	ExternalSystem/Other	Defines from where the value will be populated.
status	active/deactivated	Status of participant property
value	depends on type	value of participant property sent by external system

LabKey Support

LabKey Support