Deploying form definitions and server datasets

Form designs and data collection workflows can be downloaded, and the workflow can be re-deployed later using those same files, even on a different server. This functionality allows us to distribute samples, and for SurveyCTO users to save and share their work. In this article, you'll learn how to deploy forms and data collection workflows from definition files.

Order of deployment is important, so please follow the order of this article. You cannot deploy a server dataset that's attached to a form, or has publishing set up from a form, until that form has been deployed.

A form definition spreadsheet is a single spreadsheet file for a single form, specifying fields, groups, choices, and more (to learn more, check out our documentation on designing forms). A data collection workflow involves multiple, related files, and it can include form definitions, dataset definitions, and/or server dataset data files.

1. Readying the files

Have the files ready for upload. They can either be files saved on your computer, or files saved in Google Drive. We distribute most sample forms via Google Drive; we suggest you make your own copy of the files.

Save a single form definition

To save your own copy of a form definition spreadsheet, open the file, and in the upper-left, click File > Make a copy, and follow the prompts. If you prefer to download it to your computer, click File > Download > Microsoft Excel (.xlsx), and the file will download as an Excel file.

Save a workflow

To save a copy of multiple files (in the case of SurveyCTO workflows) to your own Google Drive, select all of the files (either Ctrl/Cmd + A, or highlight all files) right-click the selection, and click Make a copy, and the files will be saved to your drive. If you'd like, you can then go to your drive, and move the files to a folder.

Alternatively, to download the whole Google Drive folder to your computer, click the folder name in Google Drive (on the top, to the right of Shared with me), and then click Download; the files will be compressed into a ZIP file, and then downloaded. You can also right-click each file and click Download.

It is possible to upload form files to your server after simply opening them in Google Drive, but they are easier to upload if you have your own copy, and you can also change the copy to fit your needs.

2. Deploy form definitions

For a video demonstrating how to deploy form definitions, check out How to deploy a spreadsheet form definition.

For each form definition spreadsheet (there may only be one), whether it is a Microsoft Excel file or a Google Sheet, follow these steps:

Login to your SurveyCTO server console, and go to the Design tab.
Click on a "+" button on the left.
1. If you have not yet uploaded any forms, click on Add your first form.
Click on Upload form definition.
If the form definition is saved on your computer, click Select from your computer. If the form definition is saved in Google Drive, click Select from Google Drive.
1. You can also drag-and-drop the file from your computer to the indicated region, then skip to step 6.
Find and select the form definition you would like to upload.
If there are form attachments (such as .csv files, images, or field plug-ins, but not server datasets, which we'll get to later), to the left of Attach files, set the switch to YES. Then, either click Select from your computer or Select from Google Drive, and select the file you would like to attach.
1. If there are multiple attachments, you can highlight multiple files and click Open (or Select), or drag them over. You can also attach them later (see section 2.1 below).
Click Upload.

2.1 Attaching additional files

If there are additional files to attach to an already deployed form (other than server datasets), follow these steps:

On the Design tab, for the form that was just deployed, click Edit.
In the tab that opens, on the top, click Form settings.
Click Manage attachments.
Click Attach files.
Either click one of the buttons to select files from your computer or Google Drive, or drag the files from your computer to the box. Repeat this step until all of the files have been attached.
Click Save when you are done.
On the top, click Save, then Save and deploy.

Repeat these steps for each form definition.

You can also add more attachments on the Design tab by updating the already deployed form by going to the form and clicking Upload. With this method, you must upload a new version of the form with a more advanced version number (even if it contains no actual changes). Also, either enable or disable the Keep existing file attachments option, depending on what you're trying to do.

3. Deploy server datasets, including cases datasets

If the forms use server datasets (including a case management server datasets), upload them after the form definitions have been deployed. Dataset definitions contain information about which forms they are attached to, as well as how dataset publishing is set up.

Log into your SurveyCTO server console, and go to the Design tab.
Click on a "+" button on the left.
Click on Add server dataset.
Pick the New dataset from definition option.
If the form definition is saved in Google Drive, click Upload from Google Drive.
Click on +Select file, and pick the dataset definition .xml file.
Click on Upload a dataset definition.

Repeat these steps for each dataset definition.

4. Populate the server datasets

When you first upload the server datasets, they will be empty. If the dataset definition came with a .csv file, follow these steps to populate the datasets with data.

Log into your SurveyCTO server console, and go to the Design tab.
Under the title of one of the server datasets, click on Upload.
If the form definition is saved in Google Drive, click Upload from Google Drive.
Under File with new dataset contents, click on +Select file, and pick the .csv file that contains the dataset data.
Append, merge, or replace are fine (it doesn't matter when it is empty).
Click on Upload.

Repeat these steps for each server dataset.