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

# Automations

> Create powerful event-driven workflows that trigger actions across your entire HR operation

## Overview

**Automations** are the workflow engine of Firstwork. They let you define event-driven processes that automatically execute actions when specific conditions are met. From sending welcome emails to advancing candidates through stages, automations eliminate manual work and ensure consistency.

## Anatomy of an Automation

Every automation has three components:

```mermaid theme={null}
graph LR
    T[Trigger] --> R{Rule / Condition}
    R -->|Passes| A[Actions]
    R -->|Fails| S[Skip / Alt Actions]
```

1. **Trigger** — The event that starts the automation
2. **Rule** (optional) — A condition that must be satisfied
3. **Actions** — One or more operations to perform

## Triggers

| Trigger Type              | Description                                   | Use Case                                       |
| ------------------------- | --------------------------------------------- | ---------------------------------------------- |
| **OnChange**              | Fires when a field value changes              | Application status changes, form field updated |
| **Schedule**              | Fires on a time-based schedule (cron)         | Daily compliance checks, weekly reports        |
| **FormElementSubmission** | Fires when a specific form field is submitted | Real-time validation, dependent field updates  |
| **ExternalAPI**           | Fires when an external API call is received   | Webhook from ATS, partner system notification  |
| **Webhook**               | Fires from an external webhook trigger        | Custom integrations, third-party events        |
| **Recollection**          | Fires during a data re-collection event       | Periodic document re-verification              |

### Trigger Configuration

Each trigger can be scoped to:

* Specific hiring flows
* Specific stages within a flow
* Specific forms or form elements
* Specific contract types or statuses

## Actions

Automations can execute one or more actions in sequence:

### Communication Actions

| Action            | Description                                |
| ----------------- | ------------------------------------------ |
| **Send Email**    | Send templated emails via SendGrid         |
| **Send SMS**      | Send text messages via Twilio/Plivo/Exotel |
| **Slack Message** | Post messages to Slack channels            |

### Data Actions

| Action                 | Description                                |
| ---------------------- | ------------------------------------------ |
| **Fill Form Element**  | Update a form field value                  |
| **Update Application** | Change application status or stage         |
| **Update Contract**    | Modify contract fields                     |
| **Contract Creation**  | Create a new contract                      |
| **Fill Form with RPA** | Use RPA to populate form data              |
| **Recollect Data**     | Trigger data re-collection from candidates |

### Integration Actions

| Action                     | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| **Webhook**                | Make HTTP requests to external services              |
| **Run OCR**                | Process documents with optical character recognition |
| **Enroll Course**          | Assign training in the LMS                           |
| **Veriff Action**          | Trigger identity verification                        |
| **Fountain Actions**       | Sync with Fountain ATS                               |
| **App Integration Action** | Execute third-party app integrations                 |

### Flow Control

| Action                     | Description                 |
| -------------------------- | --------------------------- |
| **Send for Manual Review** | Queue for human review      |
| **Run Automation**         | Chain to another automation |
| **AI Action**              | Execute AI-powered logic    |

## Input Variables

Automations support **Input Variables** that allow you to parameterize workflows:

* Map data from the triggering event to action inputs
* Use Object Graph paths to dynamically resolve values
* Set default values for optional inputs

**Example:**

```
Input: candidate_email = {{application.candidate.email}}
Input: stage_name = {{application.current_stage.name}}
Action: Send email to ${candidate_email} about ${stage_name}
```

## Automation Execution

### Execution Records

Every automation run creates an **Automation Execution** record:

| Field            | Description                       |
| ---------------- | --------------------------------- |
| Automation       | Which automation ran              |
| Trigger Event    | What triggered the execution      |
| Status           | Success, failure, or skipped      |
| Start/End Time   | Execution timestamps              |
| Actions Executed | List of actions and their results |

### Action Executions

Each action within an automation also creates an **Action Execution** record:

| Field       | Description               |
| ----------- | ------------------------- |
| Action      | Which action ran          |
| Status      | Success or failure        |
| Input Data  | Data passed to the action |
| Output Data | Result of the action      |
| Error       | Error details if failed   |
| Duration    | How long the action took  |

### Reliable Execution

Automations execute reliably in the background with:

* **Automatic retries** on transient failures
* **Durable state** — progress is preserved even during maintenance
* **Full execution history** for debugging and auditing
* **Scalable processing** — handles thousands of concurrent automations

## Common Automation Patterns

**Trigger:** OnChange — Application created
**Action:** Send email with application confirmation and next steps
**Trigger:** FormElementSubmission — All required fields submitted
**Rule:** Compliance check passes
**Action:** Update Application — Advance to next stage
**Trigger:** OnChange — Application enters "Background Check" stage
**Action:** Webhook — Send candidate data to Sterling API
**Trigger:** Schedule — Daily at 9 AM
**Rule:** Document expires within 30 days
**Action:** Send email reminder to candidate
**Trigger:** OnChange — Application status changed to "Rejected"
**Action:** Slack message to #hiring-team channel
**Trigger:** OnChange — Contract created with status ACTIVE
**Actions:**

1. Send welcome email
2. Enroll in orientation course
3. Assign onboarding forms
4. Notify manager via Slack

## Webhook Triggers

External systems can fire automations using **webhook triggers**. Each automation with a webhook trigger gets a unique URL that external services can call to start the workflow.

This is useful for:

* Receiving results from background check providers
* Integrating with custom internal tools
* Connecting to third-party services like Zapier or Make

See [Webhooks](/integrations/webhooks) and the [API Reference](/api-reference/endpoints/fire-webhook-trigger) for details.

## Best Practices

> \[!NOTE]
> **Avoid infinite loops:** Be careful when automations trigger other automations. Use rules to prevent re-execution on data that an automation itself modified.

* **Start simple** — Begin with single-action automations and add complexity as needed
* **Use descriptive names** — Make it clear what each automation does and when it fires
* **Monitor executions** — Regularly review execution logs for failures
* **Test in staging** — Always test automations in a staging environment first
* **Use rules wisely** — Add conditions to prevent unnecessary action executions