Guide to case management part 2: Creating cases

This article is part 2 of our series on case management. See the bottom of this article for the other parts in this series. You can also check out our webinar on case management; skip to 8:44 to learn how to create cases for your case management workflow.

In this article, we discuss the basics of a case management server dataset, and how to create and edit cases. See the bottom of this article for the other parts in this series.

In this series of articles, we refer to "case management server dataset", "cases server dataset", and "cases dataset". They all mean the exact same thing.

Creating the cases server dataset

To create a cases dataset, simply create a server dataset with the dataset ID "cases", and add the needed columns. On the server console, SurveyCTO can set this up for you:

On the Design tab, click on a plus + on the left for Add form, group or dataset.
Click the Add server dataset button.
Select the tab for New dataset for cases.
Since there is only one dataset for case management by default, leave the default dataset title and ID. If you would like to use a different dataset ID, check out part 5 of this series, Adding multiple cases datasets.
Select how it will be displayed to the enumerators (this can be changed later; for more information, check out part 3 of this series, section Case management views):

Tree list: Cases are displayed as a tree, with a list of available cases, and with the forms assigned to each case listed underneath (keep this selected if you are a beginner).
Table: Cases are displayed as a table, and can include dataset headers and other info. When a case is selected, it will open a tree of that case only.

Optional: Select an enumerator dataset to use with case management. We will discuss this in detail later.
Click Create dataset.
When you go to add cases, each case will be a row in this server dataset (see Generating cases below for more information).

After going to the New dataset for cases tab, just click Create dataset, and the case management dataset will be created!

Column headers

Here is what a case management dataset might look like:

Here is the data in that dataset, so it is easier to read:

id	label	formids	users	roles	sortby	enumerators
1001	Case 1001	water_management, real_estate	collector1
1002	Case 1002	water_management		data_collectors
1003	Case 1003	water_management, water_backcheck	collector6
1004	Case 1004	water_management, real_estate, water_backcheck, real_estate_backcheck		data_collectors, managers		100001

Your cases dataset needs to include the column headers 'id', 'label', 'formids', 'users', and 'roles'. The 'sortby' and 'enumerators' columns are optional, but it is a good idea to include them, just in case you need them later. All cases need an 'id', 'label', and 'formids' value, and the others are optional.

id: This will be the unique identifier column, used to identify each case. When you add cases to the dataset, each case should have a different id. The "caseid" field in a form will be filled automatically with the corresponding case's id value when opening a blank form from the case list (i.e. the Manage Cases menu). Learn more in part 4 section The "caseid" field.

label: A user-friendly name for the case.

formids: The form ID of each form that is a part of this case, with each separated by a comma.

Example 1: water_management

Example 2: formid1, hh_listing_2, household_form

Tip: To make them easier to read, form IDs can also be separated by a comma-space, as you can see in example 2.

Note: When using Android devices for data collection, ensure that the formids column is populated for the Cases dataset to function properly. Although this is not required for iOS and web forms, it is still best practice to keep the formids field populated.

users (optional): List of users who will be able to see this case, with each user separated by a comma. If this value is blank, then all users will be able to see this case, unless roles or enumerators (see below) are specified.

Example: collector, user@example.com

If this column has a value, but no real usernames, then no data collectors will be able to view the case.

roles (optional): List of user roles whose members can see that case. If blank, then all users will be able to see this case, unless users or enumerators are specified. If this column has a value, but no real user roles, then no data collectors will be able to view the case.

sortby (optional): A numeric value by which cases will be sorted in the Manage Cases menu, from low to high. If blank, then they will be first on the list, then sorted by their id.

enumerators (optional): List of enumerators who will be able to view that case (check out our documentation on managing enumerators to learn more). If blank, then all users will be able to see this case, unless users or roles are specified. If this column has a value, but no real enumerator IDs, then no data collectors will be able to view the case. If you are going to use the enumerators property, you will need to attach an enumerator dataset to the cases dataset, as discussed in Enumerator management below.

The users, roles, and enumerators properties can be used to hide cases from all data collectors. To learn more, check out part 4 of this series, section Closing cases.

Note that while users and roles are optional in that you don't have to specify these for a case, a case management dataset must include these columns, even if they're empty. Otherwise case management will not work correctly.

While the column headers above are the ones used for case management, you can also add additional columns to the cases server dataset. We will talk about this more in part 4.

Generating new cases

There are a few ways to generate cases.

These methods can also be used for working with non-cases server datasets, whether you are adding rows, or editing its data.

Method 1: Creating cases manually

You can add cases row-by-row, like you would any other server dataset.

On the Design tab, scroll to the cases server dataset and click Edit.
In the table that appears, click Add row in the lower-left corner.
In the popup that appears, enter the new case data.
Click Add row in the lower-left, and the case data will be added.

This new case has an id value of "101", a label value of "Case 101" and the forms with the form IDs "form1" and "form2" are assigned to it. The users, roles, and enumerators properties are blank, so all data collectors will be able to see this case. Click Add row, and the case will be added!

Method 2: Manually uploading new cases

The most common way of creating cases is by uploading externally generated data. This allows you to quickly and easily add multiple cases at once.

Create a CSV file or Excel workbook with the headers a cases dataset needs (see Column headers above for details).
Add a row for each case. Ensure each case has a different id value, which should also be different from any id values already in the cases dataset.
Also make sure the case has at least a label and a formids value (the bare minimum together with an id value).
Go to the server dataset on the Design tab, and click Upload.
Click Select file.

If your CSV file or Excel workbook is stored in Google Drive, first click Upload from Google Drive.

Select the file containing your cases.
Select Append, then click Upload.

Case data from the file "new_cases.csv" is about to be added. Click Upload, and those cases will be added!

If you are having trouble preparing the upload data, check out our support article on how to upload external data.

When you add a CSV file to a server dataset, such as the cases server dataset, you will have three options:

Append: All data rows in the CSV file are added as new rows to the server dataset.

Merge: You will state which column of the server dataset is the unique identifier column; the unique identifier column in the uploaded data must have the same name. If the unique identifier of a row in the CSV matches the unique identifier of a row in the server dataset, then that row in the server dataset will be replaced by the CSV row. Otherwise, it will be added as a new row.

Replace: All rows (except for the header row) in the server dataset are removed, and replaced with the data rows in the CSV file.

Method 3: Automatically creating cases through publishing

If a form is configured to publish data into a case management server dataset, that data can be added as a new row in the server dataset, creating a new case. Those cases can be worked on immediately, and they can even be transferred to other collection devices without connecting to the Internet. To learn more, check out part 4 of our case management series, sections Publishing data to cases and Offline cases and data.

Editing cases

The methods to edit a case are very similar to the methods used to generate a new case.

Method 1: Editing cases manually

On the Design tab, for the cases server dataset, click Edit.
In the table that appears, go to the case you would like to change, and click Edit.
Change the case data as needed.
Click Save on the left when you are satisfied with your changes.

Method 2: Manually uploading outside data

Create a CSV file or Excel workbook with the headers a cases dataset needs.

It may be easier to go to the cases dataset on the Design tab, and then download that data using the Download button. You can then work from the CSV file that is downloaded.

In the 'id' column, use the case id of the case you would like to change.
In the other columns of that row, add data to the columns you would like to change. If you leave a column blank, it will not be updated (i.e. if the value is blank in the CSV file, the value in the current dataset will not be changed).
Repeat steps 2-3 for each case you would like to change, and save the CSV file.
Go to the server dataset on the Design tab, and click Upload.
Click Select file.

If your CSV file is stored in Google Drive, first click Upload from Google Drive.

Select the CSV file.
Select Merge, then click Upload.

Method 3: Automated dataset publishing

You can also use dataset publishing to update a case. To learn how, check out part 4 of our case management series, section Publishing data to cases.

Enumerator management

If you are going to use the enumerators property in your form, you will need to attach an enumerator dataset to your cases dataset, so it knows which dataset to get its list of enumerators from. The attached enumerator dataset determines which enumerators can be selected in the Manage Cases menu of SurveyCTO Collect.

As mentioned above in Creating the cases server dataset (step 6), you can select the enumerator dataset when you first create the enumerator dataset. If you want to attach an enumerator dataset later, or change which enumerator dataset is attached, on the Design tab, simply go to the cases dataset, click Settings, and from there, you can change the Linked enumerator dataset and other settings.

There are two more settings you can change customize:

Other user code: Code the enumerator has to enter to show hidden enumerators.

Entry mode: Which Entry mode for selecting an enumerator will appear by default.

We will discuss this more in part 3, section Enumerator selection.

You can learn more, including how user codes and entry modes work, in our documentation on managing enumerators.