# Surveys {#surveys}


Surveys (also called **forms**) are the data collection instruments your team fills out in the browser or the mobile field app. Every survey is created **inside a project**, and every project belongs to a **workspace**. This page is the hub for creating and managing them.


## Where Forms Live: Workspaces → Projects → Forms {#where-forms-live-workspaces--projects--forms}


Before you create a form, set up the structure that will hold it. The hierarchy is fixed and is enforced when you create a form:

```
Workspace  (team / organisation unit)
└── Project  (initiative / study)
    └── Form / Survey  (the questionnaire you design and publish)
        └── Responses  (data collected from the published form)
```

- A **Workspace** groups related projects for a team or programme. See [Workspaces](/user-manual/workspaces.md).
- A **Project** groups related forms for a single initiative. See [Projects](/user-manual/projects.md).
- A **Form (Survey)** is the questionnaire itself, built in the [Survey Designer](/user-manual/survey-designer.md).

You **cannot** create a form without a project. If the **Project** dropdown in the Create Form dialog is empty, create a project first (Workspaces → **View Projects** → **Create Project**), then return to this page.


### Navigating down the hierarchy {#navigating-down-the-hierarchy}


| You are here | Go to the next level by |
|--------------|-------------------------|
| Workspaces | Click **View Projects** on a workspace |
| Projects | Click **Create Survey** (or **Forms** in a project) to add a form |
| Surveys | Open a form with **Design Form** to edit it in the [Survey Designer](/user-manual/survey-designer.md) |

You can also deep-link straight into the Create Form dialog for a specific project by opening `/surveys?project_id=<project-id>`. The dialog pre-selects that project. If the ID is invalid, a warning appears and you must choose a project manually.


## Page Overview {#page-overview}



### What the page is for {#what-the-page-is-for}
The Surveys page is your central hub for creating, managing, and organizing all your data collection forms. From here you can create new surveys, import existing ones, browse templates, and manage your survey library.


### When a user would use it {#when-a-user-would-use-it}
- When you want to create a new survey from scratch
- When you need to import an XLSForm
- When you want to browse and use templates
- When you need to view, edit, or manage existing surveys
- When you want to filter surveys by status, tags, workspace, or project


## How to Access This Page {#how-to-access-this-page}



### Navigation path from the main app {#navigation-path-from-the-main-app}
1. Log in to the application
2. From the main dashboard, use the sidebar navigation to click on "Surveys"
3. Or, directly navigate to `/surveys` in your browser


### Permissions or prerequisites {#permissions-or-prerequisites}
- You must be logged in to access this page
- You need appropriate permissions to create, edit, or delete surveys
- The action buttons will be disabled if you don't have the required permissions


## Page Layout {#page-layout}



### Header / title {#header--title}
- **Title**: "Surveys"
- **Subtitle**: "Create and manage your data collection forms"
- **Buttons** (left to right):
  - **Create Survey**: Creates a new survey from scratch
  - **Import XLSForm**: Imports a survey from an XLSForm file
  - **Browse Templates**: Opens the template browser to use pre-built surveys


### Status filters {#status-filters}
Tabs to filter surveys by status:
- **All**: Shows all surveys
- **Active**: Shows only published surveys
- **Draft**: Shows only draft surveys
- **Archived**: Shows only archived surveys


### Filter and management section {#filter-and-management-section}
- **Filter by tag**: Dropdown to filter surveys by tags
- **Manage Tags**: Button to open the tag management dialog
- **Clear**: Button to clear tag filter (appears when tag is selected)
- **All Workspaces**: Dropdown to filter by workspace (appears when multiple workspaces exist)
- **All Projects**: Dropdown to filter by project
- **Clear**: Button to clear workspace and project filters (appears when any are selected)


### Table {#table}
The table shows a list of surveys with these columns (left to right):
1. **Name**: The survey name
2. **Description**: A short description (shows "-" if empty)
3. **Tags**: Colored badges showing tags assigned to the survey
4. **Status**: Badge showing survey status:
   - Draft (gray)
   - Published (blue)
   - Archived (outline)
   - Deleted (red)
5. **Availability**: Shows if the survey is always available, scheduled, etc.
6. **Created**: Date the survey was created
7. **Actions**: Menu with available actions


### Action menu (per survey) {#action-menu-per-survey}
Clicking on the three-dot icon (⋮) next to a survey opens a dropdown menu with these options:
- **Design Form**: Opens the survey designer
- **Manage Versions**: Opens version management dialog
- **View Data**: Navigates to survey responses
- **Manage Access**: Opens the Access Management page
- **Edit Details**: Opens edit survey details dialog
- **Clone**: Creates a clone of the survey
- **Publish** (only for Draft): Publishes the survey
- **Unpublish** (only for Published): Unpublishes the survey
- **Archive** (only for Published): Archives the survey
- **Delete**: Opens delete confirmation dialog


## Step-by-Step Tasks {#step-by-step-tasks}



### Creating a Survey {#creating-a-survey}
1. Click the **Create Survey** button at the top of the page.
2. In the **Create New Form** dialog, fill in the details (see the field reference below).
3. Choose a **Project** — this is required and determines which workspace the form belongs to.
4. Click **Create Form**.
5. The [Survey Designer](/user-manual/survey-designer.md) opens automatically on the new form.

If your plan's active-form limit is reached, the dialog shows a plan limit banner and the **Create Form** button is disabled. Delete an existing form or ask a billing administrator to review the plan.


### Create New Form dialog — field reference {#create-new-form-dialog--field-reference}


| Field | Required | What it does |
|-------|----------|--------------|
| **Form Name** | Yes | The display title of the form. A live character counter shows the remaining allowance. |
| **Description** | No | A short description shown on the Surveys list and at the top of the form in Preview. |
| **Project** | Yes | Select the project that will own this form. Projects are listed across all your workspaces, with the workspace name shown in parentheses. A confirmation line appears below ("Selected: *name* from workspace *workspace*"). |
| **Anonymous responses** | No | When enabled, responses are not linked to the logged-in respondent's identity. |
| **Allow multiple responses** | No | When enabled, the same respondent can submit the form more than once. |
| **Schedule form (auto open/close)** | No | Enables an availability window. When checked, two date-time fields appear. |
| **Opens at** | No | When the form becomes available. Cannot be set in the past. |
| **Closes at** | No | When the form stops accepting responses. Disabled until **Opens at** is set, and cannot be earlier than the open time. |
| **Tags** | No | Click tag pills to attach existing tags to the form for organisation and filtering. |

Buttons: **Cancel** closes the dialog without creating anything; **Create Form** creates the survey and opens the designer. While saving, the button shows **Creating…**.

> A form is created as a **Draft**. It will not accept responses until you [publish](/user-manual/survey-designer.md) it.


### Importing an XLSForm {#importing-an-xlsform}
1. Click the "Import XLSForm" button
2. Select your XLSForm file
3. Follow the import prompts
4. Once imported, you'll be taken to the survey designer


### Browsing and Using Templates {#browsing-and-using-templates}
1. Click the "Browse Templates" button
2. Browse the template library
3. Select a template to use
4. A new survey will be created from the template


### Filtering Surveys {#filtering-surveys}
**By status**:
1. Click on one of the status tabs (All, Active, Draft, Archived)
2. The table will update to show only matching surveys

**By tag**:
1. Click the "Filter by tag" dropdown
2. Select a tag from the list
3. The table will update to show only surveys with that tag
4. Click "Clear" to remove the filter

**By workspace or project**:
1. Click the "All Workspaces" dropdown and select a workspace (if multiple)
2. Click the "All Projects" dropdown and select a project
3. The table will update to show only surveys in that workspace/project
4. Click "Clear" to remove the filters


### Editing Survey Details {#editing-survey-details}
1. Find the survey in the table
2. Click the three-dot menu icon (⋮)
3. Select "Edit Details"
4. Update the name, description, or other details
5. Click "Save Changes"


### Publishing a Survey {#publishing-a-survey}
1. Find a Draft survey
2. Click the three-dot menu icon (⋮)
3. Select "Publish"
4. The survey status will change to Published


### Unpublishing a Survey {#unpublishing-a-survey}
1. Find a Published survey
2. Click the three-dot menu icon (⋮)
3. Select "Unpublish"
4. The survey status will change to Draft


### Archiving a Survey {#archiving-a-survey}
1. Find a Published survey
2. Click the three-dot menu icon (⋮)
3. Select "Archive"
4. The survey status will change to Archived


### Deleting a Survey {#deleting-a-survey}
1. Find the survey you want to delete
2. Click the three-dot menu icon (⋮)
3. Select "Delete"
4. Confirm the deletion in the dialog
5. The survey will be removed


### Managing Tags {#managing-tags}
1. Click the "Manage Tags" button
2. In the tag management dialog, you can:
   - Create new tags
   - Edit existing tags
   - Delete tags
3. Click "Close" when done


## Field & Button Reference {#field--button-reference}


| Field/Button | What it does | When to use it |
|--------------|--------------|----------------|
| Create Survey | Opens dialog to create a new survey | When you want to build a survey from scratch |
| Import XLSForm | Imports a survey from an XLSForm file | When you have an existing XLSForm you want to use |
| Browse Templates | Opens the template browser | When you want to use a pre-built survey template |
| Status tabs | Filters surveys by status | When you want to see only active, draft, or archived surveys |
| Filter by tag | Filters surveys by tag | When you want to find surveys with a specific tag |
| Manage Tags | Opens tag management dialog | When you want to create, edit, or delete tags |
| All Workspaces | Filters surveys by workspace | When you want to see surveys from a specific workspace |
| All Projects | Filters surveys by project | When you want to see surveys from a specific project |
| Design Form | Opens the survey designer | When you want to edit the survey questions and logic |
| Manage Versions | Opens version management | When you want to view or manage survey versions |
| View Data | Navigates to survey responses | When you want to see collected data |
| Manage Access | Opens the Access Management page | When you want to control who can access the survey |
| Edit Details | Edits survey metadata | When you want to change the name or description |
| Clone | Creates a clone of the survey | When you want to make a copy with versions |
| Publish | Makes the survey active | When the survey is ready for responses |
| Unpublish | Takes the survey offline | When you need to make changes to a published survey |
| Archive | Archives the survey | When you're done with the survey but want to keep the data |
| Delete | Removes the survey | When you no longer need the survey or its data |


## Tips & Notes {#tips--notes}


- **Create the hierarchy first**: You must have a workspace and a project before you can create a form. If the Project dropdown is empty, create a project first.
- **Design next**: After creating a form you land in the [Survey Designer](/user-manual/survey-designer.md) — this is where you add questions, logic, validation, and translations.
- **Use tags to organize**: Tags make it easy to find and group related surveys
- **Workspaces and projects help structure**: Use workspaces and projects to keep surveys organized by team or initiative
- **Preview before publishing**: Always test your survey in the designer before publishing
- **Versions track changes**: Use version management to keep track of survey changes
- **Archiving preserves data**: Archive surveys when you're done collecting responses but still need access to the data