# Workflows

On this page you can learn what a workflow is, how to create one, and how it runs.

## What a workflow is

A workflow is a business process that the [Ask agent](https://askpilot.com/docs/ask-agent.html) executes for you from start to finish. It is defined with the PROCESS.md format and its related asset files. Learn more at the [PROCESS.md page](https://askpilot.com/docs/process-md.html).

Every time a workflow starts, Askpilot opens a [session](https://askpilot.com/docs/sessions.html) for it. The session is where the work happens and where you can follow each action the Ask agent took.

## Create a workflow

*Picture: the Create new workflow form, with Access, Name, Description, the Workflow field for the PROCESS.md, the Assets drop zone, Trigger, and the Cancel and Create buttons.*

Click **Workflows** in the left sidebar, then **New**. **If you already have a workflow ready, a folder with a PROCESS.md file, including any related asset files and folders, drag and drop the whole folder onto the form and Askpilot prepopulates the workflow, the assets, the name and the description.** If not, fill in the form that opens, top to bottom.

1. **Access.** Who the workflow runs for and who can see it.
   - **Only me.** The workflow runs only for you and is visible only to you.
   - **Shared.** Pick a member of your organization. The workflow is visible to every member who can access and manage shared workflows, but the Ask agent runs it only for the member you picked. Who can view, create and manage shared workflows depends on their role. See [Roles and permissions](https://askpilot.com/docs/roles-and-permissions.html).
   *Picture: the Access field set to Shared, with the member dropdown open to pick the Askpilot user the workflow runs for.*
2. **Name and description.** A short name in lower case with hyphens, such as `lead-qualification`, and a clear summary of what the workflow is for. The Ask agent sees both, so it knows which workflows it has access to and what each one does.
3. **Workflow.** The PROCESS.md file itself, where you describe the work to be executed. Learn more about how to create one at the [PROCESS.md](https://askpilot.com/docs/process-md.html) page.
4. **Assets.** Drop a folder of files that complement the PROCESS.md, for example a contract template.
5. **Trigger.** What starts the workflow.
   - **Manually (start in the session).** You must start the workflow yourself by clicking **Run workflow** in the left sidebar and sending a message, as [Manually](#run-manually) under Start a workflow explains.
   - **A source.** Choose a webhook event from a connected [source](https://askpilot.com/docs/sources.html), and it starts this workflow automatically every time it arrives. The form asks for three things.
      - **Integration.** The source type, Street CRM for example.
      - **Source.** The connected source, for example one of your Street CRM sources if you have multiple.
      - **Events and filters.** One or more of the [events](https://askpilot.com/docs/sources.html#integration-sources) the source supports, listed on its Webhook events tab. You can add filters for each event, so the trigger only fires for the events you want. A filter is a field of the event, a condition (*is*, *is not*, *has* or *doesn’t have*) and a value. For example, fire only if the email address is mark@company.com. All conditions must match for the trigger to fire.
      > **Some sources need their webhook events set up in the tool** For certain source types, webhook events have to be set up and enabled manually in the connected tool itself. When that is the case, the **Trigger** step of the workflow form shows the webhook URLs to register there and the steps to follow.
   - **API.** The workflow can be started from your own systems with one request. See [Start workflows through the API](https://askpilot.com/docs/developers/workflows.html).
   Whatever trigger you choose, the Askpilot user with access can still start the workflow manually from **Run workflow**.
6. **Sources.** Select the [sources](https://askpilot.com/docs/sources.html) the Ask agent will use to execute this workflow. This field shows up when the trigger is a source or the API. For a workflow with a manual trigger, you select the sources in the message box when you run it. *Picture: the Sources field of the form with its dropdown open, listing every source you can select for the workflow, with Select all at the top.*
7. **Auto-run until completion.** Off by default. Choose a frequency, **Hourly**, **Daily**, **Weekly** or **Monthly**, and the Ask agent re-runs each session at that frequency until every task is done, only stopping for the approvals and questions the workflow itself asks for. Learn more about how auto-run works and when to use it at [Continuing a session automatically](https://askpilot.com/docs/continuing-a-session.html#auto-run).
8. **Create.** Click **Create** at the bottom of the form. The workflow appears in the list, switched on, and is ready to run.

## Start a workflow

A workflow can start in three ways. However it starts, it opens a session, listed in the left sidebar under **Open**, and runs with the settings that were selected for it. The [Sessions](https://askpilot.com/docs/sessions.html) page explains how to follow the session and how to answer when the Ask agent needs an input from you.

> **A workflow is visible to, and runs only for, the Askpilot user with access** Only the Askpilot user who has [access](#access) to a workflow can start it manually. When a trigger or the API starts it, it is visible to and runs only for that user, and other users do not see the session. If a team or the whole company should run and see a workflow, give access to a user that stands for them, as the [Ask agent](https://askpilot.com/docs/ask-agent.html#one-per-user) page explains.

**Example**
- **Requirement.** The whole marketing team should be able to run the *campaign-brief* workflow and follow its sessions.
- **Solution.** Invite a user for the team, marketing@company.com, and set the workflow’s **Access** to that user. Its Ask agent runs the workflow in sessions the team can open, whether the team starts it or a trigger does.

### Manually

*Picture: the Run workflow screen. The message box has a workflow selected on its Run line, a Context line with the details for this run, the Sources and Auto-run dropdowns, and the send button.*

An Askpilot user who has access to a workflow can start it from **Run workflow**, even if its trigger is not set to manual.

1. Click **Run workflow** in the left sidebar.
2. In the message box:
   - select the workflow the Ask agent will run,
   - add any context the workflow needs to run properly, the phone number of the contact for example,
   - select the sources the Ask agent will use to execute the workflow,
   - enable [auto-run](https://askpilot.com/docs/continuing-a-session.html#auto-run) if the session should re-run on a schedule until every task is done.
3. Send. A session opens under **Open** and the Ask agent starts.

### On a trigger

*Picture: the Workflows list under Workflows in the left sidebar, with each workflow’s name, who has access to it, its trigger, when it was last updated, its on/off switch and its row menu. The Trigger column shows the source event that starts each workflow.*

A workflow whose trigger is a source event starts on its own. When the event arrives from the connected tool and passes the filters, Askpilot opens a session for the Askpilot user who has access and the Ask agent executes the workflow with the enabled sources and, if auto-run is enabled, on its schedule. A workflow that is switched off does not run.

The trigger is set in the [Trigger](#create) step of the form.

### Through the API

*Picture: the Workflows list under Workflows in the left sidebar, with each workflow’s name, who has access to it, its trigger, when it was last updated, its on/off switch and its row menu. One workflow has the API as its trigger.*

Start a workflow from any system of yours with one API request, passing the context the workflow needs to run. The workflow must have the **API** trigger and be switched on. Learn more at [Start workflows through the API](https://askpilot.com/docs/developers/workflows.html) or in the [API reference](https://public-api.askpilot.com/docs#/).

## Where to find and manage your workflows

The workflows you create are available under **Workflows** in the left sidebar, which lists each one with its name and trigger icon, who has access to it, when it was last updated, and a switch that turns the workflow on or off. Only a workflow that is switched on can be started. The menu at the end of a row opens a dropdown with two options, **Edit** to open the workflow’s **Settings** tab and **Delete** to remove the workflow.

*Picture: a workflow page on its Workflow tab, with the access line, the PROCESS.md dropdown that also lists the asset files, and the file rendered section by section.*

A workflow page has two tabs.

- **Workflow.** A preview of the workflow: who has access to it and its PROCESS.md, rendered section by section. Click the file name above it to select one of the workflow’s asset files and preview that instead.
- **Settings.** The same form you filled in when you created the workflow. Change what you need and click **Save**. A session that is already open follows the saved file from its next run. Asset files cannot be edited or removed one by one. To change them, select or drop a new folder, a file or multiple files onto **Assets**: every file the workflow already has is removed and the new ones are added.

---
This is the Markdown version of https://askpilot.com/docs/workflows.html. The whole documentation as one file: https://askpilot.com/docs/llms-full.txt