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

Methods

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

{
    "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

{  
    "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

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:

Related Topics

• Survey Designs and Responses
• Testing the Response Server
• Data Sharing Consent