Guide to case management part 7: Example - Publishing to a case, and retrieving from that case – SurveyCTO Support Center

This article is part 7 of a series on case management. See the bottom of this article for the other parts in this series.

In this article, we walk you through adding a case management system, and trying it for yourself. Read on, deploy the sample form, and test it to learn more.

Resources

The resources for this example can be found in this folder, and deploy them to your server. If you are not familiar with deploying forms or server datasets, check out our support article on deploying form definitions and server datasets.

Here is a list of the files in that folder:

	Component	List of files
	Form definition	Complaint follow-up, New complaint, School form, Water usage
	Server dataset definition	Example cases definition.xml
	>Server dataset records	Example cases data.csv

You can only have one case management dataset with the ID "cases" on your server at a time. Skip to Working with a basic case if you do not have a case management dataset with the ID "cases" deployed. If you already have a cases dataset, there are two options:

Also note that if you are working on a server with multiple teams, you may not be able to see every case management dataset's ID, depending on your permissions. You may need to coordinate with colleagues on the best course of action. Each form and server dataset must have a different ID, even if the other form or server dataset is part of a different team.

Adding a second cases server dataset

Option 1: Backup and delete the current cases server dataset

If the existing case management dataset is not being actively used, download BOTH the XML definition and CSV data (see working between servers, section 2.2 Downloading dataset definitions and data), then delete the dataset from the server. Be absolutely sure the data is safely backed up, and it is not currently needed on the server. For more information, check out our support article on purging data on your server.

Option 2: Use an alternative cases dataset name

In the example server dataset definition XML file, change the dataset ID, set up a user role that uses that dataset ID for its cases dataset, add a user to that user role, and test using that user.

To learn more about editing the XML dataset definition, check out our support article on working with server dataset XML files, but you can also follow these steps:

Open the XML file in a text editor.
Between the and tags, highlight "cases"
Replace that with a new case ID, such as "example_cases".
Save the file. This will be the server dataset definition you upload to your server instead of the original.
On the server console, go to the Configure tab.
Create a new user role. For its Please provide the dataset ID for case management, use the updated dataset ID entered in step 3. For more information, check out part 5.
Either create a new data collection user with this user role, or edit an existing user and change its role to the new user role (note that you cannot change user roles for non-email usernames).
In each form definition part of the example workflow, in the pulldata() expressions, replace 'cases' with the new case ID (for example, if the new dataset ID is 'example_cases', replace all instances of 'cases' with 'example_cases', single quotes included). Most spreadsheet applications have a Find and replace tool you can use to do this automatically.
When testing this case management system, log into SurveyCTO Collect (or web forms) as the above user. That way, their Manage Cases menu will use your new case management dataset.

Working with a basic case

Viewing a case

First, take a look at the Cases dataset by going to its dataset and selecting Edit. It will look something like this:

You can scroll down to see the other cases as well.

Next, open your SurveyCTO Collect app, and open Manage Cases (if it is not available, check out part 6 of this series, section Troubleshooting). Something you’ll notice is that the order of the cases is different than the order you saw on the server. This is because the complaint cases have a sortby value of 2, while the other case has no sortby value, so the complaints go to the bottom. If you take a look at the "New complaint" form, you’ll notice a field called sort, a calculate field that is always equal to 2. This field is set to publish to the case management dataset column sortby so complaint cases are always grouped and sorted like this.

To start, open the first case there, called PS #1036 (case ID school-ps1036). This is a case where the assigned forms forms do not work with each other, but are simply assigned to the same case; here they each deal with the school called PS #1036 (short for "Public School Number 1036). There are two forms there; open the first one, called School form. The first question is automatically able to display the label of the case by using these fields:

type	name	label	calculation
calculate	school_name		pulldata('cases', 'label', 'id', ${caseid})
select_one yesno	confirmation </td style="border:solid black 1px">	Are you currently at ${school_name}?

The above is an excerpt from the sample form in spreadsheet template format. Even if you prefer the online form designer, you can identify the relevant field properties using the top row.

Here, the field "school_name" is using the pulldata() function to pull the label from the 'cases' server dataset, and it is being displayed in the field "confirmation". A cases dataset can be treated just like any other dataset; so as long as the dataset is attached, you can pre-load data from it, no problem. Both the School and Water forms use this or a similar field to call for the label of the case, which in this example, is the name of the school.

Adding a case

Try this to practice adding a new case manually:

For the Cases dataset on the Design tab, click Edit.
Click the blue + Add row button near the bottom.
In the first column, 'id', enter an identifier for a school. For example, you can enter school-ps1037.
In the next column, 'label', enter the name of your imaginary school.
For the third column, copy and paste in what is in the row above: school_form, water_usage
Click the Save button on the left.

Congratulations, you just added a case! Go back into the Collect app, open Manage Cases, tap Refresh, and your new case should appear (if it does not, make sure you are connected to the internet, and then try again in a few minutes).

Since the form definitions use the pulldata() function to pull data from the cases server dataset, you will need to update the form definition so it can retrieve the latest dataset data; to learn more, check out our support article on using data from another form, section 3. Device setup. That way, when you go into your new case and fill out the forms, the fake school name you created will appear.

Testing a form used in a case

Follow the details in part 6, section Testing a form used in a case to test one of the forms. For example, to test the form "Complaint follow-up" with the case ID complaint-139, go to this URL:

https://servername.surveycto.com/forms/complaint_followup/designer.html?view=test&caseid=complaint-139

(Make sure you replace "servername" with the name of your server.)

Advanced workflow: Publishing to a cases dataset

Instead of manually adding or editing cases, you can use server dataset publishing to dynamically update your cases dataset data whenever an enumerator submits a form instance (as discussed in part 4). In addition to the three required columns and the three optional columns, you can also publish data to other columns of the server dataset, and retrieve it later with the pulldata() function.

For example, let’s say you are logging a complaint, and you would like to check up later to see if that complaint has been resolved. In the Collect app, open and fill in the blank form "New complaint" (not from the case), and answer a few questions about a made up complaint (for the complaint ID, enter some random integer). Once you are done, send the finalized form to the server. Go into Manage Cases, refresh, and your new case will appear!

How does this work, you might ask? For the cases dataset on the Design tab of the server console, click Publish into. Then, for "New complaint", click Edit.

Clicked Publish into.

Clicked Edit.

You will be able to see the list of field mappings. On the left is a list of fields in the form definition, and on the right is the list of server dataset columns they publish into. Most importantly, look at the top two field mappings. Those fields are designed like this in the form design (you can see this in the form definition spreadsheet):

type	name	label	calculation
text	id_num	Enumerator: Enter the numeric complaint ID assigned to this case:
calculate	id		concat('complaint-', ${id_num})
text	complaint_label	In 30 characters or fewer, give this complaint a relevant title:

When you enter the complaint ID, it is concatenated to the end of ‘complaint-’, which is used as the new case id; this will be published to the 'id' column of the server dataset to be the new case id. For example, if the field "id_num" has a value of 1234, then the value of the field "id" will be complaint-1234, and that will be the case ID of the new case. Then, the value entered for the field "complaint_label" is saved as the label of the case.

Also, the calculate field that publishes into the 'formids' column has a simple calculation of 'complaint_followup'. That way, the form with that form ID will be immediately assigned to that case. Similarly, the column sortby is explicitly defined as 2 by the field sort. The other field mappings are for storing other pieces of data that will also be used in the case.

type	name	calculation
calculate	for_complaint_followup	'complaint_followup'
calculate	sort	2

With your new knowledge, try creating a few more complaint cases, and see how the data you entered appears in the cases dataset and the Manage Cases menu.

Retrieving updated dataset data in SurveyCTO Collect

Now that you have created a new complaint case, if you would like to fill out the follow-up form through case management, you will need to download the updated dataset data to the device, including the description of the complaint, visit number, etc. Remember: even if you refresh the Manage Cases menu, it does not mean the form has the latest dataset data. So, you will need to download that data.

To set up a device to download that data automatically, check out our support article on using data from another form, section 3. Device setup.

To download the data manually, follow these steps:

Go back to the Collect app. Go to Get Blank Form, and get the form with the title Complaint follow-up (it may be easier to just get all available forms).
Go into Manage Cases, go to your newly added case, and open the form assigned there. You will be able to see information from the original complaint, and update it with new information.
Complete the form, and submit it to the server.
Check the cases dataset, and you’ll see that it has been updated again!

You can repeat these steps to keep updating the complaint as needed.

Guide to case management part 7: Example - Publishing to a case, and retrieving from that case