> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/journey-maps/cards/how-to-use-planning-cards.md).

# How to use planning cards

A planning card puts a work item from a connected planning tool, like a Linear issue or a Jira ticket, directly onto the step it relates to. The card shows the item's own fields and stays in sync with the source, so the map reflects what's actually happening in delivery.

{% hint style="warning" icon="list-check" %}

#### Prerequisites

A planning tool must already be connected at the account level. To connect one, see [Integrations > Planning tools](/integrations/planning-tools.md) (Jira, Asana, Azure DevOps, Linear, Monday.com, and Trello).
{% endhint %}

{% hint style="info" icon="tag" %}
Planning cards are an advanced card type. The **Free** and **Repository** plans allow up to 3 advanced cards per map; the **Framework** and **Governance** plans remove the cap.
{% endhint %}

To add one, hover an empty cell and click **+ Add card**, then choose **Planning**. **Planning** is the Enter quick-select in a Planning lane and sits under **ADVANCED CARDS** in the picker in any other lane.

***

#### How to add a planning item from a connected tool

Planning cards don't hold their own content. Instead, you search a connected tool and pick a live item to display, so the card becomes a window onto that item.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FLFlDcWAT8CelkxQytQQt%2Fadd_a_planning_item_no_audio.mp4?alt=media&token=a8e72901-5b83-49cc-bf6d-3cc183bca4a7>" %}

{% stepper %}
{% step %}
**Open the Search planning items modal**

Add a planning card. The **Search planning items** modal opens with a tab for each of your connected tools.

<figure><img src="/files/UgGL33CadBe2Y4q3kbsP" alt="The Search planning items modal open over a journey map. A row of tabs reads Trello (selected), Jira, and Linear. Below is a search field with a blue Search button, an empty state reading Search for planning items, and a greyed-out Select button in the bottom-right."><figcaption><p>Search planning items, with a tab per connected tool</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick the tool and search**

Click the tab for the tool you want, type a query, and click **Search**. Only the tools connected to your account appear as tabs, so the set you see depends on what's been set up.
{% endstep %}

{% step %}
**Select the item and add it**

Choose an item from the results and click **Select**. The button stays greyed out until a result is selected. The card lands in the slot showing that item's live data.
{% endstep %}
{% endstepper %}

***

#### What a planning card shows

The card displays the source item's own fields, so the layout follows your tool rather than Smaply. A Linear issue, for example, shows its **ID**, **PRIORITY**, and **STATUS**.

<figure><img src="/files/qLUlWhgazT99gYFLqyeR" alt="A planning card in a lane labelled Planning. The card is titled Connect your tools and lists three fields: ID RET-3, PRIORITY --- No Priority, and STATUS Todo."><figcaption><p>A planning card backed by a Linear issue</p></figcaption></figure>

To open the item in the tool it came from, select the card and click **Open Linear** on the toolbar (the label names whichever tool backs the card). The same action sits in the card details panel as **Open in Linear**.

<figure><img src="/files/f7f3yEVTmO7QhM1grxLV" alt="A selected planning card titled Connect your tools with its floating toolbar above. The toolbar starts with an Open Linear button, followed by the card header, fill, show card details, delete, and three-dot icons."><figcaption><p>The toolbar opens the item in its source tool</p></figcaption></figure>

A planning card has no text-formatting controls, because its content comes from the source item rather than from typing on the card.

***

#### What happens when the source item changes or is deleted

A planning item isn't stored in Smaply. The card is a live view of the item in the connected tool, so changes flow one way, from the tool into Smaply.

* **When the item changes** - Edits in the source tool, such as a new status or priority, appear on the card automatically. Most changes are reflected within about 30 seconds.
* **When the item is deleted** - The card can no longer pull its data, because the item it points to no longer exists in the tool. Remove the card from the map to clear it.

There's no Smaply-side copy to edit. To change what the card shows, change the item in the tool.

***

#### How the same item can appear on more than one map

Because the item lives in the connected tool and not in Smaply, you can add the same item to as many maps as you like. Each one is a separate card pointing at the same source, and all of them reflect the same upstream status. A status change in the tool updates every card showing that item.

***

#### What planning cards share with other cards

Planning cards use the same toolbar tail, card details panel, colour system, and multi-select as every other card type. The card details panel holds the universal Personas, Card tags, and Comments sections.

<figure><img src="/files/a0kJM0ZZQuFNKciApO9i" alt="The card details panel for a planning card. A single Open in Linear button sits at the top, above three collapsed sections: Personas, Card tags, and Comments (0)."><figcaption><p>The planning card details panel, with Open in [tool] above the shared sections</p></figcaption></figure>

See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards.md) for the canonical walkthrough of these shared mechanics.

{% hint style="info" icon="compass" %}
Planning items come from an external tool and stay in sync with it. For pain points, opportunities, and solutions that live inside Smaply, see [How to use portfolio item cards](/journey-maps/cards/how-to-use-portfolio-item-cards.md).
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to add and edit cards</strong></td><td>Parent how-to for shared card mechanics: toolbar, details panel, colours, and headers.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to set up the Jira integration</strong></td><td>Connect a planning tool at the account level before adding planning cards.</td><td><a href="/pages/yllzUq913dn0gJ6LaMPO">/pages/yllzUq913dn0gJ6LaMPO</a></td></tr><tr><td><strong>How to use portfolio item cards</strong></td><td>Show pain points, opportunities, and solutions that live inside Smaply.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td></tr><tr><td><strong>How to use metric cards</strong></td><td>Surface a live metric from a connected data source on a journey map.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>How to comment on a card</strong></td><td>Add comments and @mention teammates on any card from its details panel.</td><td><a href="/pages/Kk7GjJu76NovaA8LF2EL">/pages/Kk7GjJu76NovaA8LF2EL</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/journey-maps/cards/how-to-use-planning-cards.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.