# Use watchlists in workflows and dashboards

> Feed a list's symbols into a workflow, let a workflow update a list, manage both from the Watchlists page, and work through a list on a dashboard.

Source: https://orbitalaip.com/docs/watchlists/use-with-workflows-and-dashboards

## Read a watchlist in a workflow

1. **Add an Input node**
   
   In the editor's **Nodes** panel, add **Input** from **Data Sources**. In **Source**, choose the **Watchlist** option.

2. **Pick the list**
   
   Choose a list under **Saved watchlist**.

3. **Add a fallback if you want one**
   
   Type comma-separated symbols in **Inline symbols (fallback)**. **Market** applies to these; a saved list keeps a market for each symbol.

The node then reads **Watchlist ·** and the list's name, and its **Assets** output carries one item per symbol.

Each run reads the list as it stands, without its section headers. If the list is archived or deleted, the node uses its inline symbols. If it has none, or the list is empty, the **Input** node fails and the steps after it are skipped.

With **Subject source** set to **Run subject, else configured source (dual-mode)**, a run started for one symbol analyses only that symbol. See [Set what a run works on](https://orbitalaip.com/docs/workflows/build-a-workflow#set-what-a-run-works-on).

Two more nodes read lists: **Get Watchlist** returns up to 50 of one list's symbols, and **List Watchlists** up to 50 unarchived lists. The Watchlists page does not count workflows that read a list only through them. See [Node reference](https://orbitalaip.com/docs/workflows/nodes).

## Connect from the Watchlists page

1. **Open the connections**
   
   Click the workflow button, just left of **⋯** in the card's header, to open **Workflow connections**.

2. **Connect an existing workflow**
   
   Under **Connect to existing**, click **Connect** beside a workflow. Orbital points its first watchlist **Input** node at this list, replacing any list it read. A workflow with no such node gets one, and the editor opens so you can wire it in.

3. **Or start a new workflow**
   
   Click **Create new workflow with this watchlist**, then **Create + open**. The editor opens on a draft whose one node is an **Input** set to the list. It counts toward your plan's workflow limit.

**Connected (N)** lists each workflow with **Open** and **Disconnect**. One that updates the list shows **Updates this list**.

> [!NOTE] Connect and Disconnect edit the canvas
> If the workflow has a [main](https://orbitalaip.com/docs/glossary#main) version, its schedules, signals, webhooks and dashboard runs keep running main until you save a version and make it main. See [Main](https://orbitalaip.com/docs/workflows/runs-and-versions#main).

## Disconnect, archive and delete

**Disconnect** removes this list from the workflow's watchlist **Input** nodes but leaves the nodes, which carry on with any inline symbols. Without them, a notice warns that the workflow will fail on its next run.

**Disconnect** never touches a **Watchlist Write** step. A workflow that only updates the list has no **Disconnect**; change or remove that step instead.

Archiving or deleting a list makes every workflow that updates it fail on its next run. Both dialogs name those workflows, for example **"Morning Movers" updates this list, and will fail the next time it runs.** The archive dialog adds that unarchiving fixes it. Neither dialog blocks you. Workflows that only read the list are not named.

## Update a watchlist from a workflow

**Watchlist Write**, under **Utility**, appears while the Watchlists app is on.

1. **Wire in the symbols**
   
   Connect tickers, rows with a symbol field such as a screener's results, or an object wrapping either.

2. **Pick an Operation**
   
   There is no default.

3. **Pick the list**
   
   Choose it under **Watchlist**. For create, enter a name in **New watchlist name** instead.

| Operation | What each run does |
| --- | --- |
| Replace | Makes the incoming symbols the whole list, in the order they arrive. |
| Add | Appends the symbols not already on the list. |
| Remove | Drops the named symbols. |
| Create | Makes a new list under the name you enter. |
| Delete | Moves the list to Trash, where it can be restored for 30 days. |

Delete runs only with **Confirm delete** on. A replace keeps section headers, moved above the symbols, and symbols that stay keep their flags.

For create, **If a list with that name exists** writes into that list by default, so a daily workflow makes it once and refreshes it after. **Fail the run** is the alternative.

**Symbol key path** says where the ticker sits in each row, and defaults to `symbol`. **Symbols path (optional)** picks the list when the input holds several. **Inline symbols (fallback)** is used only when nothing is wired.

The node refuses rather than guesses. Wired rows that are plainly not tickers, such as dates or prices, are skipped and counted in **Summary**. These cases write nothing and finish the node with a warning:

- No symbols resolved. **Let an empty result clear the list** lets a replace or create empty the list when the wired input arrives as an empty list. It is off by default, because a market holiday, a data outage and a screen that matched nothing look the same.

- A replace or create in which most wired rows give no ticker.

- An inline list with any entry that is not a ticker.

A write that would take the list past 200 symbols fails the run. So does a target list that is missing, archived or deleted.

When the Watchlists app is off in a project, a run of a workflow that holds **Watchlist Write**, **Get Watchlist** or **List Watchlists** is skipped with **The Watchlists app is turned off in this project**. See [Apps](https://orbitalaip.com/docs/workspace-and-account/apps#switch-an-app-on-or-off-in-a-project).

## Watchlists on a dashboard

A dashboard's symbol sidebar opens on your default watchlist, and clicking a symbol there switches the widgets that follow the active symbol to it. See [The symbol sidebar](https://orbitalaip.com/docs/dashboards/overview#the-symbol-sidebar).

> [!WARNING]
> Removing a symbol in the sidebar, such as with **Remove NVDA from Semis**, takes it off the watchlist itself.

**Run watchlist**, in the header of the list's section, runs each dashboard workflow that takes a symbol once per symbol on the list, as one batch. A workflow whose **Input** reads its own saved list runs once over that list instead. See [Run workflows and batch runs](https://orbitalaip.com/docs/dashboards/overview#run-workflows-and-batch-runs).

If the active symbol is not on a workflow's list, its widget can read **No NVDA result was found.** Click **Add NVDA to Semis and re-run** to add the symbol, then click **Re-run** and the workflow's name to run it.

**Watchlist Overview** needs the Watchlists app and builds on your default watchlist. Without one, its workflows use twelve large US stocks. See [Dashboard templates](https://orbitalaip.com/docs/dashboards/templates#dashboard-templates).