Study Participation

Enrollment / Anonymous Participation

A Study can be configured to have open enrollment, if no invitation is required to participate, or limited enrollment if an invitation is required to participate in the study.

Invitations are created and sent using the Medable Axon web app. When sending invitations, a group can be speficied, so when the user registers he/she is automatically assigned to that group.

In Open Enrollment studies, a patient registering without an invitation will be automatically placed in the All group.

Invitation Token

When sending an invitation, an invitation token is created, and an email is sent to the invitee. If you like to configure a URL redirect scheme in your app, make sure to edit your account creation email template to include that token and your configure your URL scheme to accept this invitation token, you can then set this value using the following method:

// Set the invitation token
[[Medable axon] setPublicUserToken:@"token here..."];

// The token is an object Id, and looks like this: 57c04bcf5d0622c6adeed5a7
// For more info, read the docs in MDRAxon's header file.

// It's important to call this as soon as you get the token in your AppDelegate.

📘
About the invitation token

Calling that method persists the invitation token, and will be available until:

A new invitation token is passed in.

The value nil is passed in.

If you want to delete the token --i.e.: because the user didn't join the study or something, just call the method above with nil as parameter.

The 'Public' and the 'All' special groups

When a study is created, two special groups are automatically created within it.

The Public group, which contains the tasks that are anonymously accesible (i.e.: Onboarding related tasks. This depends on your particular research study but, these are commonly Eligibility / Consent / Registration / Initial Surveys tasks). Let's call public tasks to the tasks that are assigned to this group.
The All group, which is the group any new registered user lands if no group was specified when inviting him/her; or if no invitation is required in the study, and the participant just joins willingly.

With that said, we have four use cases:

Open Enrollment study

Without invitation: The user goes through the public tasks and, he/she is automatically assigned to the All group upon registration.
With invitation: Even though the study doesn't require invitation, we could use an invitation to make the user be assigned to a different group other than the All group upon registration. So, in this case, the user goes through the public tasks and, he/she is automatically assigned to the group specified on the invitation upon registration.
- For this we need to create an invitation using the web app, and specify the group we want the participant to be assigned upon registration.
- Then the invitation token should be passed in to the Medable iOS Axon's MDRAxon singleton, so the group assignation is correctly executed later on.

Limited Enrollment study

Without invitation: Nothing can be done here. If you try to make any call, you will get a fault object returned as response (the class is MDFault).
With invitation: In this case, the user goes through the public tasks and, he/she is automatically assigned to the group specified on the invitation upon registration.
- For this we need to create an invitation using the web app, and specify the group we want the participant to be assigned upon registration.
- Then the invitation token should be passed in to the Medable iOS Axon's MDRAxon singleton, so the group assignation is correctly executed later on.

Another alternative is to verify your email address and PIN by calling the following method:

[[MDRAxon sharedInstance] verifyEmail:email withPin:pin studyId:studyId callback:^(id object, MDFault *fault)
{
    if ( fault != nil )
    {
        //Handle fault
    }
    else
    {
        //Continue as a verified user, the invitation token is already set
    }
}];

Anonymous responses re-binding to newly created account

Responses sent before registeration are bound to the invitation token.
Once the user registers, previous reponses bound to the invitation token and bound to the newly created account.
This only happens when the user completes an authentication task successfully, during the onboarding (i.e.: public task in the Public group).

Special considerations for your app

It is you app's responsibility to know when to call fetchUserTasks, and also to know if a user did register already. This is because:
- Suppose a user was invited to a study, and then went through all the public tasks, using an invitation token --if necessary-- and then registered.
- After a successful registration that user is assigned to another group, different than the Public group, having access to other tasks.
- The next time the app is opened, if it calls fetchUserTasks before logging in, the task manager will try to retrieve the public tasks anonymously, assuming it is just a new user trying to access the study. It will even create an "invitation token" if there isn't one and the study has open enrollment.
- Having said all that, your app needs to know what to call and when. Probably needing to keep track of if a user already registered successfuly or maybe providing a screen to chose from "Log In", "I'm a new user" or something alike.

Users leaving a study

For anonymous users, it's only a matter of deleting the invitation token as described before.

For users with existing accounts you can call the leave study method like this:

[[MDRAxon sharedInstance] leaveStudy:^(id object, MDFault *fault)
{
    if ( fault != nil )
    {
        //Handle Fault
    }
    else
    {
        //Deal with user having left the study, this likely means going back to an unregistered state
    }
}];