> 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/portfolio/how-to-add-portfolio-items-to-a-journey-map.md).

# How to add portfolio items to a journey map

Add portfolio items from the Portfolio or Research Hub to a journey map in one action, with Smaply AI placing each on its step.

Add one or more portfolio items to a journey map at once, from wherever you're already working with them: the Portfolio or a Research Hub investigation. Smaply AI places each item on the step it best matches, and you confirm or adjust before anything is added.

{% hint style="info" icon="tag" %}

#### Plan availability

Available on the **Framework** plan and above.
{% endhint %}

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Start from the Portfolio](#portfolio)
2. [Start from Research Hub](#research-hub)
3. [Pick the journey map](#how-to-pick-the-journey-map)
4. [Promote new insights (Research Hub only)](#how-to-promote-new-insights-research-hub-only)
5. [Place the items and confirm](#how-to-place-the-items-and-confirm)
   {% endhint %}

Both starting points lead to the same flow: pick a journey map, then confirm where each item lands.

* [**Portfolio**](#portfolio) - Select existing portfolio items directly from the Table or Board view.
* [**Research Hub**](#research-hub) - Select insights from an investigation. Unpromoted insights are turned into portfolio items as part of the flow.

{% tabs %}
{% tab title="Portfolio" %}

#### Start from the Portfolio

Select items with the row checkboxes in the [Table](/portfolio/prioritization/how-to-use-the-portfolio-table.md) view, or Cmd-click (Mac) / Ctrl-click (Windows) cards in the [Board](/portfolio/prioritization/how-to-use-the-portfolio-kanban.md) view. A bulk-action bar appears at the bottom with **Tags**, **Change type**, **Add to account library**, **Add to journey map**, and **Delete**. Click **Add to journey map**.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-5722e2f701486269daf3010db132ca8f4027600d%2Fportfolio-add-to-map-01-table-bulk-bar-crop.png?alt=media" alt="A bulk-action bar reading 2 of 39 items selected, with Tags, Change type, Add to account library, a greyed-out Remove from account library, Add to journey map, and Delete actions."><figcaption><p>The bulk-action bar on the Portfolio Table</p></figcaption></figure>

You can select items of different types together. A mix of pain points, opportunities, and solutions all go through the same flow and land together.
{% endtab %}

{% tab title="Research Hub" %}

#### Start from Research Hub

Open an investigation and select insights with their row checkboxes in the **Insights** panel. The **Bulk edit** bar shows **Add to portfolio**, **Add to journey map**, and **Delete**. Click **Add to journey map**.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-5f1072d2050496c2fe2624299b220c6c20c4cd3e%2Fportfolio-add-to-map-13-research-bulk-bar-crop.png?alt=media" alt="A Bulk edit bar reading Bulk edit 2 items, with Add to portfolio, Add to journey map, and Delete actions."><figcaption><p>The Bulk edit bar in an investigation's Insights panel</p></figcaption></figure>

**Add to journey map** works whether or not the insights are already portfolio items, unlike **Add to portfolio**, which greys out once every selected insight has already been promoted. If any selected insight isn't a portfolio item yet, promoting it happens later in the flow, after you pick a journey map - see below.
{% endtab %}
{% endtabs %}

***

#### How to pick the journey map

A **Select a journey map** screen lists your workspace's maps, with the ones most likely to be relevant tagged **Most relevant** at the top of the list. Search by name and pick a map. A preview panel shows its thumbnail and status. Click **Continue**.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-dd2193fe6431703b5832194982fabf5478e049bb%2Fportfolio-add-to-map-04-map-selected.png?alt=media" alt="The Select a journey map screen with a search field, a Most relevant match selected in the list, and a preview panel on the right showing the map&#x27;s thumbnail, title, and a Healthy status badge."><figcaption><p>Select a journey map</p></figcaption></figure>

***

#### How to promote new insights (Research Hub only)

If you started from Research Hub and any selected insight isn't a portfolio item yet, an **Add items to portfolio** screen comes next. For each insight, choose to **Create a new portfolio item** (pick its type, and **Apply to all** applies the same type to the rest), **Add to an existing portfolio item** (from suggested matches or a portfolio search), or **Don't add to portfolio**. Insights already promoted skip this screen entirely.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-71c78208a648f1d86bafbe7d4e70116d4d316eff%2Fportfolio-add-to-map-14-research-promote-step.png?alt=media" alt="The Add items to portfolio screen. A left panel lists the selected insights; the right panel offers Create a new portfolio item with a type dropdown and Apply to all, Add to an existing portfolio item, and Don&#x27;t add to portfolio, plus a portfolio item preview showing the quotes being added."><figcaption><p>Promoting insights to portfolio items</p></figcaption></figure>

This is the same guided flow as [How to add findings to portfolio](/research-hub/how-to-add-findings-to-portfolio.md#how-to-place-each-insight-in-the-portfolio). Click **Add items to portfolio** (labelled with your item count, for example **Add 2 items to portfolio**) to continue.

{% hint style="warning" %}

#### **Important: Cancelling later doesn't undo this step**

If you cancel the staging tray on the next screen, the map placement is discarded, but any insight you promoted here stays a portfolio item. To remove it, delete it from the [Portfolio table](/portfolio/prioritization/how-to-use-the-portfolio-table.md).
{% endhint %}

***

#### How to place the items and confirm

Smaply AI works out where each item best fits on the map, shown as a progress screen while it processes. You then land in the journey map editor with a staging tray docked at the bottom, holding every item you're adding, already arranged into the columns Smaply AI matched them to.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-c71978127fcc63e74d0f5c536e52ee0e446582ff%2Frn-2026-09-add-to-journey-map.png?alt=media" alt="A staging tray docked at the bottom of the journey map editor, titled Add 2 items, with two cards placed under their matched columns and an Add to selector set to New lane."><figcaption><p>The staging tray, with items already placed by column</p></figcaption></figure>

* **Adjust the column** - drag a card within the tray, or drag it straight onto the map, to move it to a different step. A card Smaply AI couldn't confidently place lands in the first column.
* **Choose the lane** - the whole batch goes into one lane, picked from the **Add to** selector. Pick an existing lane, of any type, or leave it on **+ New lane** to create one. A new lane for a single item type is named after that type, for example **Opportunity**. A new lane for a mixed selection is named **Portfolio Lane**.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-7b84064a846070c254a62ce9b1875e86ea85965e%2Fportfolio-add-to-map-10-add-to-lane-menu-populated-crop.png?alt=media" alt="The Add to selector open, listing the map&#x27;s existing lanes, Journey Stages &#x26; Steps and Opportunity, plus New lane."><figcaption><p>Add to: any existing lane, or a new one</p></figcaption></figure>

Click **Add items** (labelled with your item count, for example **Add 2 items**) to commit, or **Cancel** to close the tray without adding anything.

{% hint style="warning" %}

#### **Important: Running this again adds duplicate cards**

Adding an item that's already on the target map doesn't update its existing card or warn you. It creates a second card for the same item. Check the map first if you're not sure whether an item is already there - each item's permanent [Key](/portfolio/prioritization/how-to-use-the-portfolio-table.md) shows in its card details panel, so you can confirm you're looking at the right one.
{% endhint %}

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-daf5a7aed5c7a67de7785f3f0feb6296b910fcbc%2Fportfolio-add-to-map-11-duplicate-cards-on-map.png?alt=media" alt="Two cards for the same portfolio item on a journey map, in different lanes but the same column, with no warning shown."><figcaption><p>Adding an item already on the map creates a duplicate card</p></figcaption></figure>

***

#### 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 use portfolio item cards</strong></td><td>What a portfolio item card shows once it's on a map, and how to edit it.</td><td><a href="/journey-maps/cards/how-to-use-portfolio-item-cards.md">Portfolio item cards</a></td></tr><tr><td><strong>How to add findings to portfolio</strong></td><td>The full guided flow for promoting Research Hub insights into portfolio items.</td><td><a href="/research-hub/how-to-add-findings-to-portfolio.md">Add findings to portfolio</a></td></tr><tr><td><strong>How to use the portfolio table</strong></td><td>Select, filter, and sort portfolio items in a list.</td><td><a href="/portfolio/prioritization/how-to-use-the-portfolio-table.md">Table</a></td></tr><tr><td><strong>How to link portfolio items</strong></td><td>Connect a portfolio item to another, such as a pain point to its solution.</td><td><a href="/portfolio/how-to-link-portfolio-items.md">Link portfolio items</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/portfolio/how-to-add-portfolio-items-to-a-journey-map.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.