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

# Workflow Inputs

> Configure inputs and forms for workflows

## What Are Workflow Inputs?

When a workflow needs information to run - like a username, date, or selection from a list - you define inputs. Users provide these values before the workflow executes.

<Note>
  Any workflow with form inputs automatically appears as a catalog item in the **Catalog**. Users can browse these items by clicking **New Request** → **Browse Catalog** → **All Services** and submit structured requests directly from the catalog. See [Catalog](/sections/access-management/overview#for-end-users) for more details.
</Note>

**Example:** A "Create User" workflow might have inputs for:

* Email address (text)
* Department (dropdown)
* Start date (date)
* Is contractor (checkbox)

## How To Collect Inputs?

<CardGroup cols={2}>
  <Card title="Form Fill" icon="building">
    Collect inputs via a form, including fields that appear only when relevant
  </Card>

  <Card title="Natural language" icon="users">
    Collect inputs from the user via conversation
  </Card>
</CardGroup>

***

## Input Types

Serval supports several input types:

| Type                 | Description                                         | Example Use                        |
| :------------------- | :-------------------------------------------------- | :--------------------------------- |
| **Text**             | Single-line text entry                              | Username, email, ID                |
| **Textarea**         | Multi-line text entry                               | Description, justification, notes  |
| **Number**           | Numeric value                                       | Duration, count, amount            |
| **Date**             | Date picker                                         | Start date, deadline               |
| **Time**             | Time selector                                       | Meeting time, schedule             |
| **Select**           | Dropdown with options                               | Environment, role, department      |
| **Checkbox**         | Boolean toggle                                      | Enable flag, confirm action        |
| **Entity reference** | Searchable dropdown of records from an assets table | Cost center, location, application |

***

## Configuring Inputs

When building a workflow, Serval automatically detects inputs based on your description. You can instruct Serval to change the inputs needed:

<Steps>
  <Step title="Review auto-detected inputs">
    When Serval generates your workflow, it identifies required parameters as inputs
  </Step>

  <Step title="Adjust input types">
    Change input types if needed:

    * Convert text to dropdown for constrained choices
    * Change text to textarea for long-form input
    * Add date/time pickers for temporal values
  </Step>

  <Step title="Add branching logic (optional)">
    Describe branching logic in plain language so fields show or hide based on earlier answers on the web app, in Slack, and on hosted forms (for Teams and email campaigns).
  </Step>

  <Step title="Set required vs optional">
    Mark inputs as required or optional:

    * **Required** - User must provide a value
    * **Optional** - User can leave blank (workflow uses default or skips)
  </Step>

  <Step title="Add descriptions">
    Write clear descriptions for each input to guide users
  </Step>
</Steps>

***

## Form Confirmation

For sensitive workflows, enable form confirmation to require users to review their inputs before execution:

<Steps>
  <Step title="Enable confirmation">
    Turn on "Require form confirmation" in workflow settings
  </Step>

  <Step title="User fills form">
    User completes all input fields
  </Step>

  <Step title="Review screen">
    User sees a summary of all inputs and must confirm
  </Step>

  <Step title="Execution">
    Workflow runs only after explicit confirmation
  </Step>
</Steps>

<Note>
  Form confirmation adds an extra step but helps prevent accidental execution with incorrect values.
</Note>

***

## Breakdown: Input Type Options

### Text input

Single-line text for short values.

**Best for:**

* Usernames and email addresses
* IDs and identifiers
* Short strings

**Configuration:**

* Set placeholder text for guidance
* Add description explaining expected format

### Textarea

Multi-line text for longer content.

**Best for:**

* Descriptions and notes
* Business justifications
* Comments and feedback

**Configuration:**

* Consider setting a character limit if needed
* Provide example text in the description

### Number

Numeric input with validation.

**Best for:**

* Counts and quantities
* Duration (days, hours)
* Amounts

**Configuration:**

* Set min/max values if applicable
* Specify units in the description (e.g., "Duration in days")

### Date

Calendar date picker.

**Best for:**

* Start and end dates
* Deadlines
* Scheduled dates

**Configuration:**

* Consider default values (today, tomorrow, next week)
* Specify date format expectations in description

### Time

Time selection.

**Best for:**

* Meeting times
* Schedule times
* Time-specific events

**Configuration:**

* Clarify timezone expectations
* Offer common presets if applicable

### Select (Dropdown)

Choose from predefined options.

**Best for:**

* Environment selection (prod/staging/dev)
* Role or permission level
* Department or team
* Any constrained set of choices

**Configuration:**

* Define all available options
* Set a default selection if appropriate
* Order options logically

<Tip>
  Use dropdowns instead of text inputs when you have a known set of valid values. This prevents typos and ensures consistency.
</Tip>

### Checkbox

Boolean true/false toggle.

**Best for:**

* Feature flags
* Confirmation checkboxes
* Optional features

**Configuration:**

* Set clear label describing what the toggle controls
* Consider default state (checked or unchecked)

### Entity reference

A searchable dropdown backed by a [Serval assets table](/sections/documentation/databases/schema-design), so the requester picks a real record instead of typing free text. New records appear automatically, so the options stay current without manual updates.

<Note>
  In the workflow builder, this input currently appears as **Item ref** (or **Item ref (multi)**).
</Note>

To configure the entity reference, follow these steps:

1. Select the assets table (entity type) the options come from.
   * Optionally, set which field shows as the label and which value the workflow receives
   * Optionally, filter which records appear, or restrict options to the current recipient
2. Use **Entity reference** to let the requester pick one record, or **Entity reference list** to let them pick several.

***

## Input Validation

Serval validates inputs before workflow execution:

* **Required fields** - Must be filled before submission
* **Type validation** - Numbers must be numeric, dates must be valid
* **Format validation** - Email fields check for valid email format

### Handling validation errors

When validation fails:

1. User sees an error message on the invalid field
2. Workflow does not execute
3. User corrects the value and resubmits

***

## Examples

### User provisioning workflow

| Input         | Type     | Required | Description                         |
| :------------ | :------- | :------- | :---------------------------------- |
| Email         | Text     | Yes      | New user's email address            |
| First name    | Text     | Yes      | User's first name                   |
| Last name     | Text     | Yes      | User's last name                    |
| Department    | Select   | Yes      | Engineering, Sales, Marketing, etc. |
| Start date    | Date     | Yes      | When the user starts                |
| Manager email | Text     | Yes      | Direct manager's email              |
| Is contractor | Checkbox | No       | Check if temporary/contractor       |

### Report generation workflow

| Input          | Type     | Required | Description                          |
| :------------- | :------- | :------- | :----------------------------------- |
| Report type    | Select   | Yes      | Daily summary, Weekly rollup, Custom |
| Start date     | Date     | Yes      | Report period start                  |
| End date       | Date     | Yes      | Report period end                    |
| Include charts | Checkbox | No       | Include visual charts in report      |
| Slack channel  | Text     | No       | Channel to post report (blank = DM)  |