> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HR Surveys

> Browse, filter, and manage engagement surveys by type and status; create new surveys, view survey details with response statistics, and edit existing surveys.

The Surveys page lists all engagement surveys with search and filter controls for type and status, and provides an action menu for each survey. It is served at route `/hr/engagement/surveys`.

## Overview

The page uses `useSurveyList` with `SurveyFilters` (type and status) and a local text search. Survey cards display name, type badge, status badge, response progress bar, and scheduled dates. A dropdown action menu on each card provides Edit, Activate (Play), Stop, and Archive actions.

This page is part of the HR-17 Employee Engagement feature.

## Who it's for

Access follows your organization's role and module configuration.

## Before you start

* None required; the page loads all surveys for the current organization.

## Steps

**View surveys**

1. Navigate to **HR > Engagement > Surveys** or go to `/hr/engagement/surveys`.
2. Use the **search** input and **Type** / **Status** filters to narrow the list.
3. Click a survey card to open the Survey Details page.

**Create a survey**

1. Click **New Survey** (top right).
2. Complete the survey form (redirects to `/hr/engagement/surveys/new`).

**Manage a survey**

1. Click the action menu (three-dot icon) on a survey card.
2. Select **Edit**, **Activate**, **Close**, or **Archive** as appropriate.

## Key concepts

| Term              | Meaning                                                        |
| ----------------- | -------------------------------------------------------------- |
| Survey type       | Category: annual, pulse, exit\_interview, custom.              |
| Survey status     | Lifecycle state: draft, active, closed, archived.              |
| Response progress | Percentage of invited employees who have submitted a response. |

## Viewing a survey

The Survey Details page displays a single engagement survey with response statistics, response list, and lifecycle action buttons. It is served at route `/hr/engagement/surveys/:id`.

The page loads survey data via `useSurveyDetail`, response statistics via `useSurveyResponseList`, and mutation actions via `useSurveyMutation`. It renders a `SurveyResponseStats` summary, a `SurveyResponseTable`, and lifecycle buttons (Play/activate, Stop/close, Archive, Edit) that appear based on current survey status.

Before you start: a survey must exist and have its status set to `active` before employees can respond. Response data populates as employees submit their responses via the Take Survey route (`/hr/engagement/surveys/:id/respond`).

1. Navigate to **HR > Engagement > Surveys** and click a survey row, or go to `/hr/engagement/surveys/:id`.
2. Review the **Response Statistics** summary card for completion rate and totals.
3. Browse individual responses in the **Response Table**.
4. Use lifecycle action buttons to manage the survey:
   * **Activate** (Play icon) — sets status to `active`.
   * **Close** (Stop icon) — sets status to `closed`.
   * **Archive** — sets status to `archived`.
   * **Edit** — navigates to the survey edit form.

**Key detail concepts:**

| Term           | Meaning                                                            |
| -------------- | ------------------------------------------------------------------ |
| Survey status  | Lifecycle state: draft, active, closed, archived.                  |
| Survey type    | Category: annual, pulse, exit\_interview, custom.                  |
| Response stats | Aggregate completion and count metrics from `SurveyResponseStats`. |

## Creating a survey

The New Survey page renders `SurveyFormPage` in create mode and is available at `/hr/engagement/surveys/new`. On successful submission the user is redirected to the surveys list. This page is part of the HR Employee Engagement module.

Before you start: define the survey purpose, target audience, and question set before opening the form. Confirm the distribution window (open and close dates).

1. Navigate to `/hr/engagement/surveys/new` or choose **New Survey** from the surveys list.
2. Complete the survey form fields.
3. Submit; on success you will be returned to the surveys list.

**Key concept:** An **Engagement Survey** is a structured questionnaire distributed to employees to measure satisfaction, engagement, or other workforce indicators.

## Editing a survey

The Edit Survey page provides a form for updating an existing engagement survey. It is available at route `/hr/engagement/surveys/:id/edit`. The route renders `SurveyFormPage` with the `id` param present (edit mode). The existing survey data is pre-filled in the form. On submit the survey record is updated via mutation and the user is redirected to the detail page.

Before you start: navigate from a survey detail page at `/hr/engagement/surveys/:id` and click the edit action.

1. From a survey detail page, click the edit action. You land on `/hr/engagement/surveys/:id/edit`.
2. Update the survey name, questions, or other settings.
3. Submit the form. On success, you are redirected to the survey detail page.

## Related

<Columns cols={2}>
  <Card title="Human Resources" icon="users" href="/hr/overview">
    Human Resources core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/hr/engagement-routes.tsx
  * src/cores/hr/engagement/pages/SurveyListPage.tsx
  * src/cores/hr/engagement/pages/SurveyDetailPage.tsx
  * src/cores/hr/engagement/pages/SurveyFormPage.tsx
  * src/cores/hr/engagement/hooks/useSurveyList.ts
  * src/cores/hr/engagement/hooks/useSurveyDetail.ts
  * src/cores/hr/engagement/hooks/useSurveyResponseList.ts
  * src/cores/hr/engagement/hooks/useSurveyMutation.ts
</Accordion>