bridge-client/org.sagebionetworks.bridge.kmm.shared.models

Package-level declarations

Model objects for Bridge endpoints.

Types

@Serializable

enum AccountStatus : Enum<AccountStatus>

Status of a participant's account, for accounts that must verify an email address. |Status|Description| |---|---| |unverified|User has not consented to use the support email address.| |pending|System is waiting for the user to confirm the address.| |verified|User has consented and can sign in to the Bridge server.| On creation, the initial status of a user account depends on the email verification policy of the app. If verification is required, the account will be unverified until the participant verifies the email address; otherwise it will be enabled. Values: "enabled","disabled","unverified"

Address

@Serializable

data class Address(val placeName: String? = null, val street: String? = null, val mailRouting: String? = null, val city: String? = null, val division: String? = null, val postalCode: String? = null, val country: String? = null, val type: String? = null)

AdherenceRecord

@Serializable

data class AdherenceRecord(val instanceGuid: String, val eventTimestamp: String, val startedOn: Instant? = null, val finishedOn: Instant? = null, val clientTimeZone: String? = null, val uploadedOn: String? = null, val declined: Boolean = false, val clientData: JsonElement? = null, val type: String = "AdherenceRecord")

A record describing the performance state of a scheduled session or assessment, as requested in a Timeline. Each record describes the state of a session or an assessment.

AdherenceRecordsSearch

@Serializable

data class AdherenceRecordsSearch(val instanceGuids: List<String>? = null, val assessmentIds: List<String>? = null, val sessionGuids: List<String>? = null, val timeWindowGuids: List<String>? = null, val adherenceRecordType: AdherenceRecordType? = null, val includeRepeats: Boolean? = null, val currentTimestampsOnly: Boolean? = null, val eventTimestamps: Map<String, String>? = null, val startTime: String? = null, val endTime: String? = null, val pageSize: Int? = null, val offsetBy: Int? = null, val sortOrder: SortOrder? = null, val type: String? = null)

AdherenceRecordType

@Serializable

enum AdherenceRecordType : Enum<AdherenceRecordType>

The AdherenceRecordType can be used to limit search results for adherence records to either assessment or session records. If not present, both records will be returned according to the criteria of the search. |Enum|Description| |---|---| |assessment|| |session|| Values: "assessment","session"

AdherenceRecordUpdates

@Serializable

data class AdherenceRecordUpdates(val records: List<AdherenceRecord>, val type: String = "AdherenceRecordUpdates")

AppConfig

@Serializable

data class AppConfig(val label: String, val createdOn: String? = null, val modifiedOn: String? = null, val guid: String? = null, val deleted: Boolean? = null, val criteria: Criteria? = null, val clientData: JsonElement? = null, val surveyReferences: List<SurveyReference>? = null, val schemaReferences: List<SchemaReference>? = null, val configReferences: List<ConfigReference>? = null, val fileReferences: List<FileReference>? = null, val configElements: Map<String, JsonElement>? = null, val version: Long? = null, val type: String? = null)

An app configuration object.

AssessmentConfig

@Serializable

data class AssessmentConfig(val config: JsonElement, val createdOn: String? = null, val modifiedOn: String? = null, val version: Long? = null, val type: String? = null)

AssessmentInfo

@Serializable

data class AssessmentInfo(val key: String, val guid: String, val appId: String, val identifier: String, val revision: Int? = null, val label: String, val minutesToComplete: Int? = null, val colorScheme: ColorScheme? = null, val configUrl: String, val imageResource: ImageResource? = null, val type: String? = null)

Information about an assessment in order to render it in a UI prior to execution.

ClientInfo

@Serializable

data class ClientInfo(val appName: String? = null, val appVersion: Int? = null, val deviceName: String? = null, val osName: String? = null, val osVersion: String? = null, val sdkName: String? = null, val sdkVersion: Int? = null, val type: String? = null)

Describes the content of the User-Agent field in the format that is accepted and understandable to the Bridge server (see /articles/rest.html).

ColorScheme

@Serializable

data class ColorScheme(val foreground: String? = null, val background: String? = null, val activated: String? = null, val inactivated: String? = null, val type: String? = null)

Colors to differentiate this assessment in a UI.

ConfigReference

@Serializable

data class ConfigReference(val id: String, val revision: Long, val type: String? = null)

A pointer to a configuration element.

ConsentStatus

@Serializable

data class ConsentStatus(val name: String? = null, val subpopulationGuid: String? = null, val required: Boolean? = null, val signedOn: String? = null, val consented: Boolean? = null, val signedMostRecentConsent: Boolean? = null, val type: String? = null)

A description of the participant's consent status in a particular subpopulation (consent group). This object is never used to update state on the server (all fields are read only).

Contact

@Serializable

data class Contact(val role: ContactRole, val name: String, val position: String? = null, val affiliation: String? = null, val address: Address? = null, val email: String? = null, val phone: Phone? = null, val jurisdiction: String? = null, val type: String? = null)

A contact for the study. This is for display to the participants of the study, and in other catalogs of the studies that are available.

ContactRole

@Serializable

enum ContactRole : Enum<ContactRole>

The purpose of this contact. |Type|Description| |---|---| |irb|Either the IRB that approved the research, or in secondary jurisdictions, an “assenting” IRB that reviewed the initial approval and accepted it for their own jurisdiction.| |principal_investigator|Principal investigator of the study. Conceivably there can be one of these for every jurisdiction, but this is rare.| |investigator|Position could be co-investigator, medical monitor, repository guardian, etc. Nevertheless, this person is not presented as a point of contact (use a support role for that).| |sponsor|The institution funding the study and/or providing IRB oversight. Sometimes the institution the Principal Investigator is affiliated with.| |study_support|Position could be study coordinator or study contact—the person the participant should contact about participation in the study.| |technical_support|Support person or department for the technology being utilized (mobile app, website, device provisioning, etc.).| Values: "irb","principal_investigator","investigator","sponsor","study_support","technical_support"

Criteria

@Serializable

data class Criteria(val language: String? = null, val allOfGroups: List<String>? = null, val noneOfGroups: List<String>? = null, val allOfSubstudyIds: List<String>? = null, val noneOfSubstudyIds: List<String>? = null, val minAppVersions: Map<String, Int>? = null, val maxAppVersions: Map<String, Int>? = null, val type: String? = null)

Some objects, like Subpopulations and the schedules in a CriteriaScheduleStrategy, are matched against user criteria in order to return the correct object. The criteria against which user information will be matched are described in the Criteria object. See /articles/filtering.html for a fuller explanation.

DateRange

@Serializable

data class DateRange(val startDate: String? = null, val endDate: String? = null)

Model object representing a date range, which includes start date and end date as calendar dates (YYYY-MM-DD).

EnrollmentInfo

@Serializable

data class EnrollmentInfo(val externalId: String? = null, val consentRequired: Boolean? = null, val enrolledOn: String? = null, val withdrawnOn: String? = null, val enrolledBySelf: Boolean? = null, val withdrawnBySelf: Boolean? = null, val type: String? = null)

Details about an enrollment for the participant enrolled in the study.

Environment

@Serializable

enum Environment : Enum<Environment>

This value should always be set to production. Values: "local","develop","staging","production"

FileReference

@Serializable

data class FileReference(val guid: String, val createdOn: String, val href: String? = null, val type: String? = null)

A pointer to a file revision hosted for this app.

Identifier

@Serializable

data class Identifier(val appId: String, val email: String? = null, val phone: Phone? = null, val type: String? = null)

Payload object for an email address or phone number. You do not provide both identifiers when using this object for a call.

ImageResource

@Serializable

data class ImageResource(val name: String, val type: String, val module: String? = null, val labels: List<Label>? = null)

An indicator for an image that should be displayed. The image data is not stored in this object; this object is only used to determine which image to display.

IrbDecisionType

@Serializable

enum IrbDecisionType : Enum<IrbDecisionType>

The outcome of IRB approval that allows this study to be executed on the Bridge platform. |Type|Description| |---|---| |exempt|The study is considered to be exempt from human subjects research guidelines.| |approved|The study was reviewed by the IRB and its protocol is approved.| Values: "exempt","approved"

Label

@Serializable

data class Label(val lang: String? = null, val value: String? = null, val type: String? = null)

A localizable string value to show study participants.

Model

interface Model

NotificationInfo

@Serializable

data class NotificationInfo(val notifyAt: NotificationType, val offset: String? = null, val interval: String? = null, val allowSnooze: Boolean? = null, val message: NotificationMessage? = null, val type: String? = null)

A notification to show to a participant as part of the execution of a scheduled session.

NotificationMessage

@Serializable

data class NotificationMessage(val subject: String, val message: String, val lang: String? = null, val type: String? = null)

NotificationType

@Serializable

enum NotificationType : Enum<NotificationType>

They type of notification to provide relative to a session’s time window. This enum specifies when the notification should be shown to the participant. |Status|Description| |---|---| |after_window_start|Issue the notification the offset after the window starts| |before_window_end|Issue the notification the offset before the window ends| Values: "after_window_start","before_window_end"

ParticipantData

@Serializable

data class ParticipantData(val data: JsonObject, val identifier: String? = null, val type: String? = null)

The JSON data for a non-time series participant data attribute.

ParticipantSchedule

@Serializable

data class ParticipantSchedule(val createdOn: String, val dateRange: DateRange? = null, val schedule: List<ScheduledSession>? = null, val assessments: List<AssessmentInfo>? = null, val sessions: List<SessionInfo>? = null, val studyBursts: List<StudyBurstInfo>? = null, val eventTimestamps: Map<String, Instant>? = null, val type: String? = null)

A detailed description of when a participant should perform specific sessions as part of a study. The ParticipantSchedule is similar to the Timeline in structure, but includes the specific dates when this participant should perform each session, as well as state information about the participant’s completion of the schedule. Entries in the schedule collection should be ordered by startDate and startTime, and entries that are not available to the participant are not included in the collection (ie. entries that have the state not_applicable). However, definitions for those sessions are still included in the sessions, assessments, and studyBursts collections for future reference. Persistent time windows do not have state (they should always be available to the participant so they are never shown as finished, even if one or more adherence records have been filed for that session).

PerformanceOrder

@Serializable

enum PerformanceOrder : Enum<PerformanceOrder>

The assessments in a session can be presented in a fixed and sequential order, in a randomized order the participant cannot choose, or the participant may be allowed to pick and choose the assessments to do them in an order of their choosing. This enum specifies which method must be presented to the participant. |Status|Description| |---|---| |participant_choice|The participant can perform the assessments in any order.| |sequential|The participant must perform the assessments in the order they are specified in the session.| |randomized|The assessments should be presented to the user in a randomized order.| Values: "participant_choice","sequential","randomized"

Phone

@Serializable

data class Phone(val number: String, val regionCode: String, val nationalFormat: String? = null, val type: String? = null)

The user's phone number.

PhoneSignin

@Serializable

data class PhoneSignin(val appId: String, val phone: Phone, val token: String, val type: String? = null)

Using a token supplied in an SMS message authenticate with the server. The token remains valid, once sent, for 5 minutes.

PhoneSignInRequest

@Serializable

data class PhoneSignInRequest(val appId: String, val phone: Phone, val type: String? = null)

Make a request to sign in using an SMS message. This request will trigger a message to be sent to an existing account's phone number. The SMS message will include a numeric token that must be included in a subsequent request to the server to authenticate.

ReminderType

@Serializable

enum ReminderType : Enum<ReminderType>

If the app should issue a second reminder notification, when should this reminder be issued? If null, no reminder should be shown. If present, it can be relative to when a time window starts, or relative to when the window ends. This value works with reminderPeriod to determine the time. |Status|Description| |---|---| |after_window_start|Issue the reminder reminderPeriod after the window starts| |before_window_end|Issue the reminder reminderPeriod before the window ends| Values: "after_window_start","before_window_end"

Role

@Serializable

enum Role : Enum<Role>

The roles assigned to this user. Normal users do not have any roles assigned, but for developers, researchers, etc. their roles will appear hear (see main API documentation about the roles assigned by the Bridge server). |Role|Description| |---|---| |developer|A user with the rights to use the app configuration APIs (all admin APIs except for those APIs which expose information about study participants).| |researcher|The research role is assigned to users who have permission to see the users in a study and the activity of participants. We will assign this role to developers during the initial development of the application so they can view the uploads of test accounts, etc.| |admin|A Sage Bionetworks Bridge administrator (internal to Bridge).| |worker|A Sage Bionetworks worker process (internal to Bridge).| Values: "developer","researcher","admin","worker"

S3UploadSession

data class S3UploadSession(val filePath: String, val contentType: String, val uploadSessionId: String, val url: String, val requestHeaders: Map<String, String>) : UploadFileIdentifiable

S3UploadType

enum S3UploadType : Enum<S3UploadType>

ScheduledAssessment

@Serializable

data class ScheduledAssessment(val refKey: String, val instanceGuid: String, val type: String? = null)

The refKey of this object will refer to the key value of an AssessmentInfo object in the assessments of the timeline. The instanceGuid is a unique GUID to identify any data that is generated from the execution of this scheduled assessment. This allows scientists to contextualize data based on when it was gathered in the execution of the study’s schedule.

ScheduledSession

@Serializable

data class ScheduledSession(val refGuid: String, val instanceGuid: String, val startEventId: String? = null, var startTime: LocalTime, val delayTime: String? = null, val expiration: DateTimePeriod, val persistent: Boolean = false, val studyBurstId: String? = null, val studyBurstNum: Int? = null, val timeWindowGuid: String? = null, val assessments: List<ScheduledAssessment>, val startDate: LocalDate, val endDate: LocalDate, val type: String? = null)

An individual session instance the participant should perform as part of the study. The refGuid property will refer to a session in the list of sessions in this timeline. The instanceGuid is a unique GUID to identify any data that is generated from the execution of this scheduled session. This allows scientists to contextualize data based on when it was gathered in the execution of the study’s schedule. Further details about how a client should interpret a timeline can be found at the Bridge developer portal.

SchemaReference

@Serializable

data class SchemaReference(val id: String, val revision: Long? = null, val type: String? = null)

A pointer to an upload schema defined for this survey. This schema represents a particular task or activity that the participant should perform, and tells the app which schema ID and revision number to associate the data upload with. If the revision number is set to null when creating a schedule plan, then the reference is to the most recent revision for the given OS and app version. The specific revision number that should be used will be resolved when a #ScheduledActivity is created for the participant).

SessionInfo

@Serializable

data class SessionInfo(val guid: String, val label: String, val symbol: String? = null, val performanceOrder: PerformanceOrder, val timeWindowGuids: List<String>? = null, val minutesToComplete: Int? = null, val notifications: List<NotificationInfo>? = null, val type: String? = null)

Information about a session in order to render it in a UI prior to execution.

SharingScope

@Serializable

enum SharingScope : Enum<SharingScope>

|Enum|Description| |---|---| |no_sharing| Do not share data generated by this participant with the study team;| |sponsors_and_partners|Share data with the study researchers and their researcher partners only;| |all_qualified_researchers|Share data with researchers who qualify under the specific governance qualifications to access the study's data set. This may include researchers beyond the sponsors of the original study.| Values: "no_sharing","sponsors_and_partners","all_qualified_researchers"

SignInType

@Serializable

enum SignInType : Enum<SignInType>

|Enum|Description| |---|---| |email_password| Study expects participants to sign in with an email address and a password. | |phone_password| Study expects participants to sign in with a phone number and a password. | |external_id_password| Study expects participants to sign in with an external ID and a password. | |email_message| Study expects participants to sign in by sending an email message to the participant’s email account with a sign in code or sign in link. | |phone_message| Study expects participants to sign in by sending an SMS message to the participant’s phone number with a sign in code or sign in link. | Values: "email_password","phone_password","external_id_password","email_message","phone_message"

SortOrder

@Serializable

enum SortOrder : Enum<SortOrder>

|Enum|Description| |---|---| |asc| Sort so that the earliest startedOn time is the first record in the returned list. | |desc| Sort so that the most recent startedOn time is the first record in the returned list. | Values: "asc","desc"

Study

@Serializable

data class Study(val identifier: String, val name: String, val phase: StudyPhase, val version: Long, val details: String? = null, val clientData: JsonElement? = null, val irbName: String? = null, val irbDecisionOn: String? = null, val irbExpiresOn: String? = null, val irbDecisionType: IrbDecisionType? = null, val irbProtocolName: String? = null, val irbProtocolId: String? = null, val studyLogoUrl: String? = null, val colorScheme: ColorScheme? = null, val institutionId: String? = null, val scheduleGuid: String? = null, val keywords: String? = null, val diseases: List<String>? = null, val studyDesignTypes: List<String>? = null, val signInTypes: List<SignInType>? = null, val contacts: List<Contact>? = null, val deleted: Boolean? = null, val createdOn: String? = null, val modifiedOn: String? = null, val type: String? = null)

A study (an outside organization providing participants for a study).

StudyActivityEvent

@Serializable

data class StudyActivityEvent(val eventId: String, val timestamp: Instant, val answerValue: String? = null, val clientTimeZone: String? = null, val recordCount: Int? = null, val createdOn: String? = null, val type: String? = null)

Activity event for a participant in a specific study, used for scheduling activities.

StudyActivityEventList

@Serializable

data class StudyActivityEventList(val items: List<StudyActivityEvent>? = null, val type: String? = null)

StudyActivityEventRequest

@Serializable

class StudyActivityEventRequest(val eventId: String, val timestamp: Instant, val answerValue: String? = null, val clientTimeZone: String? = null, val type: String? = "CustomActivityEventRequest")

StudyBurstInfo

@Serializable

data class StudyBurstInfo(val identifier: String, val originEventId: String, val delay: DateTimePeriod = DateTimePeriod(), val interval: DateTimePeriod, val occurrences: Int, val type: String? = null)

Information about a study burst from which some of the timeline is being derived.

StudyInfo

@Serializable

data class StudyInfo(val identifier: String? = null, val name: String? = null, val details: String? = null, val phase: StudyPhase? = null, val studyLogoUrl: String? = null, val colorScheme: ColorScheme? = null, val signInTypes: List<SignInType>? = null, val type: String? = null)

An abridged study object with information that is useful for displaying, selecting, and signing into the study.

StudyParticipant

@Serializable

data class StudyParticipant(val firstName: String? = null, val lastName: String? = null, val synapseUserId: String? = null, val id: String? = null, val notifyByEmail: Boolean = true, val attributes: Map<String, String>? = null, val sharingScope: SharingScope? = null, val createdOn: String? = null, val emailVerified: Boolean? = null, val phoneVerified: Boolean? = null, val status: AccountStatus? = null, val roles: List<Role>? = null, val dataGroups: List<String>? = null, val clientData: JsonElement? = null, val languages: List<String>? = null, val studyIds: List<String>? = null, val externalIds: Map<String, String>? = null, val orgMembership: String? = null, val clientTimeZone: String? = null, val healthCode: String? = null, val email: String? = null, val phone: Phone? = null, val consentHistories: Map<String, List<UserConsentHistory>>? = null, val enrollments: Map<String, EnrollmentInfo>? = null, val consented: Boolean? = null, val timeZone: String? = null, val type: String? = null)

StudyParticipant payload. The Participant API supports sparse updates, so most fields in this class are marked as EncodeDefault.Mode.NEVER.

StudyPhase

@Serializable

enum StudyPhase : Enum<StudyPhase>

A lifecycle phase for the study. |Type|Description| |---|---| |legacy|If not set, the study is in the LEGACY phase, and no domain logic will be applied to the study, enrollments, etc.| |design|Study is being designed and tested and has not begun. All accounts created in this phase are marked as test accounts, and schedules are still mutable. The study is not visible in public registries.| |recruitment|Study has launched and is visible in public registries, and accepting new participants through some form of enrollment. The schedule is published when the study is transitioned to this phase, and can no longer change.| |in_flight|The study is no longer accepting new participants, but participants are still active in the study. The study is no longer visible in public registries and will no longer accept new sign ups.| |analysis|All participants have completed the study protocol, and the data is being analyzed. For IRBs, this study is still open and it should still be available in administrative UIs for reporting, but no mobile or desktop participant-facing client should be engaged with the study.| |completed|Analysis has been completed and the study has been reported to the IRB. The study can now be logically deleted.| |withdrawn|The study was withdrawn before completion. It can be withdrawn from any other phase, and at that point it can be logically deleted.| Values: "legacy","design","recruitment","in_flight","analysis","completed","withdrawn"

SurveyReference

@Serializable

data class SurveyReference(val guid: String, val identifier: String? = null, val createdOn: String? = null, val href: String? = null, val type: String? = null)

A pointer to a survey defined for this app, and associated with a survey to be taken as part of the mobile application health study. If the createdOn value is null, then the reference is to the most recently published version of the survey (the specific version that should be used will be resolved when a #ScheduledActivity is created for the participant).

Timeline

@Serializable

data class Timeline(val duration: DateTimePeriod, val schedule: List<ScheduledSession>? = null, val assessments: List<AssessmentInfo>? = null, val sessions: List<SessionInfo>? = null, val studyBursts: List<StudyBurstInfo>? = null, val totalMinutes: Int? = null, val totalNotifications: Int? = null, val type: String? = null)

A detailed description of when a participant should perform specific sessions and assessments as part of a study, along with the metadata to show UI to the participant before loading and executing code for the assessments.

UploadedFileRecord

@Serializable

data class UploadedFileRecord(val filePath: String, val uploadTimestamp: Instant, val uploadSessionId: String? = null, val metadata: UploadMetadata? = null) : UploadFileIdentifiable

UploadFile

@Serializable

data class UploadFile(val filePath: String, val contentType: String, val fileLength: Long, val md5Hash: String?, val encrypted: Boolean = true, val metadata: UploadMetadata? = null, val s3UploadType: S3UploadType = S3UploadType.STUDY_DATA) : UploadFileIdentifiable

UploadFileIdentifiable

interface UploadFileIdentifiable

UploadMetadata

@Serializable

data class UploadMetadata(val instanceGuid: String? = null, val eventTimestamp: String? = null, val startedOn: String? = null)

UploadRequestMetadata

@Serializable

data class UploadRequestMetadata(val instanceGuid: String? = null, val eventTimestamp: String? = null, val startedOn: String? = null, val finishedOn: String? = null, val declined: Boolean? = null, val clientTimeZone: String? = null, val clientData: JsonElement? = null)

UploadSession

@Serializable

data class UploadSession(val id: String? = null, val url: String, val expires: String? = null, val type: String? = null)

UserConsentHistory

@Serializable

data class UserConsentHistory(val subpopulationGuid: String? = null, val consentCreatedOn: String? = null, val name: String? = null, val birthdate: String? = null, val imageData: String? = null, val imageMimeType: String? = null, val signedOn: String? = null, val withdrewOn: String? = null, val hasSignedActiveConsent: Boolean? = null, val type: String? = null)

A record of a complete consent (including both the dates of consent and withdrawal, if applicable);

UserSessionInfo

@Serializable

data class UserSessionInfo(val firstName: String? = null, val lastName: String? = null, val externalId: String? = null, val id: String, val notifyByEmail: Boolean? = null, val attributes: Map<String, String>? = null, val sharingScope: SharingScope? = null, val createdOn: String? = null, val emailVerified: Boolean? = null, val phoneVerified: Boolean? = null, val status: AccountStatus? = null, val roles: List<Role>? = null, val dataGroups: List<String>? = null, val clientData: JsonElement? = null, val languages: List<String>? = null, val studyIds: List<String>, val externalIds: Map<String, String>? = null, val authenticated: Boolean, val sessionToken: String, val reauthToken: String? = null, val environment: Environment? = null, val email: String? = null, val phone: Phone? = null, val dataSharing: Boolean? = null, val signedMostRecentConsent: Boolean? = null, val synapseUserId: String? = null, val consented: Boolean = false, val consentStatuses: Map<String, ConsentStatus>? = null, val enrollments: Map<String, EnrollmentInfo>? = null, val orgMembership: String? = null, val type: String? = null)