1 | P a g e

Jeeves User Guide How to create, update and deploy your ESM studies

Contents

Setting up Jeeves .......................................................................................................................................................................................... 3

Giving Participants Access ......................................................................................................................................................................... 9

The Basics ...................................................................................................................................................................................................... 12

A – Menu Bar ........................................................................................................................................................................................... 12

B – Section Selector .............................................................................................................................................................................. 13

C- Canvas .................................................................................................................................................................................................. 13

D – Log Design Pane ............................................................................................................................................................................ 13

E – User Attributes................................................................................................................................................................................. 14

Creating Surveys ......................................................................................................................................................................................... 15

Survey Parameters ................................................................................................................................................................................. 15

Adding and Moving Questions ........................................................................................................................................................ 16

Editing Questions .................................................................................................................................................................................. 17

Question Branching.......................................................................................................................................................................... 17

Assigning Attributes......................................................................................................................................................................... 19

Question Types ....................................................................................................................................................................................... 21

Open ended ........................................................................................................................................................................................ 21

Numeric ................................................................................................................................................................................................ 21

Yes/No ................................................................................................................................................................................................... 21

Multiple Choice (Single) ................................................................................................................................................................. 21

Multiple Choice (Many) .................................................................................................................................................................. 22

Time........................................................................................................................................................................................................ 22

2 | P a g e

Date ........................................................................................................................................................................................................ 22

Scale ....................................................................................................................................................................................................... 22

Geo ......................................................................................................................................................................................................... 23

Heart Rate ............................................................................................................................................................................................ 23

Text Present ......................................................................................................................................................................................... 23

Image Present .................................................................................................................................................................................... 24

Audio Present ..................................................................................................................................................................................... 24

All About Blocks .......................................................................................................................................................................................... 25

Triggers ..................................................................................................................................................................................................... 25

Set Times Trigger .............................................................................................................................................................................. 25

Interval Trigger ................................................................................................................................................................................... 25

Repeated Time Trigger ................................................................................................................................................................... 26

Begin Trigger ...................................................................................................................................................................................... 26

Sensor Trigger .................................................................................................................................................................................... 26

Location Trigger ................................................................................................................................................................................ 26

Button Trigger .................................................................................................................................................................................... 27

Survey Trigger .................................................................................................................................................................................... 27

Actions ....................................................................................................................................................................................................... 27

Send Survey ......................................................................................................................................................................................... 27

Send Prompt ....................................................................................................................................................................................... 27

Update Waking Schedule .............................................................................................................................................................. 28

Snooze App ......................................................................................................................................................................................... 28

Sense Data ........................................................................................................................................................................................... 28

Update Attribute ............................................................................................................................................................................... 28

Conditions ................................................................................................................................................................................................ 29

Conditional Statements ....................................................................................................................................................................... 29

‘If’ Conditional Statement .............................................................................................................................................................. 29

3 | P a g e

‘While’ Conditional Statement ..................................................................................................................................................... 29

Triggers vs. Conditional Statements ............................................................................................................................................... 30

Execution Flow ........................................................................................................................................................................................ 31

Triggers are independent of each other .................................................................................................................................. 31

Actions execute in sequence ........................................................................................................................................................ 31

Survey actions won’t wait until you’re done ........................................................................................................................... 32

Monitoring User Data ............................................................................................................................................................................... 33

Downloading Data ................................................................................................................................................................................ 33

Sending/Receiving Feedback ............................................................................................................................................................ 34

Updating Users’ Schedule .................................................................................................................................................................. 35

Setting up Jeeves

To maximise security of your participants’ data, and to ensure GDPR-compliance, the setup of Jeeves has

changed significantly so that you as a researcher are owner and administrator of your own database, rather

than being part of a single shared database.

1. This guide takes you step-by-step through the simple process of setting up your database using

Google’s Firebase. First, if you don’t have a Google account already, you’ll need to create one.

4 | P a g e

2. Then, head to https://console.firebase.google.com and click on ‘Create a project’

3. In the following two windows, you can set a name for your project and default sharing settings. In the

first window, give your project any name you choose, and untick the ‘Use the default settings for sharing

Google Analytics for Firebase data’ checkbox. Leave all boxes unticked on the second window.

4. Once this is done, you need to set up the database for your participant and project data. Click on

‘Database’ in the sidebar, and then ‘Create database’ on the presented screen, as shown below.

https://console.firebase.google.com/

5 | P a g e

5. The following two windows let you set the security rules and location for your database. Select ‘Start in

locked mode’ in the first window, and select the most appropriate location for your participant data

from the dropdown in the second window.

6. After this, you now need to generate a ‘private key’ that Jeeves uses to load and save project

specifications to your database. Click on the cog icon in the sidebar, then ‘Project settings’, and then

the ‘Service accounts’ tab on the settings screen, as shown below.

7. In this tab, click the ‘Generate new private key’ button circled below, and then ‘Generate key’ in the

popup that appears. This will download a .json file – keep this safe as it will be needed later!

6 | P a g e

8. Next, you’ll need to set up the storage functions so that audio clips and images can be displayed to

your participants. Click ‘Storage’ in the sidebar and then the ‘Get started’ button on the screen that

appears. Click through the two setup windows that appear, and you’ll have a new storage space.

9. Just like you need a private key for database functions, you’ll need a separate private key for using

storage functions with Jeeves. To get a ‘service account key’ for cloud storage, head to the following

URL: https://cloud.google.com/storage/docs/reference/libraries, scroll down to the ‘Go to the Create

Service Account Key Page’ button and click on it.

https://cloud.google.com/storage/docs/reference/libraries?authuser=0

7 | P a g e

10. On the page that loads, click on ‘Select a project’, then select the name that you chose for your project

in the list that is presented.

11. In the ‘Service account’ dropdown box, select ‘New service account’. Give your account any name,

make sure ‘JSON’ is selected as the Key type, then click ‘Create’.

8 | P a g e

12. If asked to assign a role to your account, select ‘Project’ -> ‘Owner’, then click the ‘Create’ button. This

will download the second .json file that you’ll need. Give it a suitable name like ‘storage.json’ to

distinguish it from the database key JSON file you created in Step 7.

13. When you first open Jeeves, you will be presented with a pop-up box that asks you to locate the two

JSON files you previously downloaded. You only need to do this once, after which it will save these files

and use them every time you open Jeeves thereafter.

It’s important that you choose the JSON files correctly or you won’t be able to save your project or save

any image/audio files in storage. If you realise you have incorrectly selected these files, you can reset

them by going to where Jeeves is installed in your filesystem and deleting the ‘firebasekey.json’ and

‘storagekey.json’ files that are generated in the same directory.

9 | P a g e

Giving Participants Access

There are additional steps to allow your participants access to your study and to upload survey results to the

database. This section of the guide walks through the steps to do so.

1. First, click on ‘Authentication’ in the sidebar, then on the ‘Sign-in method’ tab as shown below.

2. Select ‘Email/Password’, click on the ‘Enable’ switch to allow this means of authentication when

signing up to a Jeeves study, then click the ‘Save’ button.

3. Next, you’ll need to allow participants read and write access to certain areas of the database, through

declaring security rules. Select ‘Database’ in the sidebar, then make sure that ‘Realtime Database’ is

selected in the dropdown box (not ‘Cloud Firestore’) and finally click on the ‘Rules’ tab as shown below.

10 | P a g e

Copy and paste the following JSON into the presented text box, overwriting the existing JSON as shown, then

click the ‘Publish’ button to confirm these rules.

These rules state that all ‘projects’ (i.e., the combinations of blocks and surveys created using Jeeves) can be

read by anyone, but only the ‘surveydata’ section of each project can be written to. All survey data is

encrypted before being uploaded, so that even if a participant somehow accessed the survey data of another

participant, it could not be decrypted by them.

The ‘users’ section of the database contains data on your users/participants. The ‘$uid === auth.uid’ text

dictates that users can only read from and write to their own personal data, and have no access to others’.

4. Finally, you need to generate a config file that you’ll send to each of your participants to link their

installation of the JeevesAndroid app with your database and storage. First, to add an Android app to

your project, click the cog icon in the sidebar, followed by ‘Project settings’. Scroll down to the section

that allows you to select an app platform, then click on the Android icon as highlighted below.

5. In the ‘Register app’ section, enter ‘com.jeevesandroid’ as the Android package name (the app

nickname is not necessary) then click the ‘Register app’ button.

{

"rules": {

"projects": {

".read":true,

"surveydata": {

".write": true

}

},

"users": {

"$uid": {

".read": "$uid === auth.uid",

".write": "$uid === auth.uid"

}

}

}

}

11 | P a g e

6. Finally, in the ‘Download config file’ section, click the ‘Download google-services.json’ button. This

will download the JSON config file for your participants, to pair their app with your project.

The simplest means of doing so is by emailing the file to your participants so that they can access it

from their smartphone.

When a participant first opens the JeevesAndroid app, they will be prompted to select a config file in

their device’s file system. Once they have selected an appropriate JSON file, they can then create an

account and will be registered to your database.

12 | P a g e

The Basics

First of all, thanks for giving Jeeves a look! I’ve tried to make this guide as comprehensive as possible,

but if you have any questions or suggested updates, I’d be glad to hear from you. Email me at

danieljrough@gmail.com to let me know.

We’ll start with an overview of the different sections of Jeeves, before delving into how to design a survey, how

to create your study specification with blocks, and how to view and interact with participants and their data.

Figure 1 - Main interface of Jeeves

A – Menu Bar

The icons on the menu bar have the following functions:

New – Create a new study (make sure to save any changes to your current study first!)

Open - Select any of your previously created studies to open and make changes.

Save – Save your study (if it is new, you will be prompted to enter a name). Any changes you make will

be automatically pushed in real-time to any participants signed up to the study.

mailto:danieljrough@gmail.com

13 | P a g e

Quit – Exit Jeeves (make sure to save any changes before you do!)

B – Section Selector

The Section Selector contains three tabs that allow you to move between the three main functions of Jeeves –

the Blocks Library, Survey Design pane, and the User Data pane. Click on one to jump to the relevant section.

C- Canvas

The Canvas is where your study specification is built with blocks from the Blocks Library. By dragging and

dropping Trigger blocks, Action blocks, and other types of block onto this canvas, you can design how surveys

and prompts will be sent to your participants.

D – Log Design Pane

This pane allows you to drag and drop buttons and labels onto a virtual smartphone (Figure 2, left). When a

user accesses the Self Report section of Jeeves by pressing the ‘Log New Information’ button (Figure 2, center)

they are presented with the same buttons and labels (Figure 2, right).

Figure 2- Updating users' self-report functions from the Log Design pane

These buttons can then be tied to different app functions like sending surveys, through the Button Trigger

described later.

14 | P a g e

E – User Attributes

User Attributes are added, edited and removed in this pane. An Attribute is a special type of block that can be

used in your study specification to tailor studies to individual users. The screenshot of two Triggers below

demonstrates why Attributes might be useful (different types of blocks are discussed in All About Blocks - skip

ahead to this section if you want to be clearer about Triggers and Actions first).

The left Trigger block is designed to send a prompt 6 times a day for 2 weeks (from the 14th June to the 28th

June) between 8am and 10pm.

This could be a problem – what if your users start the study on different days? What if they aren’t awake

between 8am and 10pm?

Attributes solve this problem by acting as blocks that can hold values personalized to a user. For example, the

Attributes can hold different values that are chosen by the user

her/himself.

From the Attributes Pane, you can create a new Attribute, giving it a name and one of the following types:

Different types of Attribute are distinguished

by their appearance and can be used in different ways in your blocks specification.

Attributes can be assigned values through users’ answers to survey questions (see Assigning Attributes) but

you can also assign your Attribute an initial ‘random’ value by ticking the random value box. Depending on

the type of Attribute you create, one of the pop-ups below will appear, which allow you to give your Attribute

different possible random values.

In these examples above…

15 | P a g e

- The Attribute will be an even number between 2 and 12 (inclusive).

- The Attribute will be assigned to ‘Cat 1’, ‘Cat 2’ or ‘A third category’.

- The Attribute will be a random day between June 14th and July 6th.

- The Attribute will be a random time between 12:14am and 1:02pm.

A pop-up does not appear for a random Attribute (it is simply assigned to either True or

False). You cannot generate a random Attribute.

Creating Surveys

In an ESM study, the surveys you send to your participants are a crucial component of your study specification.

This section walks you through the details of creating and editing these surveys. The Survey Design section is

accessed from its tab in the Section Selector pane.

Figure 3 - Screenshot of the Survey Design pane

Survey Parameters

First, you should give your survey a unique Name so that you can reference it later when designing your study

specification.

The Add expiry time option lets you specify whether the survey should expire after a certain number of

minutes – to stop users filling out surveys too late or completing many surveys at once.

16 | P a g e

The Fast Transitions option is for specific cases where users may be in cumbersome situations when

completing surveys (e.g., riding a bike). With this option selected, the survey automatically loads without

requiring the user to respond to the notification. Also, the user does not have to press ‘Next’ after selecting an

answer to certain question types, and the survey finishes without a final ‘Thank you’ prompt.

Adding and Moving Questions

To add a new question to your survey, simply drag and drop one of the ‘Question Types’ into the ‘Questions’

list (Figure 4). Questions can be rearranged in the list by dragging and dropping them into the desired position

(Figure 5).

Figure 4 - Drag and drop question types into your Questions list

Figure 5 - Rearrange questions in your list through drag-and-drop

17 | P a g e

Editing Questions

For each question that you add to your survey, you can edit its Question Text and

whether it Must be answered (if this is selected, the user cannot move to the next

question before entering an answer).

Some questions will also have additional options. For example, when editing a

multiple-choice question, you must enter the choices for the user to select from, as

shown in the screenshot. The additional options for each question type are

described in the Question Types section.

Two other important features are Question Branching, and Assigning Attributes

based on users’ answers to questions. These two features will be described below.

Question Branching

Sometimes, you may only want to ask a survey question based on the answer of a

previous question. For example, it would only make sense to ask: “Please list the people you are with” if the

answer to “Are you with anyone just now?” is ‘Yes’. The Question Branching feature of Jeeves allows you to

accomplish this.

Figure 6 - Example survey with two different question branches

18 | P a g e

When editing a question, tick the Ask this if answer to checkbox to select from a drop-down list of any

previous question in your survey. The answer to your selected previous question will then determine whether

or not the question you are editing gets asked.

In the Figure 6 example, the ‘Pick multiple options’ question is only asked if the answer to ‘Which study group

have you been assigned to?’ is ‘Group C’.

Depending on the previous question you have selected, you can then specify what the condition should be:

Yes/No Question condition: simply checks

whether the user’s answer was ‘yes’ or ‘no’.

Number Question condition: checks whether the

user’s answer was greater than, less than, or equal

to a given value.

Time Question condition: checks whether the

user’s answer was before or after a given time.

Date Question condition: checks whether the

user’s answer was before or after a given date.

Category Question condition: checks whether the

user’s answer was equal to a given option.

The conditional question, and the parent question it is dependent on, become the same colour to indicate their

relationship. If you try to reorder your questions in a way that puts the conditional question before its parent,

this will be disallowed.

19 | P a g e

Assigning Attributes

As mentioned in the section on User Attributes, these blocks can be given specific values from users’ answers

to survey questions. As an example of how to do this, you can create a Time question that asks the user ‘What

time do you wake up?’ Then you can save the answer that the user gives into the Attribute.

To extend this example, take the survey below, which contains two Time questions: "What time do you wake

up?" and "What time do you go to sleep?" assigned to the and Attributes respectively.

Then, in the blocks specification, the user can begin this survey at any time by pressing an 'Update' button.

Whenever the user completes this survey, the Interval Trigger will be updated to only schedule prompts

between the user's two specified times.

All Attribute types can be tailored in different ways. Take the 'Intro' survey below:

20 | P a g e

This asks the user "Which study group have you been assigned

to?" and saves their answer into the Attribute.

This could then be used to provide different surveys to a control

and test group, as shown in the adjacent specification.

A final useful example is the tailoring of meaningful locations to

a particular user. You might want to send a survey when a

participant is at home, but 'home' is likely different for each of

your participants, and so requires tailoring.

By asking the user to choose a specific set of GPS coordinates for

'Home', the study can be tailored to this location.

In this more complex example, a check is done every 10 minutes

between 12pm and 3pm to see if the Attribute is false

and the user is at home. If this is the case, the 'Test' survey is sent,

and is updated to be true so that the survey is not

sent again.

21 | P a g e

Question Types

Jeeves offers a variety of question types (some are not strictly ‘questions’ but instead present images, text or

sounds to the user). This section explains what the different types are for, the additional options that you must

specify for the question type, the attribute types that you can assign to each question type, and a snapshot of

what each question looks like on the app.

Open ended

Free text question type, for open-ended answers.

Numeric

Similar to the ‘Open Ended’ type but restricted to numeric values. Thus, the

answer can be assigned to a type Attribute.

Yes/No

Presents ‘Yes’ or ‘No’ options in the form of radio buttons. The answer can

be assigned to a Attribute.

Multiple Choice (Single)

Presents multiple options to the user and allows them to choose one. Can

be assigned to a type Attribute.

Additional options: you must specify the question choices

22 | P a g e

Multiple Choice (Many)

Same as before, but displays check boxes instead of radio buttons, allowing the

user to select multiple options

Additional options: you must specify the question choices

Time

Presents a ‘time picker’ allowing the user to select a time of day. These can be

assigned to attributes for tailored scheduling of surveys, for

example.

Date

Presents a ‘date picker’ allowing the user to select any date, which can be

assigned to a Attribute.

Additional options: You can specify whether the users’ selected date should

be in the past or future.

Scale

For Likert Scale questions (or any other question that requires a user to

choose from a discrete range of values). This presents a slider to the user.

The selected value can be assigned to a Attribute

Additional options: You must specify the number of items in the scale, and

also beginning, middle and end labels for the slider.

23 | P a g e

Geo

Presents a Google map to the user, allowing them to select

a location. The user’s answer can be assigned to a

Attribute for tailored Location Triggers.

Heart Rate

This is not a question as such, but instead allows the user to capture their

heart rate by placing their finger over the camera for 30 seconds.

Text Present

Presents a large chunk of text to the user. Scrolling is enabled so that the text

can be as long as necessary.

Additional options: You must specify the chunk of text to display to the user.

24 | P a g e

Image Present

Displays an image to the user. Again, this is not actually a ‘question’ that

requires an answer.

Additional options: You must choose the image file from your computer (note

that large images may take some time to upload and download).

Audio Present

Presents an audio file to the user that they must listen to in full before

continuing to the next question.

Additional options: You must choose the audio file from your computer (note

that audio files may take some time to upload and download).

25 | P a g e

All About Blocks

The visual language ‘blocks’ consist of four types: Triggers, Actions and Conditions, as well as the Attributes

described in the previous section. This part of the guide describes what each does, and how you might want to

use it in your study specification.

Triggers

Your specification doesn’t do anything without Triggers! Trigger blocks specify the events that determine when

actions should be taken. For example, a certain time of day, a button press, or a change in location might all be

useful events on which to send a survey to a user, or do other things.

Set Times Trigger

Use: This allows you to add a number of specific times that you want actions to

be taken on a given day or number of days.

Click ‘add time’ to insert as many new time slots as you require; click ‘remove

time’ if you need to get rid of a slot (time slots will be removed from bottom to

top).

Interval Trigger

Use: Allows pseudo-random scheduling, with surveys sent at regular intervals

but with a level of randomness

You can specify the length of an interval (in minutes) and a range of randomness

in which actions will be taken.

26 | P a g e

Repeated Time Trigger

Use: Allows actions to be scheduled a specific number of times every day. You

can specify the number, and whether these should be fixed at exactly even

intervals, or completely random.

Note that this is true randomness, and triggers may occur at any time between

the start and end times.

Begin Trigger

Use: For any actions that need to be taken as soon as your ESM study begins, you can

use the Begin Trigger. This could be for setting up necessary user attributes, for

example.

Sensor Trigger

Use: Allows actions to be taken when the on-board

smartphone sensors return an interesting result. Two types

of sensor trigger are available (activity and noise level).

Activity recognition is performed using Google’s Activity

Recognition API, and noise level by the EmotionSense

libraries.

Location Trigger

Use: Separate from the Sensor Trigger, the Location Trigger provides more

specific functionality for when users enter, leave, or stay within a particular

location.

The purple ‘Home’ attribute shown in this Trigger is set by the user,

allowing tailored triggering based on locations of personal meaning to a

user (see Assigning Attributes).

27 | P a g e

Button Trigger

Use: Allows the user to initiate actions by pressing

a button in the Jeeves app.

Create a button in the Log Design pane and select

its name in the dropdown box.

Survey Trigger

Use: Performs actions immediately after a user

has completed or missed a selected survey. If the user misses a survey, you

might use this Trigger to remind them to complete surveys, or to send the

survey again.

On survey completion, you might use this Trigger to check the user’s latest

answer to a particular question, and perform further actions based on this.

Actions

Just like Triggers, without Actions your app won’t do anything! Actions can be combined with Triggers to

define what should happen when the Trigger conditions are met. As well as sending surveys or reminder

prompts, Jeeves has some other useful ‘passive’ Actions that you might want to make use of.

Send Survey

If you are using Jeeves as an ESM creation tool, sending surveys will be a key component of your app’s

function. This delivers a survey notification to your users that, when opened, will start your selected survey.

Send Prompt

This presents a notification to the user containing your specified prompt text. Unlike the survey notification,

this can be dismissed immediately through swiping.

28 | P a g e

Update Waking Schedule

This Action sends a special type of survey, through which they can pre-program their waking and sleeping

times for a number of study days. The full use of the scheduling feature is described in Updating Users’

Schedule.

Snooze App

Sometimes, you may not want to perform certain actions immediately after the Trigger event occurs. This

allows you to specify a time to wait before continuing with the remaining Actions in a particular Trigger. It is

also useful to include this Action in a ‘While’ Conditional Statement.

Sense Data

This captures sensor data from one of the device’s sensor streams (Activity, Microphone or Location) for a set

time. The sampled data is then stored and will be made available for download from the User Data Pane*.

Note that constantly capturing sensor data can be draining on the device’s battery - do so sparingly!

Update Attribute

As discussed, User Attribute blocks contain pieces of information specific to a user. While most of the time

you will want to assign these attributes to survey questions (so users can specify their values themselves)

you can also update the values of attributes manually through the

Update Attribute Action.

As shown in the adjacent screenshot, the Action changes in response

to the type of attribute you drag into it, allowing you to set true/false

values, numbers, times and dates.

29 | P a g e

Conditions

Conditions are blocks that represent something that is either true or false (i.e., they are a bit like Attributes,

which is why they have a similar appearance).

Combined with the Conditional Statement blocks,

they can be used to determine whether or not to perform

certain actions when a Trigger event occurs. The figure opposite

shows how Conditions and Attributes can be

combined to create more complex Conditions.

Other Conditions are also available that make use of different

types of Attribute. For example, the adjacent Conditions check

whether a Attribute is less than, more than, or equal to a value.

Others check whether the current date or time falls within the bounds of the

specified Attributes.

Conditional Statements

Conditional Statements are actually special types of Actions, which can contain their own Actions and

determine whether or not they should be performed based on the value of their contained Condition. The two

types are ‘If’ and ‘While’ Conditional Statements:

‘If’ Conditional Statement

The ‘If’ Conditional Statement determines whether or not its contained

Actions should be executed based on the value of its Condition. In this

example, if either of the Attributes ‘att3’ or ‘att2’ are true, then the

survey will be sent.

‘While’ Conditional Statement

The ‘While’ Conditional statement is similar, except it will continue to

execute its contained Actions until its Condition is no longer true. In this

example, while the user is detected to be at home, a prompt will be sent

every 10 minutes.

Note: If a Snooze App action is not included in the While statement, the enclosed Actions are executed every 1

minute by default. This stops Actions being continuously executed, which could cause the app to crash.

30 | P a g e

Triggers vs. Conditional Statements

Some Triggers may seem to be identical in function to Conditional Statements…so when should you use

Triggers, and when should you use Conditions? For example, the Location Trigger and the Location Condition

may appear to do the same thing. Likewise, the Survey Trigger and Survey Condition might look functionally

identical.

The difference is that Triggers represent

EVENTS while Conditions represent STATES.

For example, the exact time of sunrise is an

event. If the Sun is in the sky, that is an

ongoing state.

So, the point at which the user enters their home is

an event, whereas the user being at home is an

ongoing state. The exact time when a user’s daily

assessment survey expires is an event, but the user

having missed their last survey is an ongoing state.

Also notice the shape of the Conditional Statement – it has a notch sticking out like other Actions. This means

that it must be nested within a Trigger for it to do anything – it won’t do anything by itself!

31 | P a g e

Execution Flow

Without running your app, it may not be clear how the Triggers and Actions function together –this section

aims to explain some ambiguities.

Triggers are independent of each other

The Actions in one Trigger will not affect those within another Trigger. This can be useful, but confusing. Look

at this example – when the user presses ‘Delayed action’, this will snooze for 20 minutes before sending a

prompt. However, this will not snooze Actions in the other Trigger, so surveys may still be sent during this 20-

minute snooze time.

Similarly, when the user presses the ‘Start loop’ button in this example, the two Actions within the While

Statement will continue to execute so long as ‘number’ is less than 10. However, Actions in any other Trigger

are free to execute independently of this loop, so surveys can still be sent in this case, too.

Actions execute in sequence

All Actions within a Trigger will execute from top to bottom. Take the (fairly useless) example on the left - first,

the ‘number’ Attribute is set to 5, then the user is prompted with the text ‘first’. After a minute, the user is again

prompted with the text ‘second’ and ‘number’ is set back to 0.

32 | P a g e

The only exception to this occurs in the use of Conditional Statements, as shown in the right-hand example.

Here, the user receives the ‘first’ prompt, but may receive the ‘second’ prompt many times before finally

receiving the ‘third’ prompt.

Survey actions won’t wait until you’re done

Once a survey is sent with the Send Survey Action, execution

carries on – it won’t wait until the user finishes the survey before

executing the next Actions. In this example, Survey 2 will be sent

immediately after Survey 1.

If instead you only want to send Survey 2 after Survey 1 is

completed (or perform any other Actions after Survey 1 is

completed) you can use the Survey Trigger as shown in the

example below.

33 | P a g e

Monitoring User Data

When your participant completes a survey, their data is transmitted in real-time to the server and is then

accessible through the User Data pane of Jeeves. This section describes this pane and how to access and

respond to incoming user data.

As can be seen in Figure 7, the top part of the User Data pane displays both a list of users enrolled in the study,

and a list of surveys available for them to complete. By selecting a user and a survey from these lists, you can

view data on the number of times a given user has completed/missed a survey, how long it takes them to

complete it on average, and how this time compares to other users.

Figure 7 - Screenshot of the User Data pane

Downloading Data

The Data Download section allows users’ survey data to be download in Excel (.xls) format, a screenshot of

which is shown in Figure 8.

A separate sheet is created for each survey in the specification. The first column in each sheet gives the

timestamp of survey completion, and further columns represent a user’s answers to the survey questions at this

particular time.

Further, if ‘All Users’ is selected, an additional column titled ‘User ID’ is added to distinguish the different users

whose entries are listed in the sheet.

The example below shows data for all users and all surveys; note the ‘User ID’ column to distinguish each user’s

entry, and the various sheets including ‘InfoZust’, ‘Before’, etc. to indicate the different surveys.

34 | P a g e

Figure 8 - Example Excel survey data

Note: one known issue with this implementation is that, if you add an additional question to your survey

during the study, the answers in survey rows before this addition will then be misaligned with their questions. If

possible, try not to add questions to the middle of your question list during data collection!

Sending/Receiving Feedback

You may notice that one of your users is not completing surveys -

or is taking a particularly long time to do so. Jeeves allows you to

send and receive messages from your users on an individual

basis, or send a study-wide message to all your users. Your users

can access and send messages by pressing the ‘Messages’ button

on the main screen, as shown in the adjacent screenshots.

The Feedback section of the User Data pane presents a

timestamped conversation for a selected user.

To reply to this user alone, the Message selected user text box and

corresponding button will allow 1-to-1 communication.

If you need to send a message to all users (for example, to notify

them about an emergency study update or to resolve a common

issue) use the Message all users text box and button.

35 | P a g e

Updating Users’ Schedule

When describing the different Actions of Jeeves, the Update Waking Schedule Action was mentioned. This

section explain what a user’s waking schedule is, and how it is updated.

For most studies, you can probably employ static dates/times, or allow your users to update waking/sleeping

times through surveys. However, if your users have a special pattern of times that they will be available

(through work schedules, for example) then they can pre-program a fixed schedule for themselves that spans

multiple days, without having to constantly update their new available times every day!

The Update Waking Schedule Action sends users a special type of survey that asks the following:

- A scheduled start date

- A scheduled end date

- Multiple wake and sleep times that cover the entire study schedule (as determined by the start and end

dates).

Special constraints are added to this survey – the user’s end date must be after their start date (Figure 9), their

sleep time on a given ‘day’ must be after their wake time, and their wake time on a given day must be after

their sleep time on the previous day (Figure 10).

Figure 9 - End date must be after the start date

36 | P a g e

Figure 10 - Sleep time must be after last wake time, and wake time after last sleep time

Figure 11 - Wake/sleep questions are asked to cover the study schedule

After the user completes this survey, the app can now store appropriate dates and times at which to send

prompts or surveys.

Figure 12 - Appropriate times to prompt the user (orange blocks) are calculated

37 | P a g e

When you drag the Update Waking Schedule Action into your specification, a pop-up appears asking you to

name special Attributes for scheduling (Figure 13, left). Give these names and click ‘Add attributes’, and four

new Attributes will automatically be created (Figure 13, right). These cannot be deleted or edited.

Figure 13 - Scheduling Attributes are automatically created

When the user completes their waking schedule survey, their selected start and end dates are assigned to the

created and Attributes.

The wake and sleep times they entered for Day 1 are assigned to and

respectively. Then, at the end of Day 1, they are automatically reassigned to the wake and sleep times entered

for Day 2. At the end of Day 2, they are reassigned to the times of Day 3, and so on.

This means that, if you create a Trigger that uses these four attributes like so…

…it is guaranteed to send the ‘Hello’ prompt 8 times within each of the ‘day’ windows illustrated in Figure 12.

Since it only makes sense to use these scheduling Attributes together, you can autofill them into a time-based

Trigger by right-clicking on it and selecting ‘Set to waking schedule’ (Figure 14, left). This will add these

Attributes to the Trigger automatically and prevent them from being accidentally removed (Figure 14, right). To

reset the Trigger, simply right-click on it again and select ‘Remove waking schedule’.

38 | P a g e

Figure 14 - Triggers can be easily set to the waking schedule

As can be seen in Figure 7, the user’s selected schedule can be observed in the ‘User schedule’ table. From this

table, you can also update the user’s schedule (if, for example, they have made a mistake and are unable to

access the scheduling survey again).

Double-click on a table cell to edit its date/time, then press the ‘Update user schedule’ button, as shown in

Figure 15.

Figure 15 - Process of updating a user's schedule

If you have incorrectly formatted the date/time, it will appear in red

and you will be unable to update the schedule (in the example, a

slash is missing between the month and year).

Note that there are no other constraints on waking and sleeping

times, so please edit these with care!