Setting up a case list · Joripo documentation

Each workspace has at most one case list. It is a server dataset marked as the case list, so it can also be downloaded and attached to forms like any other dataset. Only owners and managers open a workspace's Cases page.

The set-up wizard

Set up case management (on Cases, also linked from Collect) builds the list from any spreadsheet in three steps:

Your beneficiary list: upload a .csv or .xlsx, or pick a dataset the workspace already has, such as the preload a form already reads.
Which column is which: the column holding each case's ID and the name shown for it (both guessed for you), the details to keep, the survey form the cases are interviewed with (a form with a caseid field is chosen for you), an optional name for the round, and who gets each case: everyone, a column of email addresses or usernames (several names make a team), or enumerators you choose.
Check and import: the wizard checks the list again and Import and publish to phones makes it the case list.

Nothing is written while a case ID is missing or used twice, a column you mapped is not in the file, an ID is longer than 200 characters, or the form is not deployed. Warnings (a case with no name, a case given to nobody, a name nobody collecting in the workspace has) do not stop the import, and are listed.

Running the wizard again updates the list: new cases are added, known ones updated, and cases missing from the file are kept unless you tick that they should be removed. Whether a case has been interviewed is kept apart from the list, so an update never resets or duplicates a completed case.

The columns of a case list

Under the wizard, the list has the SurveyCTO-compatible case-list columns. You can also upload a list already in this form, under Advanced.

Column	Required	Holds
`id`	yes	The case's own identifier, present and different for every case.
`label`	yes	What the enumerator sees, such as "Household 12". If blank, the phone shows the ID.
`formids`	yes	The form IDs this case opens, separated by spaces.
`users`	yes (may be empty)	Who sees the case: email addresses or usernames, separated by spaces. Empty means everyone.
`sortby`	no	The order of the list on the phone; numbers are compared as numbers.
anything else	no	Sent to the phone with the case. Forms can read these columns with `pulldata()` or `search()`.

Uploading new data in this form merges on id by default (known cases updated, others added); you can also add every row, or replace the whole list. A missing required column, or an ID that is blank or repeated, is refused and the list stays as it was.

Who gets a case

The users column names people by their full email address, or by a username (the part before the @) when exactly one person in your organisation has it. A username two people share gives the case to neither of them: the Cases page says so, as does every upload, the wizard and Give them. Write the full email to be sure. A data collector who signs in with a bare username is always named by it exactly.

A case open to everyone reaches every phone in the workspace. A device key that belongs to no person (one made for ODK Collect, or a shared phone) receives only the cases open to everyone.

Making a form case-aware

Add one row to each form a case opens:

type	name
`caseid`	`caseid`

The field may have any name (id, hhid): the server finds it by its type. When the form is opened from a case on Joripo Collect, the field holds the case's ID; opened any other way (and always in ODK Collect), it is blank. Use it like any field, for example pulldata('cases', 'village', 'id', ${caseid}) once the case list is attached to the form.

A known limit: a form that has the case list attached for pulldata() holds a copy of it. Updates from submitted data reach the phones' case list straight away, but reach that attached copy only when the dataset is uploaded again or re-attached.

Stopping

Stop using this case list removes the mark: the data stays as an ordinary dataset, phones stop showing cases at their next check, and another list can take its place. The case list cannot be deleted while it is the case list, because phones would lose every case; stop using it first.