# Smaply Helpdesk

Help guides for Smaply, covering journey maps, personas, portfolio, research, integrations, and account management.

<h2 align="center">Welcome to Smaply Helpdesk</h2>

<p align="center">Find docs to help answer your Smaply questions</p>

<p align="center"><button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">What do you need help with?</button></p>

<br>

<p align="center">New to Smaply? Take the quick tour.</p>

{% embed url="<https://www.youtube.com/watch?v=pXRQTz-5uak>" %}

<br>

***

### Start here

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Get started</h4></td><td>Go from a fresh account to your first journey map, with your team working alongside you.</td><td><a href="/pages/cKtZtZyWlxjJq2XWFvNp">/pages/cKtZtZyWlxjJq2XWFvNp</a></td><td><a href="/files/uUJl1ojqqAXLII4XjSNf">/files/uUJl1ojqqAXLII4XjSNf</a></td></tr><tr><td><h4>First steps for admins</h4></td><td>Set up the essentials: branding, roles, users, integrations, tags, and templates.</td><td><a href="/pages/lfeGHTTNt6pNYxV044Ne">/pages/lfeGHTTNt6pNYxV044Ne</a></td><td><a href="/files/tYyftY7d2fchyQFS1gQQ">/files/tYyftY7d2fchyQFS1gQQ</a></td></tr><tr><td><h4>Import your maps</h4></td><td>Bring existing maps into Smaply from Miro, Figma, PowerPoint, or an image.</td><td><a href="/pages/bBPhrOBBcAp2tI7Seqov">/pages/bBPhrOBBcAp2tI7Seqov</a></td><td><a href="/files/vWeMdTWRcYFzaOBx5Iud">/files/vWeMdTWRcYFzaOBx5Iud</a></td></tr><tr><td><h4>What's new</h4></td><td>The latest Smaply features and improvements, newest first.</td><td><a href="/pages/qZ3cyAV1JYrMiHRWDPRm">/pages/qZ3cyAV1JYrMiHRWDPRm</a></td><td><a href="/files/VyB8NUpJ0EaaUINnECOS">/files/VyB8NUpJ0EaaUINnECOS</a></td></tr></tbody></table>

<br>

***

### Understand your customers

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Journey maps</h4></td><td>Create, structure, and evolve journey maps with lanes, columns, and every card type.</td><td><a href="/pages/5JNDKt1ZnijS8ys5tXdV">/pages/5JNDKt1ZnijS8ys5tXdV</a></td><td><a href="/files/0dziZq262d7FbbLgykfq">/files/0dziZq262d7FbbLgykfq</a></td></tr><tr><td><h4>Research hub</h4></td><td>Run investigations, analyze transcripts with AI, and turn raw research into insights.</td><td><a href="/pages/hyj2DohLgGq9AoOwS1yg">/pages/hyj2DohLgGq9AoOwS1yg</a></td><td><a href="/files/JLCeQ3iCPY7X8esdkLos">/files/JLCeQ3iCPY7X8esdkLos</a></td></tr><tr><td><h4>Personas</h4></td><td>Build customer personas and assign them to the journey map cards they shape.</td><td><a href="/pages/1r40VyUdX9zKLUFyvSHk">/pages/1r40VyUdX9zKLUFyvSHk</a></td><td><a href="/files/xikr2dXZFXYIH6xdvAGT">/files/xikr2dXZFXYIH6xdvAGT</a></td></tr></tbody></table>

<br>

***

### Improve customer experience

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Portfolio</h4></td><td>Capture pain points, opportunities, and solutions, then prioritize them across journeys.</td><td><a href="/pages/IqUgaXX3BeI7WpnrjGLY">/pages/IqUgaXX3BeI7WpnrjGLY</a></td><td><a href="/files/2tl0UsqAdCP9IyLBwu0e">/files/2tl0UsqAdCP9IyLBwu0e</a></td></tr><tr><td><h4>Metrics</h4></td><td>Put live quantitative data on your journey maps as charts and numbers.</td><td><a href="/pages/Csa6pE6zG7JBj73ytsCv">/pages/Csa6pE6zG7JBj73ytsCv</a></td><td><a href="/files/RbS900fZgIeFwkxE0AgH">/files/RbS900fZgIeFwkxE0AgH</a></td></tr><tr><td><h4>Hierarchy maps</h4></td><td>Connect related journey maps into a navigable map of maps.</td><td><a href="/pages/BK4CPUUH3fjLWnoKajUL">/pages/BK4CPUUH3fjLWnoKajUL</a></td><td><a href="/files/lMYhSWxYPwYvWelHfVyG">/files/lMYhSWxYPwYvWelHfVyG</a></td></tr></tbody></table>

<br>

***

### Connect your tools

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Metric integrations</h4></td><td>Pull data from Google Analytics, Power BI, Qualtrics, Excel, and Google Sheets.</td><td><a href="/pages/Kf9X1ug2MQ8PofLSSbUl">/pages/Kf9X1ug2MQ8PofLSSbUl</a></td><td><a href="/files/YYH4pzsTpa12finsghAq">/files/YYH4pzsTpa12finsghAq</a></td></tr><tr><td><h4>Planning integrations</h4></td><td>Link work items from Jira, Asana, Linear, Monday.com, Trello, and Azure DevOps.</td><td><a href="/pages/1UFmZNSO8c4cjWEYlFUe">/pages/1UFmZNSO8c4cjWEYlFUe</a></td><td><a href="/files/QzzpoZ39TYa5pmWNrWA6">/files/QzzpoZ39TYa5pmWNrWA6</a></td></tr><tr><td><h4>Embeds</h4></td><td>Embed Figma, Miro, Google Docs, YouTube, and more directly on a card.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td><td><a href="/files/2JQ7lOqx2TSb6xE7Xwje">/files/2JQ7lOqx2TSb6xE7Xwje</a></td></tr></tbody></table>

<br>

***

### Collaborate with your team

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Sharing and exporting</h4></td><td>Share a read-only link, share a saved view, or export a map to PDF.</td><td><a href="/pages/6jPFR2O8RTNcoWJ7NMt8">/pages/6jPFR2O8RTNcoWJ7NMt8</a></td><td><a href="/files/82nZYwlTWASRkqvvHR7I">/files/82nZYwlTWASRkqvvHR7I</a></td></tr><tr><td><h4>Account and team</h4></td><td>Manage users, roles, workspaces, tags, branding, billing, and plans.</td><td><a href="/pages/oJH8Xf5j2fZ5D1fwnNFE">/pages/oJH8Xf5j2fZ5D1fwnNFE</a></td><td><a href="/files/TsiCUz7w3YzLC6YBgUIn">/files/TsiCUz7w3YzLC6YBgUIn</a></td></tr><tr><td><h4>Invite users</h4></td><td>Add teammates at the account, workspace, or journey map level.</td><td><a href="/pages/F1Nzd1jlynqOnRaG0WSM">/pages/F1Nzd1jlynqOnRaG0WSM</a></td><td><a href="/files/1TuZbdvr3NEsYrV6Pdqd">/files/1TuZbdvr3NEsYrV6Pdqd</a></td></tr></tbody></table>


# What's new

New features and improvements in Smaply, newest first.

The latest features and improvements in Smaply, newest first. Filter by type, or subscribe to the feed to follow updates in your reader.

{% updates format="full" %}
{% update date="2026-08-08" tags="new-feature" %}

## Multi-slider cards

Stack several ratings on one card instead of spreading them across your map. A slider card now holds more than one slider, each with its own title and end labels, plus a new Display style to switch between a handle, a dot, or a filled bar. See [how to use slider cards](/journey-maps/cards/how-to-use-slider-cards).

<figure><img src="/files/sFI2wcamvgO1b4FYrMbm" alt="A slider card holding two sliders, Sentiment and Perceived effort, each with its own handle and end labels."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-08-08" tags="new-feature" %}

## Spreadsheet import for Research Hub

Bring structured feedback into an investigation as a CSV or Excel file, whether it's a Qualtrics survey export, a Zendesk ticket export, or any spreadsheet of responses. Smaply auto-detects your feedback column and any metadata like date or channel, so you're ready to analyze in a couple of clicks. See [how to create an investigation](/research-hub/how-to-create-an-investigation).

<figure><img src="/files/p8A9kleiY1w5mXUB4BRR" alt="The Select your evidence source screen with two cards. The Text file card lists .txt, plain text or transcript, with export shortcuts for Microsoft Teams, Zoom, and Youtube. The Spreadsheet card lists .csv, rows and columns, with export shortcuts for Qualtrics, Dovetail, Medallia, Zendesk, Intercom, and Trustpilot."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-08-07" tags="new-feature" %}

## Lane templates

Skip the blank-canvas setup. Grid, flow, and freeform lanes now offer ready-made templates, like a RACI Matrix, a BPMN process diagram, or a mind map, that lay out the structure for you. Click Templates in the lane's header to pick one. See [how to use grid lanes](/journey-maps/lanes/how-to-use-grid-lanes).

<figure><img src="/files/0m6fkfgq6q281DX2wgjw" alt="The Grid lane templates dialog, showing four layout thumbnails: Gantt chart, RACI Matrix, Prioritization matrix, and Project roadmap, each with a one-line description underneath."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-08-07" tags="new-feature" %}

## Freeform lanes

Lay cards out anywhere you like, off the journey map's column grid. A freeform lane turns a lane into an open canvas: place cards wherever you want, connect them with arrows the same way you would in a flow lane, and they stay exactly where you put them as the rest of the map changes. Start from a ready-made template, like a mind map or an affinity map, instead of placing every card yourself. Add it from the lane picker like any other lane. See [how to use freeform lanes](/journey-maps/lanes/how-to-use-freeform-lanes). *(Repository plan and above)*

<figure><img src="/files/iRKCsX0ys5LEvwc2HN1J" alt="A freeform lane in a journey map with cards placed off the column grid, connected by arrows, and an image card used as an annotated backdrop with two callout cards overlaid on it."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-07-07" tags="new-feature,improvement" %}

## Bulk-add cards

Add several cards to a journey map in one go. The add-card picker now lets you select multiple items, like metrics and portfolio items, and add them all at once instead of one at a time. See [how to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

<figure><img src="/files/dMzB1vN9mnK1y2ffeaOk" alt="The Add metric picker with two metrics selected. A right panel reads 2 metrics will be added, and the confirm button reads Add 2."><figcaption></figcaption></figure>

### Improvements

1. **Cleaner Word paste:** pasting from Word no longer carries unwanted formatting into your text cards.
2. **Reliable Power BI refresh:** Power BI metric cards now update correctly when you refresh them.
3. **Full descriptions in PDF export:** journey map descriptions now render in full and export cleanly to a single-page PDF. See [how to export a journey map as PDF](/sharing-and-exporting/how-to-export-a-journey-map-as-pdf).
4. **Tags stay deleted:** a card tag you delete no longer reappears on the map.
5. **Clearer AI settings label:** the AI feature once shown as "Evidence lab" is now **Research hub** in [Account Settings](/account-and-team/how-to-configure-ai-features), matching its name across the app.
6. **Research investigation fixes:** smoother renaming, analysis viewing, and file handling in research investigations.
   {% endupdate %}

{% update date="2026-07-07" tags="new-feature" %}

## Flow lanes

Show how one step leads to the next. A flow lane lets you draw connector arrows between cards to map a process, service blueprint, or decision flow, with swimlanes and lines of interaction to structure it. Add it from the lane picker like any other lane. See [how to use flow lanes](/journey-maps/lanes/how-to-use-flow-lanes). *(Repository plan and above)*

<figure><img src="/files/Z5q7FQ2Ev6OEJC33bfDw" alt="A flow lane in a journey map with cards across two swimlanes joined by grey connector arrows."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-06-29" tags="new-feature" %}

## Import journey maps from Excel

Bring a journey map you already keep in a spreadsheet straight into Smaply. The new Excel source on the import screen reads an Excel or CSV file and turns your rows and columns into stages, lanes, and cards, with options to control how the layout maps across. See [how to import from Excel](/migration/how-to-import-from-excel). *(Repository plan and above)*

<figure><img src="/files/YD3RDOkHq2uUdUXc2VlB" alt="The Select import source screen with the Excel tile selected and the Continue button active. The six sources are Figma, Miro, Image or screenshot, and Powerpoint, each with an AI icon, plus Excel and JSON."><figcaption></figcaption></figure>

### Import from JSON

Move a journey map between workspaces or accounts, or bring back a saved copy, by re-importing a map you exported from Smaply as JSON. Export it from the map's title menu, then pick the JSON source on the import screen. See [how to import from JSON](/migration/how-to-import-from-json).
{% endupdate %}

{% update date="2026-06-18" tags="new-feature,improvement" %}

## Public persona sharing

Share a persona with anyone using a read-only public link that opens in the browser, no Smaply account required, and switch on password protection when it's sensitive (available on the Framework plan and above). See [how to share or export a persona](/sharing-and-exporting/how-to-share-or-export-a-persona).

<figure><img src="/files/27Mf1Oe6JSIoock6A5on" alt="The persona Share dialog with the view-only link enabled, a Copy Link button, and the optional Password required setting."><figcaption></figcaption></figure>

### Improvements

1. **Cleaner journey map PDF exports:** exported PDFs now leave out collaborator cursors and trim empty space, so the file looks like your map, not the editing session.
2. **Clearer Add Portfolio Item picker:** the picker shows full item titles and descriptions, and fuzzy search is back, so you can find and add the right item faster.
3. **Refined dashboard tables:** tidied table styling across the dashboard for easier scanning.
   {% endupdate %}

{% update date="2026-05-01" tags="new-feature" %}

## Kanban view for Portfolio

See where your portfolio work stands at a glance: the new Board view lays your portfolio out as a kanban board, with every item in a column by status, and you drag a card to the next column to move it along. Group by priority, assignee, or tag category when a different cut is more useful. See [how to use the portfolio kanban](/portfolio/prioritization/how-to-use-the-portfolio-kanban).

<figure><img src="/files/wtoIBRQLZdzgoWwynhzc" alt="The portfolio Board view with items laid out in kanban columns by status, each card showing a type icon and title."><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2026-04-01" tags="new-feature,improvement" %}

## Research hub

Turn raw interview research into portfolio insights without the manual slog: upload transcripts, let AI surface quotes and sentiment, and push the findings you choose straight into your [portfolio](/research-hub/research-hub) with a traceable link back to the source. *(Governance plan)*

<figure><img src="/files/5yB32nmiSKD6OGsxYhXm" alt="Research hub showing sources, AI-extracted insights, and insight details"><figcaption></figcaption></figure>

### Improvements

1. **Seat management consistency:** seat counts, invitation rules, and upgrade prompts now line up across the app, so it is clearer when you are near a limit and what to do about it.
   {% endupdate %}

{% update date="2026-03-01" tags="new-feature,improvement" %}

## Google Sheets and Qualtrics integrations

Pull live data into your metrics from two more sources, so your journey maps stay current without manual updates. [Google Sheets](/integrations/metrics-tools/google-sheets) is available on all plans; [Qualtrics](/integrations/metrics-tools/qualtrics) is on the Governance plan.

### Advanced journey map filtering

Narrow a map to exactly what you need by filtering on portfolio item attributes or tags, so large maps stay readable. See [how to filter a journey map](/journey-maps/filtering-and-views).

<figure><img src="/files/ELPNklrikeatr8SpZfF0" alt="Journey map filter menu with Portfolio items options"><figcaption></figcaption></figure>

### Improvements

1. **Faster loading,** especially for large journey maps.
2. **Improved portfolio table performance** now supports 10,000+ portfolio items.
3. **New metric display option** shows labels and values in metric charts.
   {% endupdate %}

{% update date="2026-02-01" tags="new-feature,improvement" %}

## Journey map version history

Your maps auto-save every 10 minutes, so you can compare or [restore an earlier version](/journey-maps/how-to-use-version-history) without redoing lost work. *(Governance plan)*

### Quick filters

Find the right portfolio item or metric faster: the add and create modal now has quick filters, so you are not scrolling a long list.

<figure><img src="/files/Y1dQfbUekOBVwahFjnFs" alt="Add metric modal with quick filters"><figcaption></figcaption></figure>

### Improvements

1. **Faster loading,** especially for large journey maps.
2. **Improved portfolio table performance** now supports 10,000+ portfolio items.
3. **New metric display option** shows labels and values in metric charts.
   {% endupdate %}

{% update date="2026-01-01" tags="new-feature,improvement" %}

## Custom colors and branding

Add your company colors and logo so journey maps look consistent and trusted when you share them with your team and stakeholders. See [custom branding](/account-and-team/customization/how-to-set-up-custom-branding).

### Custom cards

Go beyond pain points, opportunities, and solutions by creating your own [custom card types](/portfolio/how-to-create-custom-portfolio-item-types) and linking them in your portfolio, so your framework fits how your team actually works. *(Governance plan)*

<figure><img src="/files/lrSLalvUv7sREz1CMN5s" alt="Custom cards settings listing custom card types"><figcaption></figcaption></figure>

### Portfolio summary

See your whole portfolio at a glance with the [portfolio summary](/portfolio/how-to-use-the-portfolio-summary), then drill into the details, so you can see where things stand without opening every item.

<figure><img src="/files/ScpDjXqAx2zsLIk8YhBf" alt="Portfolio summary overview"><figcaption></figcaption></figure>

### User and seat management

See total and occupied seats plus a seat allocation summary, so you can [check your seat usage](/account-and-team/billing-and-plans/how-to-check-seat-usage) before you invite more people.

### Improvements

1. **"No priority" option** for portfolio items, now the default, so items are not forced into a priority before you have decided.
2. **New demo assets on onboarding:** new accounts and workspaces now come with demo assets, so there is something to explore from the first login.
3. **More metric chart display options.**

<figure><img src="/files/QKettRVebtrehfY7Sywp" alt="Portfolio item priority dropdown with the new No priority option, now the default"><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2025-12-01" tags="improvement" %}

## Faster loading

Especially for large journey maps and portfolios.

### Improvements

1. **Quicker way back to your workspace:** the workspace name now shows in a tooltip from inside a journey map, so you always know where you are.
2. **Partial data in series metrics:** uploaded data can now include empty cells, so you no longer have to fill every gap before a metric will work.
   {% endupdate %}

{% update date="2025-11-01" tags="new-feature,improvement" %}

## AI journey map creation on the Free plan

Build a first-draft journey map from a prompt without upgrading: [AI map creation](/account-and-team/how-to-configure-ai-features) is now on the Free plan, with three uses per person each month.

### Portfolio table configuration

Show or hide columns in the [portfolio table](/portfolio/prioritization/how-to-use-the-portfolio-table) so you see only the data you care about and keep large tables readable.

### Bulk actions for personas

Apply changes to several [personas](/personas/how-to-manage-personas) at once instead of editing them one by one, so tidying up your persona library is much quicker.

### Copy and paste grid lanes

Move entire grid lanes between maps to [reuse your work](/journey-maps/lanes/how-to-copy-lanes-across-journey-maps) and iterate faster, rather than rebuilding the same lane from scratch.

### Improvements

1. **Faster loading,** especially for large journey maps and portfolios.
   {% endupdate %}

{% update date="2025-10-01" tags="new-feature,improvement" %}

## Account Library

Manage and reuse your key content, including journey maps, personas, opportunities, pain points, solutions, and metrics, across every workspace in your account, so teams build on shared assets instead of starting over. See [how to use the Account Library](/account-and-team/how-to-use-the-account-library).

### Import your Classic maps

Bring your existing maps into Smaply automatically with the [import tool](/migration/migration), so you can pick up where you left off without rebuilding them by hand.

### Customizable portfolio items

Tailor how opportunities, pain points, and solutions look and behave to match how your team works, with [custom portfolio item types](/portfolio/how-to-create-custom-portfolio-item-types).

<figure><img src="/files/92m0CmkUYoThhPHQoxdT" alt="Portfolio settings for customizing opportunity, pain point, and solution items"><figcaption></figcaption></figure>

### Copy and paste lanes between maps

Reuse a lane you have already built by [copying it from one map to another](/journey-maps/lanes/how-to-copy-lanes-across-journey-maps), so you spend less time recreating structure.

<figure><img src="/files/c5BkHAg97iog9b0zy4Gg" alt="Menu for copying a lane between journey maps"><figcaption></figcaption></figure>

### Improvements

1. **Demo content for new accounts:** new accounts now start with demo personas, portfolio items, and metrics, so there is something to explore from the first login.
2. **Portfolio summaries in PDF export:** you can now add portfolio item summaries from the journey map [export modal](/sharing-and-exporting/how-to-export-a-journey-map-as-pdf).
3. **Better portfolio tracking:** an updated-date filter and a "Last updated" column in [portfolio tables](/portfolio/prioritization/how-to-use-the-portfolio-table) make recent changes easy to spot, with a performance boost and PDF downloads for library portfolio items.
   {% endupdate %}

{% update date="2025-09-01" tags="new-feature,improvement" %}

## AI support for journey maps

Turn a short prompt into a first-draft journey map and skip the blank canvas, so you can start from something concrete and refine from there. See [creating a journey map with AI](/account-and-team/how-to-configure-ai-features).

<figure><img src="/files/EQupv9ataH4JriYzr1cI" alt="Smaply AI generating a draft journey map from a prompt"><figcaption></figcaption></figure>

### Lane duplication

Duplicate a lane in a single step to [build maps faster](/journey-maps/lanes/how-to-add-and-manage-lanes), instead of recreating its setup by hand.

### Collapsible journey info panel

A restyled journey info panel lets you collapse it for more canvas room and take actions like cloning, archiving, sharing, and exporting right from inside the map, so you stay in your flow.

<figure><img src="/files/Mz7RfgJTDvamp0Ilsn8G" alt="Collapsible journey info panel inside the journey editor"><figcaption></figcaption></figure>

### Monthly subscriptions and a free trial

You can now choose a [monthly plan](/account-and-team/billing-and-plans/how-to-upgrade-or-downgrade), and new sign-ups get a free 14-day trial, so it is easier to start and to pick the billing that suits you.

<figure><img src="/files/hVOT5oqleQ1u1uJZe7X4" alt="Plan selection showing monthly subscription option"><figcaption></figcaption></figure>

### Improvements

1. **Color for more card types:** icon, image, and slider cards now support color, for clearer, more consistent visuals.
2. **Cleaner pasting:** pasting into the text editor now clears formatting, so unwanted or unsafe content does not come along with it.
3. **New loading experience** in the journey map.
4. **More bulk actions** for portfolio, image, slider, and icon cards, so you can edit them several at a time. See [bulk editing cards](/journey-maps/how-to-bulk-edit-cards).
   {% endupdate %}

{% update date="2025-08-01" tags="new-feature,improvement" %}

## Bulk actions for cards

Edit many cards in one go by selecting a whole lane, a whole column, or hand-picking with Shift+click, so large maps are much faster to update. See [how to bulk edit cards](/journey-maps/how-to-bulk-edit-cards).

<figure><img src="/files/09XU2kdL8qrjmOqVUVXR" alt="Selecting multiple cards in a lane and applying a bulk action"><figcaption></figcaption></figure>

### Guest dashboard

If you are not yet a member of any account, you now land on a dedicated guest dashboard for a clearer first experience, with no account created for you automatically.

<figure><img src="/files/HcsDEvdKs43s9bzgoblq" alt="Guest dashboard shown to users who are not members of any account"><figcaption></figcaption></figure>

### Full-screen portfolio editing

Edit a portfolio item in a full-screen view that gives you much more room to write descriptions of your opportunities, pain points, and solutions. See [creating a portfolio item](/portfolio/how-to-create-a-portfolio-item).

### Improvements

1. **Easier card headers:** turn a card header on straight from the toolbar menu, with more consistent header styling across cards.
   {% endupdate %}

{% update date="2025-07-01" tags="new-feature,improvement" %}

## Image card shapes

Change the shape and aspect ratio of an [image card](/journey-maps/cards/how-to-use-image-cards) so visuals fit your layout the way you want.

<figure><img src="/files/Jg9RKS1o50nInprVrZRk" alt="Image card with shape and aspect ratio options"><figcaption></figcaption></figure>

### Monday.com planning integration

Connect Smaply to [Monday.com](/integrations/planning-tools/how-to-set-up-the-monday.com-integration) to bring project planning and task management into your journey maps.

### Card color options

Give cards a background style, including white, light, solid, and transparent, for more flexibility in how your maps look. See [adding and editing cards](/journey-maps/cards/how-to-add-and-edit-cards).

<figure><img src="/files/khPaEwGSeZ5DdoI7JvoG" alt="Choosing a card background style from white, light, solid, and transparent"><figcaption></figcaption></figure>

### Improvements

1. **Drag card edges to span cards** across the journey map, so a card can stretch over several columns.
2. **New card toolbars:** a single universal toolbar makes editing text, stage, and image cards simpler.
3. **Smoother invitations:** invitation links no longer expire after 30 days, pending invitations are accepted automatically when you open a direct link, a banner flags outstanding invitations, and "Shared with me" and "Membership" are now one redesigned page.

<figure><img src="/files/NakYttaKjEG01SJN8YmK" alt="Dragging a card edge to span it across columns on a journey map"><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2025-06-01" tags="new-feature,improvement" %}

## Custom portfolio statuses and icons

Define your own portfolio statuses and icons in [account settings](/account-and-team/customization) so your portfolio reflects your team's workflow. *(Paid plans)*

<figure><img src="/files/2al2WnMRxFQEcF2M3sNS" alt="Account settings for defining custom portfolio statuses and icons"><figcaption></figcaption></figure>

### Linked portfolio items

Connect pain points, opportunities, and solutions to each other with [linked items](/portfolio/how-to-link-portfolio-items), turning a flat list into a meaningful network of insights and actions.

<figure><img src="/files/s5rDk3KiwbZKxCH5IQ3M" alt="Portfolio items linked together as pain points, opportunities, and solutions"><figcaption></figcaption></figure>

### Display options for portfolio cards

Choose how opportunity, pain point, and solution [cards](/journey-maps/cards/how-to-use-portfolio-item-cards) appear in a journey map, so each map shows the right level of detail.

<figure><img src="/files/F38dnAedKW3E8mBYmiyn" alt="Display options for portfolio item cards in a journey map"><figcaption></figcaption></figure>

### Improvements

1. **Descriptions in link-view embed cards:** add context right where it matters by writing a description in the link-only [embed card](/journey-maps/cards/how-to-use-embed-cards) view.
2. **Filters and saved views in the journey editor:** the editor now matches the dashboard filter style and lets you [save your default view](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view).
3. **More ways to add images:** upload, drag and drop, or pick from Giphy and Unsplash to enrich your [image cards](/journey-maps/cards/how-to-use-image-cards).

<figure><img src="/files/jWhK7TUvcjD34CInUkcd" alt="Description field in the link-only embed card view"><figcaption></figcaption></figure>

<figure><img src="/files/l8JBq01SRjRP3JnhFStU" alt="Journey editor filters matching the dashboard style with a saved default view"><figcaption></figcaption></figure>

<figure><img src="/files/54Uc94NYyR1W1m3FsnTv" alt="Image picker with upload, drag and drop, Giphy, and Unsplash options"><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2025-05-01" tags="new-feature,improvement" %}

## Reimagined personas

A refreshed look and new building blocks make your [personas](/personas/personas) more flexible, so you can capture exactly the detail you need.

<figure><img src="/files/3P7VeFyfdV7Y4NmF8hKH" alt="Redesigned persona with new building blocks"><figcaption></figcaption></figure>

### Smart portfolio create

When you add an opportunity, pain point, or solution, you can now search for an existing [portfolio item](/portfolio/how-to-create-a-portfolio-item) or create a new one on the spot, so you avoid duplicates and work faster.

<figure><img src="/files/Q3u7If71k3NusGkG8p05" alt="Smart portfolio create searching for an existing item while adding one"><figcaption></figcaption></figure>

### Improvements

1. **More bulk actions:** select and manage several templates or archived journeys at once.
2. **Video in embed cards:** [embed videos](/journey-maps/cards/how-to-use-embed-cards) from multiple sources.
3. **Better view-only mode** for journeys and templates, with improved viewer-role permissions.
4. **Portfolio CSV export now respects filters,** so you [export](/portfolio/how-to-export-portfolio-to-csv) exactly the items you are looking at.
   {% endupdate %}

{% update date="2025-04-01" tags="new-feature,improvement" %}

## Self-service upgrades

Move from a free trial to a paid plan right in the app, with no need to contact support, so you can [upgrade](/account-and-team/billing-and-plans/how-to-upgrade-or-downgrade) the moment you are ready.

<figure><img src="/files/19L77EIYOQcwt4uWYgvw" alt="In-app upgrade from free trial to a paid plan"><figcaption></figcaption></figure>

### Link view for embed cards

A new link view for the [embed card](/journey-maps/cards/how-to-use-embed-cards) makes external content easier to display and open.

<figure><img src="/files/AboMAhXHfO87MgDyV2GW" alt="Embed card shown in the new link view"><figcaption></figcaption></figure>

### Card headers

Give each [card](/journey-maps/cards/how-to-add-and-edit-cards) a clear, meaningful title with the new card header.

<figure><img src="/files/NmnyB3KzodKT7KmbOsud" alt="Card with a header title"><figcaption></figcaption></figure>

### Improvements

1. **See your highest plan** right in your personal account settings.
2. **Sign-in lands on your first account** instead of your favorites, for a more predictable start.
3. **Clearer pricing page:** it now shows the Free plan if you are on it, so it is easier to compare and decide whether to upgrade.
   {% endupdate %}

{% update date="2025-03-01" tags="new-feature,improvement" %}

## New dashboard sidebar

A redesigned sidebar makes [navigating Smaply](/getting-started-with-smaply) easier, and you can switch between accounts from the menu using the arrow in the lower-left corner of the screen.

<figure><img src="/files/MOLgM99edlctAagrWX2s" alt="Redesigned dashboard sidebar with account switcher"><figcaption></figcaption></figure>

### Notification improvements

See where you were mentioned, invited, or asked for help, all in [one place](/account-and-team/about-notifications), so nothing slips through the cracks.

<figure><img src="/files/Lo9tdnVBUM92bkq9Hj43" alt="Notifications panel showing mentions, invitations, and help requests"><figcaption></figcaption></figure>

### Embedded cards for Monday.com, Power BI, and Tableau

Embed live content from Monday.com, Power BI, and Tableau straight into your journey map with [embed cards](/journey-maps/cards/how-to-use-embed-cards).

<figure><img src="/files/e64qhvpvNEWAHaTHafi7" alt="Embedded cards from Monday.com, Power BI, and Tableau in a journey map"><figcaption></figcaption></figure>

### Streamlined modal for planning and embed cards

A refreshed modal makes creating [planning](/journey-maps/cards/how-to-use-planning-cards) and embed cards quicker and clearer.

### Improvements

1. **Live metric card updates:** the side panel now supports real-time [metric](/journey-maps/cards/how-to-use-metric-cards) updates.
2. **Updated card and lane menus** for better usability.
3. **Membership visibility:** view your memberships on the invitations page and leave accounts, workspaces, or maps as needed.
4. **Cleaner memberships page:** personal account memberships are no longer listed, keeping things relevant.
5. **Priority filter in portfolios:** focus on high-priority items with a new [priority filter](/portfolio/prioritization/how-to-use-the-portfolio-table).
6. **More notification touches:** see pending invitations at a glance, with auto-scroll to selected cards for smoother navigation.
7. **A new invite component** in organizations and workspaces, plus advanced-filtering fixes and updated tag styling in settings.

<figure><img src="/files/ndHOBzKin3sRYUCMxk7K" alt="Updated card and lane context menus"><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2025-02-01" tags="new-feature,improvement" %}

## Paste content from anywhere

Drop Miro post-its, Excel tables, images, and more straight into your journey maps with [enhanced paste](/journey-maps/how-to-use-enhanced-paste), so moving existing work into Smaply is effortless.

### Portfolio summary in the journey info

See a summary of [portfolio items](/portfolio/how-to-use-the-portfolio-summary) in the journey info section and jump to a filtered portfolio view in one click.

### Power BI and Excel 365 integrations

Connect your metric cards to live data from [Power BI](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration) and [Excel 365](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration) to keep your insights up to date.

### Embed content into journeys

Add interactive elements from Miro, Figma, YouTube, Google Sheets, Docs, Slides, Mural, and Microsoft Office with [embed cards](/journey-maps/cards/how-to-use-embed-cards).

### Improvements

1. **Password-protected HTML sharing:** secure your shared [journey maps](/sharing-and-exporting/how-to-share-a-journey-map-via-html-link) with a password.
2. **Share filtered views:** share a specific filtered [view](/sharing-and-exporting/how-to-share-a-saved-view) of a map instead of the whole thing.
3. **New persona card types:** expand your [persona](/personas/how-to-edit-a-persona) documentation with more card options.
4. **Advanced filtering for dashboard lists:** combine selections with AND and OR operators to refine [list views](/journey-maps/filtering-and-views/how-to-filter-and-save-list-views).
5. **Duplicate and bulk-delete metrics:** copy a metric or remove several at once.
6. **Bulk-edit coordinator and performance indicator:** update these across many [journey maps](/journey-maps/how-to-bulk-edit-journey-maps-in-the-list) in one go.
   {% endupdate %}

{% update date="2025-01-01" tags="new-feature,improvement" %}

## Planning cards for Asana, Azure DevOps, and Linear

Bring your planning tools into your maps by adding [planning cards](/journey-maps/cards/how-to-use-planning-cards) from Jira, Trello, Asana, Azure DevOps, and Linear, so delivery work sits alongside the experience it supports.

<figure><img src="/files/AlbXgNzRmZrIqloSptsS" alt="Planning cards from Jira, Trello, Asana, Azure DevOps, and Linear"><figcaption></figcaption></figure>

### Save filters as a view for lists

Organize your journey map lists with [saved views](/journey-maps/filtering-and-views/how-to-filter-and-save-list-views), shared with your team or kept private to you.

<figure><img src="/files/xtjugnYZxWo4fQyExXHg" alt="Saving a filtered list as a view"><figcaption></figcaption></figure>

### Bulk edit for journey maps and personas

Work efficiently with [bulk editing](/journey-maps/how-to-bulk-edit-journey-maps-in-the-list): archive, copy, or tag journey maps, and archive or copy personas.

<figure><img src="/files/JVX1q69qyKQsjIbA2Bp3" alt="Bulk editing journey maps to archive, copy, or tag them"><figcaption></figcaption></figure>

### Tag and filter personas, portfolio items, and metrics

Tagging and tag filtering now reach beyond journey maps and cards to [every item](/account-and-team/tags/how-to-use-tags), so you can organize your whole workspace the same way.

<figure><img src="/files/8m4RKnRQij0crzBzLGCL" alt="Tagging and filtering personas, portfolio items, and metrics"><figcaption></figcaption></figure>

### HTML sharing of a journey map

Share a read-only version of a [journey map](/sharing-and-exporting/how-to-share-a-journey-map-via-html-link) with anyone via a public link.

<figure><img src="/files/zjLw6U1pZDgDnAGp3jpU" alt="Sharing a read-only journey map via a public HTML link"><figcaption></figcaption></figure>

### Improvements

1. **Custom emotion-chart labels:** set your own labels on the [emotion chart](/journey-maps/lanes/how-to-use-emotion-chart-lanes) scale, no longer limited to the default range.
2. **Choose workspaces for Google Analytics:** pick which workspaces have the [Google Analytics](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration) integration enabled, for more control.
3. **Better icon card layout** for longer text, with a new "quotes" template. See [icon cards](/journey-maps/cards/how-to-use-icon-cards).
4. **Saved sort order:** your list sort order in the dashboard is now remembered.

<figure><img src="/files/x496hHhGLyOTahVp33Hs" alt="Selecting which workspaces have the Google Analytics integration enabled"><figcaption></figcaption></figure>

<figure><img src="/files/mN5dPCu3ODK9HVyh7Q0E" alt="Improved icon card layout with a quotes template"><figcaption></figcaption></figure>
{% endupdate %}

{% update date="2024-12-01" tags="new-feature,improvement" %}

## Slider cards

Add customizable [slider cards](/journey-maps/cards/how-to-use-slider-cards) to your personas or journey maps to show a value on a scale, making data easy to visualize and compare.

<figure><img src="/files/c2lnfKhS5T3CnKILHqEU" alt="Slider card showing a value on a scale in a journey map"><figcaption></figcaption></figure>

### Improvements

1. **Cleaner "Shared from outside":** maps from deleted accounts no longer appear there.
2. **Clearer account details:** the applied subscription plan now shows for every account.
3. **Alphabetical workspaces** in the main menu.
4. **Add-card menu in lane order:** cards in the add-card menu now match your lane order.
   {% endupdate %}

{% update date="2024-11-01" tags="new-feature,improvement" %}

## Divider lanes

Add a [divider lane](/journey-maps/lanes/how-to-use-divider-lanes) to group and separate content in a map, so larger journeys stay organized and easy to read.

<figure><img src="/files/gmete7nII25WOhtVgNUD" alt="Divider lane separating sections of a journey map"><figcaption></figcaption></figure>

### Card tagging

Tag individual [cards](/account-and-team/tags/how-to-use-tags) to make them easier to find and categorize across your projects.

### Improvements

1. **Logo goes home:** clicking the Smaply logo always takes you to your personal dashboard.
2. **Smoother tag selection** for a more intuitive process.
3. **Users sorted by name** in your organization list, for easier navigation.
4. **Portfolio enhancements:** a new interactive bubble [chart](/portfolio/prioritization/how-to-use-the-portfolio-chart) and table, cleaner styling, a dropdown to pick opportunity, pain point, or solution, an improved create/edit modal, and CSV export that includes score names and values.
   {% endupdate %}

{% update date="2024-10-01" tags="new-feature,improvement" %}

## Personal dashboard

See all your accounts and workspaces at a glance, along with recent activity and shared journey maps, so you can pick up where you left off from one [home](/getting-started-with-smaply).

<figure><img src="/files/FEJWvdGHpiWTDFQsvpgz" alt="Personal dashboard showing accounts, workspaces, and recent activity"><figcaption></figcaption></figure>

### Account home page

A dedicated dashboard for shared accounts makes it easier to manage and reach your team's collective work. See [your account overview](/account-and-team/account-and-team).

### Redesigned settings

Your [account settings](/account-and-team/account-and-team) are now organized into tabs for more intuitive navigation.

### Improvements

1. **Better tag management:** a refreshed color palette and visual design, and duplicate tags within a category are now blocked for cleaner categorization. See [creating and editing tags](/account-and-team/tags/how-to-create-and-edit-tags).
2. **Free-plan access:** free-plan users can now assign tags to journey maps (tag management stays on paid plans), and a free-plan user can be assigned to one journey map per account.
   {% endupdate %}

{% update date="2024-09-01" tags="new-feature,improvement" %}

## Tags for journey maps

Organize and filter your journey maps with [tags](/account-and-team/tags/how-to-use-tags), so projects stay easy to manage as your library grows.

<figure><img src="/files/e2fF4dXTllIwxX4KUQYr" alt="Journey maps organized and filtered with tags"><figcaption></figcaption></figure>

### Google Analytics integration

Connect [Google Analytics](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration) to bring real usage data into your journey insights.

<figure><img src="/files/gpVRRtEyyHo4XtHqoT3S" alt="Google Analytics integration bringing usage data into Smaply"><figcaption></figcaption></figure>

### Filtering across menus

A consistent condition bar brings the same [filtering](/journey-maps/filtering-and-views/how-to-filter-a-journey-map) experience to every menu.

<figure><img src="/files/PORrdhJwrcwiv8Ow3UjK" alt="Condition bar filtering used consistently across menus"><figcaption></figcaption></figure>

### Main menu drawer

A new drawer component gives the [main menu](/getting-started-with-smaply) a cleaner, less cluttered interface.

<figure><img src="/files/YeyUCmG85FJm7LlFdipt" alt="Main menu shown in a new drawer component"><figcaption></figcaption></figure>

### Refreshed logo

We have updated the Smaply logo to match our evolving brand.

### Improvements

1. **Safer account deletion:** extra confirmation steps in the deletion flow help prevent mistakes.
2. **Higher rate limit** for better performance under load.
3. **Richer metrics:** more options for how metrics are displayed and compared.
   {% endupdate %}
   {% endupdates %}


# Getting started with Smaply

Get oriented in your workspace, start your first journey map, and bring your team into the same space.

By the end of this guide, you'll be oriented in your workspace, you'll have your first journey map started, and your team will be invited in.

{% embed url="<https://www.youtube.com/watch?v=pXRQTz-5uak>" %}

{% hint style="info" %}
If you haven't created an account yet, see [How to create an account](/account-and-team/users-and-roles/how-to-create-an-account). If you've received an invitation, see [How to join by invitation](/account-and-team/users-and-roles/how-to-join-by-invitation).
{% endhint %}

{% hint style="info" icon="compass" %}
If you set up the Smaply Account and need to configure integrations, branding, custom item types, or users at scale, see [First steps for admins](/first-steps-for-admins).
{% endhint %}

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

#### What you'll do

1. [The left sidebar](#the-left-sidebar)
2. [Create your first journey map](#create-your-first-journey-map)
3. [Invite your team](#invite-your-team)
4. [Get oriented to the rest of Smaply](#get-oriented-to-the-rest-of-smaply)
5. [What's next](#whats-next)
   {% endhint %}

***

#### The left sidebar

The persistent left sidebar is where you move around Smaply.

The **Account name** sits at the top with an expand and collapse dropdown for switching between Smaply Accounts you belong to. Below it, the workspace expands to show the sections you'll use day to day:

* **Dashboard** - The workspace landing page, with quick-create buttons, recents, saved views, favorites, and learning links.
* **Journey maps** - Every journey map in the workspace.
* **Personas** - Customer archetypes you can attach to journey maps.
* **Portfolio** - Pain points, opportunities, solutions, and any custom item types your team works with.
* **Metrics** - Quantitative data you can drop onto maps as cards.
* **Research** - The Research Hub for analyzing transcripts and turning them into insights.
* **Templates** - Pre-built journey map structures, from Smaply or your team.
* **Archive** - Archived journey maps, personas, and templates.
* **Settings** - Workspace-level settings.

At the bottom of the sidebar, your current plan name appears with an **Upgrade** button next to it (visible on the Free plan).

<figure><img src="/files/g27L6GPqd5G1CmSZyEJ7" alt="The persistent left sidebar of a workspace, with the Account name at the top and the workspace expanded to show Dashboard, Journey maps, Personas, Portfolio, Metrics, Research, Templates, Archive, and Settings. The plan area sits at the bottom."><figcaption><p>The left sidebar, where you move around Smaply</p></figcaption></figure>

***

#### Create your first journey map

Click **+ New journey** on the Dashboard to open the **New journey map** dialog. Pick the **Account** and **Workspace** the map belongs to, then click **Create**. The editor opens on the **Create your journey map** start screen, where you choose one of three ways to build the map:

* [**With Smaply AI**](#with-smaply-ai) - Describe the journey in a sentence and let AI draft the structure. Fastest if you don't have an existing model in mind.
* [**Blank journey**](#blank-journey) - Start from an empty canvas and build the map yourself. Best when you have a clear plan or want full control.
* [**From a template**](#from-a-template) - Start from a pre-built structure for a common scenario. Best when your situation matches a known pattern.

{% hint style="info" icon="tag" %}
Smaply AI is available on every plan. The **Free** plan includes 3 generated maps per month; paid plans raise this limit.
{% endhint %}

<figure><img src="/files/o6OtpAAJw2fepMFYgZR9" alt="The Dashboard of your workspace. A quick-create row near the top shows three buttons: + New journey, + New persona, and + New metric."><figcaption><p>Dashboard > + New journey</p></figcaption></figure>

<figure><img src="/files/0iVs4rH1frYAXS7R1HUw" alt="The Create your journey map start screen inside the editor. A prompt field with a Generate button sits below the heading, with Try chips beneath it, and a Templates row showing a Blank journey card followed by template cards."><figcaption><p>The start screen, with three ways to build your map</p></figcaption></figure>

{% tabs %}
{% tab title="With Smaply AI" %}
Type a sentence describing the journey in the prompt field and click **Generate**. A guided three-step wizard then walks you through refining the name and description and customizing the stages and steps before it builds the full map.

For the full walkthrough, see [How to create a journey map](/journey-maps/how-to-create-a-journey-map).
{% endtab %}

{% tab title="Blank journey" %}
Click the **Blank journey** card in the **Templates** row. The map opens as an empty canvas with a single **Stage** lane, ready for you to add the lanes, columns, and cards you need.

For the full walkthrough, see [How to create a journey map](/journey-maps/how-to-create-a-journey-map).
{% endtab %}

{% tab title="From a template" %}
Pick a template card from the **Templates** row to start from a pre-built structure. Smaply's built-in templates sit alongside any your team has saved, and the map opens with the template's structure already in place.

For the full walkthrough, see [How to create a journey map](/journey-maps/how-to-create-a-journey-map).
{% endtab %}
{% endtabs %}

***

#### Invite your team

Invites happen at three levels. Pick the level that matches how widely the person needs access. Access at a broader level cascades down, so an account-level invitee automatically has access to every workspace and journey map.

* **Account level** - Use when someone needs access to everything in the account. Open **Account Settings > Users**.
* **Workspace level** - Use when someone only works inside one workspace. Open **Workspace Settings > Manage users**.
* **Journey-map level** - Use when someone only needs access to one specific map. Open the map's **Share** menu in the top-right of the editor and choose **Manage access**.

When you invite someone, you assign them a role: Admin, Editor, or Viewer. For what each role can do at each level, see [Access levels and permissions](/account-and-team/users-and-roles/access-levels-and-permissions).

For the full invite flow at any level, see [How to invite users](/account-and-team/users-and-roles/how-to-invite-users).

{% hint style="info" icon="tag" %}
Viewer seats are tracked separately from Admin and Editor seats and require **Framework** or above.
{% endhint %}

<figure><img src="/files/0qOytX4cnPewN2j2qEPE" alt="The Share menu open on a journey map, showing Manage access and Share link (view-only)."><figcaption><p>A map's Share menu > Manage access</p></figcaption></figure>

***

#### Get oriented to the rest of Smaply

Beyond journey maps, four other workspace areas hold work that connects back into your maps:

* **Personas** - Audience profiles you can attach to journey maps to filter and contextualize the experience. See [How to create a persona](/personas/how-to-create-a-persona).
* **Portfolio** - The catalog of pain points, opportunities, solutions, or any custom item types your team works with. See [How to create a portfolio item](/portfolio/how-to-create-a-portfolio-item).
* **Research Hub** - Where you analyze research files in an investigation; insights and quotes can flow into the portfolio. See [How to create an investigation](/research-hub/how-to-create-an-investigation).
* **Metrics** - Quantitative data from connected tools or manual CSVs that you can drop onto journey maps as cards. See [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

***

#### What's next

<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 create a persona</strong></td><td>Add an audience profile to your first journey map.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td></tr><tr><td><strong>How to share a journey map via HTML link</strong></td><td>Share a read-only view with stakeholders outside your account.</td><td><a href="/pages/pIllWy9tostqqZvqoymz">/pages/pIllWy9tostqqZvqoymz</a></td></tr><tr><td><strong>First steps for admins</strong></td><td>If you set up the Smaply Account, the admin-side setup tasks live here.</td><td><a href="/pages/lfeGHTTNt6pNYxV044Ne">/pages/lfeGHTTNt6pNYxV044Ne</a></td></tr><tr><td><strong>Access levels and permissions</strong></td><td>How roles and scopes shape what each user can see and do.</td><td><a href="/pages/escpmNlj3DUgMgLSjGAl">/pages/escpmNlj3DUgMgLSjGAl</a></td></tr></tbody></table>


# First steps for admins

Get your Smaply Account set up so your team can start mapping in a workspace that looks and works the way you need.

Branding, team access, integrations, customization, and AI controls are all set in one place. Walk through them once and your team can start mapping in a workspace that already looks and works the way you want.

{% hint style="info" icon="compass" %}
If you're a Workspace Admin and only need to manage one workspace's settings, open **Settings** in the workspace sidebar instead.
{% endhint %}

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

#### Prerequisites

You're an Account Admin and signed in to Smaply. If you've been invited to a Smaply Account but you're not sure which role you have, see [Access levels and permissions](/account-and-team/users-and-roles/access-levels-and-permissions).
{% endhint %}

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

#### In this guide

1. [Where Account Settings lives and who can open it](#where-account-settings-lives-and-who-can-open-it)
2. [Set up your Account name, logo, icon, and brand colors](#set-up-your-account-name-logo-icon-and-brand-colors)
3. [Invite your team at the level that matches their access](#invite-your-team-at-the-level-that-matches-their-access)
4. [Connect Smaply to your metrics and planning tools](#connect-smaply-to-your-metrics-and-planning-tools)
5. [Set up tags and templates for the team](#set-up-tags-and-templates-for-the-team)
6. [Decide which AI features your team can use](#decide-which-ai-features-your-team-can-use)
7. [Keep an eye on seat usage and your plan](#keep-an-eye-on-seat-usage-and-your-plan)
   {% endhint %}

***

#### Where Account Settings lives and who can open it

**Account Settings** is the admin-only configuration area for the whole Smaply Account. While you're at the account level, before entering a workspace, open it from the **Account settings** button at the bottom of the left sidebar, next to **Manage users**.

<figure><img src="/files/RHIFlx1HjK2jFQpYmapp" alt="Smaply dashboard at the account level. The left sidebar shows the account switcher dropdown at the top and, at the bottom, an Account settings button next to a Manage users button."><figcaption><p>Account settings opens from the bottom of the left sidebar</p></figcaption></figure>

The account-name dropdown at the top of the left sidebar is the account switcher. Use it to move between accounts you belong to or add another account. It doesn't hold settings.

Inside Account Settings, seven tabs cover everything an admin sets up:

* **Account** - Branding and subscription
* **Users** - Invitations and seat allocation
* **Integrations** - Metrics and planning tool connections
* **Workspaces** - Workspace list and per-workspace user management
* **Customization** - Custom Cards and Icon templates
* **Tags** - Tag categories and tags
* **AI Features** - Account-wide AI controls

Account Admins have access to everything here. Workspace Admins are limited to a single workspace's **Workspace Settings** and don't see Account Settings at all. See [Access levels and permissions](/account-and-team/users-and-roles/access-levels-and-permissions) for the full role and access model.

<figure><img src="/files/GeOzgUu5rvSsc9WGjPKE" alt="Account Settings open on the Account tab, with the seven-tab strip across the top: Account, Users, Integrations, Workspaces, Customization, Tags, and AI Features."><figcaption><p>Account Settings with the seven tabs across the top</p></figcaption></figure>

***

#### Set up your Account name, logo, icon, and brand colors

Branding is on the **Account** tab. It shows up on anything your team exports or shares, so set it before you invite people in.

* **Account name** - Editable text field, shown alongside the account avatar throughout Smaply.
* **Logo** - Wider format. Appears on PDF exports and shared journey maps.
* **Icon** - Square format. Used as the account avatar in navigation.
* **Brand colors** - Up to 14 custom colors that flow into color palettes across the platform.

For the full setup walkthrough, see [How to set up custom branding](/account-and-team/customization/how-to-set-up-custom-branding).

***

#### Invite your team at the level that matches their access

Smaply has three access levels. Pick the level that matches how broadly the person needs to work. Access at a broader level cascades down, so an account-level invitee has access to every workspace and journey map automatically.

* **Account level** - Use when someone needs access to everything in the Account. Invite from **Account Settings > Users**.
* **Workspace level** - Use when someone only works inside one workspace. Invite from that workspace's **Settings > Manage users**.
* **Journey-map level** - Use when someone only needs access to one specific map. Invite from the map's **Share** menu in the top-right of the editor.

Each invitation also assigns a role. A few things to know about roles and seats:

* Roles are **Admin**, **Editor**, or **Viewer**.
* Seats follow the user, not the access level. One person counts as one seat regardless of how many levels they have access to.
* Viewer seats are tracked separately from Admin and Editor seats.

For the full invite mechanics at any level, see [How to invite users](/account-and-team/users-and-roles/how-to-invite-users). For the role and level model in depth, see [Access levels and permissions](/account-and-team/users-and-roles/access-levels-and-permissions). To see what's available against your plan, see [How to check seat usage](/account-and-team/billing-and-plans/how-to-check-seat-usage).

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

#### Plan availability

Viewer seats follow your plan. **Free** and **Repository** include no viewer seats. **Framework** includes 5. **Governance** is unlimited.
{% endhint %}

<figure><img src="/files/iWS6myObxCa1hxaHqBFZ" alt="Account Settings on the Users tab with the invite panel open, showing an email field and the role dropdown listing Admin, Editor, and Viewer."><figcaption><p>Account Settings > Users, inviting at the account level</p></figcaption></figure>

***

#### Connect Smaply to your metrics and planning tools

Integrations are configured once at the account level. Open the **Integrations** tab to see the two categories:

* **Metrics integrations** - **Google Analytics**, **Excel 365**, **Power BI**, **Google Sheets**, **Qualtrics**. These pull quantitative data into metric cards on journey maps.
* **Planning integrations** - **Jira**, **Azure DevOps**, **Asana**, **Linear**, **Trello**, **Monday.com**. These link work items to the journey steps they affect.

Connecting an integration is the admin's job. After it's connected, anyone on the workspace can drop the data onto a journey map.

For the connection flow on any integration, see [Set up your first integration](/integrations/set-up-your-first-integration). For cross-tool questions like refresh frequency, switching auth, and what happens on disconnect, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level). For per-tool setup, see the article for your tool under **Metrics tools** or **Planning tools**.

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

#### Plan availability

**Service account** authentication for **Google Analytics**, **Power BI**, and **Google Sheets** is available on **Governance**. On other plans, those three tools connect with **Login with your account (OAuth)**, which ties the connection to a single user.
{% endhint %}

<figure><img src="/files/uYzC34ml6kLtrkZ64FPA" alt="Account Settings on the Integrations tab, showing the metrics and planning tools each with a Set up or connected state."><figcaption><p>Account Settings > Integrations</p></figcaption></figure>

***

#### Set up tags and templates for the team

Two customization items are worth setting up early because they shape how the team organizes content and starts new work.

* **Tags** - Account-level metadata, shared across every workspace. Set up tag categories (each with an icon, color, and name) and the tags inside them. Configured on the **Tags** tab. See [How to create and edit tags](/account-and-team/tags/how-to-create-and-edit-tags).
* **Templates** - Pre-built journey map structures the team can reuse when creating new maps. Smaply provides starter templates. Your team can also save any journey map as a template. See [How to create and use templates](/account-and-team/customization/how-to-create-and-use-templates).

***

#### Decide which AI features your team can use

The **AI Features** tab sets the AI posture for the whole Account. Each AI feature has its own toggle, and a **Disable all** link turns every one off at once.

When an AI feature is disabled at the account level, it's hidden from the UI for everyone in the Account rather than greyed out. Content already generated by an AI feature stays in place either way.

For the current list of AI features and what each one does, see [How to configure AI features](/account-and-team/how-to-configure-ai-features).

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

#### Plan availability

The AI features available depend on your plan. **Journey map create** works on every plan, with the **Free** plan capped at 3 generated maps per month and paid plans raising the cap. See [How to configure AI features](/account-and-team/how-to-configure-ai-features) for per-feature availability.
{% endhint %}

***

#### Keep an eye on seat usage and your plan

Seat usage lives on the **Users** tab. A **Seats used** summary at the top shows totals (e.g., "9 of 1000") with a breakdown by **Account**, **Workspace only**, **Map only**, and **Pending**. A **View seat allocation** button opens a detailed view that lists users per level, plus a separate **Viewer license management** section where viewer seats are tracked apart from Admin and Editor seats.

When the team is approaching the plan's seat allowance or wants a feature that's gated, the per-plan feature matrix shows what each tier unlocks.

For the seat views in depth, see [How to check seat usage](/account-and-team/billing-and-plans/how-to-check-seat-usage). For the plan feature comparison, see [What's included in each plan](/account-and-team/billing-and-plans/what-is-included-in-each-plan).

<figure><img src="/files/jYfsbaXZJzx1nxltmkiN" alt="The View seat allocation view, with a Seats used summary, per-level user lists, and a Viewer license management section showing viewer licenses used."><figcaption><p>View seat allocation, with the Viewer license management section</p></figcaption></figure>

***

#### What's next

<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 invite users</strong></td><td>Invite mechanics across account, workspace, and journey-map level.</td><td><a href="/pages/F1Nzd1jlynqOnRaG0WSM">/pages/F1Nzd1jlynqOnRaG0WSM</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>The connection flow for metrics and planning tools.</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr><tr><td><strong>Access levels and permissions</strong></td><td>How roles and access levels shape what each user can see and do.</td><td><a href="/pages/escpmNlj3DUgMgLSjGAl">/pages/escpmNlj3DUgMgLSjGAl</a></td></tr><tr><td><strong>Getting started with Smaply</strong></td><td>User-side onboarding. Forward this to invited team members.</td><td><a href="/pages/cKtZtZyWlxjJq2XWFvNp">/pages/cKtZtZyWlxjJq2XWFvNp</a></td></tr></tbody></table>


# Glossary

Plain-language definitions of the Smaply terms people most often mix up.

Quick definitions of the Smaply terms that come up most often, including every card and lane type and the main features, with the commonly confused pairs spelled out at the end.

#### Accounts, workspaces, and people

**Account** - Your organisation's home in Smaply. It holds your workspaces, the people you invite, your integrations, and your billing. One Account can contain several workspaces.

**User account** - Your personal login and profile. The same login can belong to more than one Account (for example your own company's and a client's), and you switch between them from the account dropdown at the top-left.

**Workspace** - A space inside an Account where the work lives, with its own journey maps, personas, portfolio items, metrics, and research. Use separate workspaces to keep teams, clients, or projects apart. How many you get depends on your plan.

**Persona** - A customer archetype, built from cards, that you can assign to journey map cards, plot on an emotion chart, and filter a map by.

#### Journey map building blocks

**Journey map** - Smaply's core canvas for mapping an experience over time. It is a flexible grid of lanes (rows) and columns (steps) that holds many kinds of cards: text, stages, emotions, personas, images, metrics, embeds, portfolio items, and links to other maps. Teams use journey maps for everything from customer journeys and service blueprints to onboarding flows and current-state vs future-state analysis.

**Hierarchy map** - The same kind of canvas as a journey map, used to organise a set of related journey maps into a navigable map of maps. You add existing journey maps as nodes and connect them in any direction. Use a journey map for a single experience, and a hierarchy map to see how many journeys fit together. Available on the Repository plan and above.

**Lane** - A horizontal row on a journey map. Its type sets the card you add by default (see Lane types).

**Column** - A vertical slot on a journey map, running left to right to show how the experience unfolds over time. Columns are usually grouped under stages.

**Step** - A single moment or touchpoint in the journey, shown as a column. There is no separate step card; you label steps with text or stage cards.

**Stage** - A high-level phase that groups several steps together, shown as a chevron-shaped stage card across the top of a map.

**Card** - The unit of content you place on a map, at the crossing of a lane and a column. Any card type can go in any lane (see Card types).

#### Card types

**Text card** - Narrative content such as notes, descriptions, or quotes. The default card in text lanes; click in and type, with rich formatting.

**Stage card** - A chevron-shaped header that marks a high-level phase and spans the steps it covers.

**Image card** - A picture on the map. Upload a file (JPG, PNG, GIF, or SVG) or search the built-in Unsplash and Giphy libraries.

**Icon card** - A set of icons for channels, touchpoints, or checklists, chosen from an icon template such as Channels, Checklist, or Social.

**Slider card** - One or more sliders, each with a title and two end labels, for showing a position on a scale such as confidence or maturity. A card can hold several sliders for related ratings on the same step.

**Embed card** - Live external content embedded by pasting a URL (Figma, Miro, YouTube, Google Docs, Sheets, and Slides, Power BI, and more). Shows as interactive rich media or a simple link.

**Metric card** - Shows a metric on the map as a chart or a number.

**Planning card** - Shows a work item from a connected planning tool (Jira, Asana, Linear, and others) with its live details.

**Portfolio item card** - Shows a portfolio item (pain point, opportunity, solution, or custom type) on the map.

**Linked journey map card** - Links to another journey map, with a preview and a way to jump to it. It is also the building block of hierarchy maps.

#### Lane types

A lane's type sets the card you add by default, but any card type can still go in any lane. Two lane types are exceptions and hold no cards of their own: emotion chart and divider.

**Text lane** - The default lane, for narrative content. Defaults to text cards.

**Stage lane** - Holds the stage cards that mark your phases.

**Grid lane** - A table-like lane split into rows and columns, good for channels, matrices, or process tables. Cells take any card type.

**Flow lane** - A grid-style lane that adds connector arrows between cards, for mapping a process, sequence, or decision flow tied to the map's columns. Shares its row-and-column structure with the grid lane.

**Freeform lane** - An open-canvas lane where cards go anywhere you place them, off the column grid, and stay put as columns change elsewhere on the map. Connects cards with the same arrows as a flow lane.

**Emotion chart lane** - Plots an emotional journey as a line on a sentiment scale (a 5-point scale by default), one line per persona. Holds no cards.

**Divider lane** - A full-width separator with an optional label, used to break a map into sections. Holds no cards.

**Image, icon, embed, metric, planning, and linked journey lanes** - Each defaults to its matching card type.

**Portfolio lanes** - Default to a portfolio item type: pain point, opportunity, solution, or a custom type your account has added.

#### Portfolio, metrics, and planning data

**Portfolio item** - A pain point, opportunity, solution, or custom type that lives at the workspace level, independent of any map. It carries its own details (description, scores, priority, status, assignee, tags, evidence, and links to other items) and can appear on many journey maps at once.

**Metric** - A number or data series in Smaply, either typed in by hand, uploaded as a CSV, or pulled from a connected tool such as Google Analytics or Power BI. A metric exists once and can be shown on any map.

**Planning item** - A work item (a ticket, task, or issue) from a connected planning tool such as Jira, Asana, or Linear. Planning items are not stored in Smaply; they stay in the source tool, and Smaply shows their live details.

#### Features and tools

**Portfolio** - The workspace area for capturing pain points, opportunities, solutions, and custom types, and prioritising them across journeys with chart, table, and board views.

**Metrics** - Quantitative data brought onto journey maps as charts or numbers, from manual entry, a CSV, or a connected tool.

**Research Hub** - A space for turning research into insights: upload transcripts to an investigation, let AI pull out quotes and sentiment, then promote findings to portfolio items.

**Integrations** - Connections to external tools: metrics sources (such as Google Analytics and Power BI), planning tools (such as Jira and Asana), and embed sources.

**Smaply AI** - Smaply's AI features, including drafting a journey map from a short prompt and analyzing research in the Research Hub. An admin can turn these on or off for the account.

**Account Library** - A shared layer that makes an item available as a single synced reference across every workspace, instead of copying it. Framework plan and above; it activates once you have a second workspace.

**Templates** - Saved journey map structures you start new maps from, including Smaply's own templates and ones your team saves.

**Lane template** - A ready-made content layout, such as a RACI Matrix or a mind map, that you drop into a single grid, flow, or freeform lane from that lane's own **Templates** button. Smaller in scope than a (journey map) template: it fills in one lane, not a whole map.

**Tags** - Account-level labels, grouped into categories, that you can apply to maps, cards, personas, portfolio items, and metrics, then filter by.

**Custom portfolio item types** - Portfolio types your admin defines beyond the three built-ins (pain point, opportunity, solution), each with its own scores and statuses.

**Icon templates** - Reusable sets of icons your admin sets up for icon cards to draw from.

**Emotion chart** - A view of sentiment across the journey, drawn as one line per persona on an emotion chart lane.

**Version history** - Automatically saved snapshots of a journey map that you can view and restore, with a restore opening a non-destructive working copy. Governance plan.

**Archive** - Where archived journey maps, personas, and templates go instead of being deleted, so you can restore them later.

**Paste content** - Pasting tables and text from Excel, Google, Miro, or Mural, or images, straight onto a map as cards. Also called enhanced paste.

**Bulk edit** - Selecting several cards, or several maps in a list, to tag, assign, move, or delete them in one action.

**Import** - Bringing an existing map into Smaply by uploading a screenshot or image that AI rebuilds into an editable journey map.

**Notifications** - In-app alerts (the bell icon) for things like @mentions, shared maps, access grants, and comment activity.

#### Filtering and sharing

**Filter** - A way to narrow what you see on a journey map by lanes, personas, tags, or portfolio items. A filter changes the view on screen; it does not change the map.

**Saved view** - A filter you have named and saved so you, or your team, can reapply it in one click. The view stores the filter, not a separate copy of the map.

**HTML share link** - A read-only link to a journey map or persona that opens in a browser without a Smaply account. It is for viewing, not collaborating, and can be password-protected.

***

#### Commonly confused

<details>

<summary><strong>Account vs user account</strong></summary>

Your **user account** is you: one personal login and profile. An **Account** is an organisation's space that holds workspaces, people, integrations, and billing. One user account can belong to several Accounts, and you switch between them from the account dropdown at the top-left.

</details>

<details>

<summary><strong>Journey map vs hierarchy map</strong></summary>

Both are the same kind of editable map. A **journey map** captures one experience. A **hierarchy map** sits in the Hierarchies space and links many journey maps together into an overview. Rule of thumb: map a single journey on a journey map, and reach for a hierarchy map when you need to see how lots of journeys relate.

</details>

<details>

<summary><strong>Items vs cards (portfolio, metric, planning)</strong></summary>

In Smaply, the data and the way it is shown on a map are separate. A portfolio item, a metric, and a planning item each hold the data; the matching card (portfolio item card, metric card, planning card) is a view of that item placed on a journey map. The data or item can appear on many cards on many maps, and editing the data / item updates every card.

</details>

<details>

<summary><strong>Filter vs saved view</strong></summary>

A **filter** narrows what you see on a map right now. A **saved view** is a filter you have named and kept, so you can reapply the same filter later or share it with your team. The view stores the filter, not a separate copy of the map.

</details>

<details>

<summary><strong>Share a link vs give someone access</strong></summary>

An **HTML share link** lets people view a journey map or persona in a browser without a Smaply account. It is read-only (no editing), and you can password-protect it. **Giving access** means inviting someone to the map, workspace, or Account with a role, so they can view, comment, or edit inside Smaply. Use a link for quick read-only viewing, and invite people when they need to work in the map.

</details>

<details>

<summary><strong>Templates vs lane template</strong></summary>

A **template** is a whole journey map structure you pick when creating a new map. A **lane template** is smaller: a ready-made layout, such as a RACI Matrix or a BPMN diagram, that you drop into a single grid, flow, or freeform lane from that lane's own **Templates** button. Use a template to start a whole map, and a lane template to fill in one lane fast.

</details>


# Block showcase

A deliberate test of GitBook's custom block types and internal formatting to confirm each renders correctly after sync

This article exercises every content type and custom block available in GitBook so we can confirm each one renders correctly after a git-to-GitBook sync.

***

## Text and basic formatting

### Headings

All six heading levels render with distinct sizing. Most articles only use H1 (title), H2 (major sections), and H3 (sub-sections). H4-H6 are mainly used inside custom blocks (per GitBook's normalisation rules).

## H2 heading

### H3 heading

#### H4 heading

**H5 heading**

**H6 heading**

### Inline text styles

**Bold text** and *italic text* and `inline code` and ~~strikethrough~~.

Combined: ***bold italic***, **`bold inline code`**, and *`italic inline code`*.

### Links

* External link: [Smaply website](https://smaply.com)
* Internal link to another file: [Homepage](/)
* Internal link with anchor: [Jump to Mermaid section](#mermaid-diagrams)
* Email link: [Contact support](mailto:help@smaply.com)

***

## Structural elements

### Horizontal divider

A horizontal rule separates sections visually without adding a heading. Syntax: three hyphens on a line of their own.

Above the divider.

***

Below the divider.

### Blockquote

> A blockquote for quoting text or calling out something memorable.
>
> Blockquotes can span multiple paragraphs and support *inline formatting*.

### Task lists

Markdown checkboxes render as visual task lists.

* [ ] Unchecked task
* [x] Completed task
* [ ] Another unchecked task
  * [x] Nested completed task
  * [ ] Nested unchecked task

### Code blocks

Syntax highlighting follows the language tag on the fence.

```javascript
// JavaScript
const greeting = "Hello GitBook";
console.log(greeting);
```

```python
# Python
def greet(name):
    return f"Hello, {name}"
```

```yaml
# YAML
config:
  timeout: 30
  retries: 3
```

### Tables

| Column A | Column B | Column C |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

### Lists

Unordered:

* First item
* Second item
  * Nested item
    * Double-nested item

Ordered:

1. First step
2. Second step
3. Third step
   1. Nested numbered
   2. Second nested

***

## Callouts (hint blocks)

### Basic styles

Four styles, each mapped to the callout vocabulary.

{% hint style="info" %}
**Prerequisites style.** Used for requirements the reader needs before starting a task.
{% endhint %}

{% hint style="success" %}
**Tip style.** Used for optional enhancements, shortcuts, or best-practice nudges.
{% endhint %}

{% hint style="warning" %}
**Important style.** Used for non-obvious constraints the reader will trip on if missed.
{% endhint %}

{% hint style="danger" %}
**Warning style.** Used for destructive or irreversible actions.
{% endhint %}

### Rich internal formatting

Hints accept most markdown inside them.

{% hint style="info" %}
**With a heading**

You need Admin permissions on the workspace.

This article assumes you have already connected at least one integration. If you have not, see the integrations overview first.
{% endhint %}

{% hint style="warning" %}
**With a list**

Switching between OAuth and service account will:

* Disconnect the current connection
* Invalidate any active tokens
* Require re-authorisation on the next sync

Save any pending configuration changes before proceeding.
{% endhint %}

{% hint style="success" %}
**With a code block:** use keyboard shortcuts to speed up common actions.

```
⌘ + K    Open quick search
⌘ + /    Show all shortcuts
⌘ + .    Toggle comments panel
```

{% endhint %}

{% hint style="danger" %}
**Multi-paragraph.** Deleting a persona is permanent. There is no undo and no archive for personas.

If you think you might need the persona later, archive related journey maps instead. Archived journeys can be restored with their persona assignments intact.

For bulk operations, export the workspace before deleting anything.
{% endhint %}

{% hint style="info" icon="books" %}
**Custom icon.** This hint uses a `books` icon instead of the default info icon.
{% endhint %}

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

#### Possible causes:

* [**Missing invitation** - They don't see the map in their sidebar at all](#missing-invitation-they-dont-see-the-map-in-their-sidebar-at-all)
* [**Permissions issue** - The map is visible but they can't edit it](#the-map-is-visible-but-they-cant-edit-it)
* [**Archived, moved or deleted** - The map used to be visible but has disappeared](#the-map-used-to-be-visible-but-has-disappeared)
* [**Wrong Account / Workspace** - They see different content or a different workspace](#wrong-account-workspace-they-see-different-content-or-a-different-workspace)
  {% endhint %}

***

## Sequential and comparison blocks

### Stepper

Sequential steps with visual progression. Steps accept nested formatting.

{% stepper %}
{% step %}
**Open Workspace Settings**

Click **Settings** in the workspace sidebar.

{% hint style="info" %}
The Settings option only appears if you are a Workspace Admin.
{% endhint %}
{% endstep %}

{% step %}
**Go to Manage users**

Select the **Manage users** tab.

You'll see three sections: active users, pending invitations, and viewers.
{% endstep %}

{% step %}
**Send the invite**

Enter an email, pick a role from the dropdown, and click **Invite**.

Available roles:

* **Admin**: full access to the workspace
* **Editor**: can create and edit content
* **Viewer**: read-only with commenting

The invite expires after 7 days.
{% endstep %}
{% endstepper %}

### Tabs

Used for genuine alternatives.

{% tabs %}
{% tab title="OAuth" %}
Sign in with your Google account. Access is tied to the individual user who authenticates.

**Best for:**

* Quick personal connections
* Single-user integrations
* Early testing
  {% endtab %}

{% tab title="Service account" %}
Upload a JSON service account file. Access is tied to the service, not a user.

**Best for:**

* Team-wide integrations
* Production setups
* Environments where user turnover should not break integrations
  {% endtab %}

{% tab title="API token" %}
For services that use token-based auth (like Qualtrics).

1. Generate a token in the third-party service
2. Copy it (tokens are usually shown once)
3. Paste into Smaply's configuration field
   {% endtab %}
   {% endtabs %}

### Columns

Side-by-side comparison. Maximum two columns.

{% columns %}
{% column %}
**Viewer role**

Can view journey maps and add comments. Cannot edit content, change structure, or manage users.

Best for:

* Stakeholders reviewing work
* Executives who want visibility
* Read-only cross-team access
  {% endcolumn %}

{% column %}
**Editor role**

Can view and edit content: create journey maps, add cards, manage personas, update portfolio items.

Best for:

* Core team members
* Researchers and designers
* Product managers
  {% endcolumn %}
  {% endcolumns %}

### Expandable

Optional deep-dives, collapsed by default.

<details>

<summary><strong>Advanced configuration options</strong></summary>

Content hidden by default. Readers expand if they need the detail.

**Configuration file:**

```yaml
advanced:
  refresh_interval: 3600
  max_retries: 3
  timeout: 30
```

**Options explained:**

* `refresh_interval`: how often the integration polls, in seconds
* `max_retries`: attempts before marking the connection as failed
* `timeout`: request timeout per call

</details>

***

## Navigation and reference blocks

### Cards

Visual navigation for Related topics and category landing pages.

<table data-view="cards" data-full-width="false"><thead><tr><th>Related topic</th><th>Short description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Test homepage</td><td>Back to the test space landing page</td><td><a href="/pages/kzTlst3tKo255yz4YpDi">/pages/kzTlst3tKo255yz4YpDi</a></td></tr><tr><td>Hint blocks</td><td>Jump to the hint blocks section of this article</td><td><a href="#hint-blocks-basic-styles">#hint-blocks-basic-styles</a></td></tr><tr><td>Stepper examples</td><td>See the stepper block with nested hints and lists</td><td><a href="#stepper-with-nested-blocks">#stepper-with-nested-blocks</a></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

### Updates (changelog style)

Dated entries in reverse chronological order. Good for release notes.

{% updates %}
{% update date="2026-04-23" %}

## Block showcase expanded

Added task lists, Mermaid diagrams, embeds, and explicit heading level examples.
{% endupdate %}

{% update date="2026-04-22" %}

## Sync testing

Set up the GitBook Git Sync test environment. Confirmed bi-directional sync and all custom blocks render correctly.
{% endupdate %}

{% update date="2026-04-15" %}

## Helpdesk workflow overhaul

Replaced the Haiku retrieval + Opus writer pipeline with a registry-driven multi-agent workflow.
{% endupdate %}
{% endupdates %}

***

## Rich media

### Images

Committed image (SVG in `.gitbook/assets/`):

![Committed SVG](/files/AniRzwaIUntJWkfIHni5)

External image by URL:

![External placeholder](https://placehold.co/600x300/e0e0e0/333333?text=External+Image+via+URL)

### File downloads

Inline downloadable file with caption. File blocks need a resolvable URL or GitBook silently drops them.

### Buttons

Primary and secondary styles, with optional icons.

<a href="https://smaply.com" class="button primary">Open Smaply</a>

<a href="https://smaply.com/docs" class="button secondary">Read the docs</a>

<a href="https://github.com/joe-smaply/test-gitbook" class="button primary" data-icon="github">View on GitHub</a>

### Embeds

External content (videos, interactive demos, social media).

YouTube:

{% embed url="<https://www.youtube.com/watch?v=39-WxZLf004>" %}

Loom (placeholder URL):

{% embed url="<https://www.loom.com/share/test-placeholder>" %}

***

## Diagrams

### Mermaid diagrams

Fenced code block with `mermaid` language tag. GitBook renders it as an interactive diagram.

**Flowchart:**

```mermaid
graph TD
    A[User opens journey map] --> B{Is map shared?}
    B -->|Yes| C[Viewer sees content]
    B -->|No| D[Access denied]
    C --> E{Has edit role?}
    E -->|Yes| F[Can edit content]
    E -->|No| G[Read-only view]
```

**Sequence diagram:**

```mermaid
sequenceDiagram
    participant User
    participant Smaply
    participant GoogleSheets
    User->>Smaply: Open journey map
    Smaply->>GoogleSheets: Request metric data
    GoogleSheets-->>Smaply: Return data
    Smaply->>User: Render metric card
```

***

## Dynamic content

### Variables and expressions

Variables defined in `.gitbook/vars.yaml` referenced dynamically via expressions.

**Current support email:** <code class="expression">space.vars.supportEmail</code>

**Current plan name:** <code class="expression">space.vars.currentPlan</code>

**Current year:** <code class="expression">space.vars.currentYear</code>

**Max workspaces on Ultimate plan:** <code class="expression">space.vars.maxWorkspacesUltimate</code>

**String concatenation:** <code class="expression">"Contact support at " + space.vars.supportEmail</code>

**Conditional:** <code class="expression">space.vars.currentPlan === "Ultimate" ? "You are on the top tier" : "Consider upgrading"</code>

### Inline icons

Icons in running text: the <i class="fa-check">:check:</i> icon indicates success, the <i class="fa-triangle-exclamation">:triangle-exclamation:</i> icon flags caution, and the <i class="fa-circle-info">:circle-info:</i> icon points at supplementary info.

Use sparingly. Icons work best as visual anchors in comparison tables or status indicators, not decoration in every paragraph.

***

## Card icon options (prototype)

Three ways to add a visual to overview-page cards, shown with the Journey Maps *Create and structure* grid so the options compare like-for-like. This is a prototype for choosing which treatment to roll out on category landing pages.

### Option A: icon in the title

Font Awesome glyph prepended to each card title. No image assets. Reuses the inline-icon convention already used in comparison tables.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-map">:map:</i> Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr><tr><td><h4><i class="fa-table-columns">:table-columns:</i> Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td></tr><tr><td><h4><i class="fa-clone">:clone:</i> Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td></tr></tbody></table>

### Option B: cover tile (soft tint)

Branded SVG cover in `.gitbook/assets/`. Soft warm-tint background with the brand-red glyph.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td><td><a href="/files/0dziZq262d7FbbLgykfq">/files/0dziZq262d7FbbLgykfq</a></td></tr><tr><td><h4>Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td><td><a href="/files/lzhRTbwhkI9ERJO9CO6b">/files/lzhRTbwhkI9ERJO9CO6b</a></td></tr><tr><td><h4>Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td><td><a href="/files/oWFRfSjbUPDGKBJZEBgb">/files/oWFRfSjbUPDGKBJZEBgb</a></td></tr></tbody></table>

### Option B: cover tile (solid red)

Same cover mechanism, saturated brand-red background with a white glyph.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td><td><a href="/files/CAWq4Y1kID7qWl2qWBEg">/files/CAWq4Y1kID7qWl2qWBEg</a></td></tr><tr><td><h4>Lanes and columns</h4></td><td>Build the grid of rows and steps that make up the map.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td><td><a href="/files/ERQj8t08Un4AXVnJ9eH7">/files/ERQj8t08Un4AXVnJ9eH7</a></td></tr><tr><td><h4>Cards</h4></td><td>The card types and what each one is for.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td><td><a href="/files/Rykxx9T96pqRQQqwaNAM">/files/Rykxx9T96pqRQQqwaNAM</a></td></tr></tbody></table>

***

## Spacer test

Each method sits between a **TOP** and **BOTTOM** marker. The gap between the two markers shows how much vertical space the method renders; reading the file back after sync shows what GitBook kept.

### A. Three blank lines

TOP A

BOTTOM A

### B. Empty centered paragraph (x2)

TOP B

BOTTOM B

### C. Non-breaking space paragraph (x2)

TOP C

&#x20;

&#x20;

BOTTOM C

### D. Space-entity paragraph (x2)

TOP D

BOTTOM D

### E. Break tags

TOP E

\
\ <br>

BOTTOM E

***

## Summary

If you're reading this and everything above renders correctly, GitBook sync is working end-to-end with the full feature set we'd use in the real helpdesk.


# Journey maps overview

Creating, structuring, and evolving journey maps in Smaply

Journey maps are the core artefact in Smaply. Create a map, build out its structure, fill it with cards, then filter, version, and refine it as your work evolves.

### Create and structure

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a journey map</h4></td><td>Start a new map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td><td><a href="/files/0dziZq262d7FbbLgykfq">/files/0dziZq262d7FbbLgykfq</a></td></tr><tr><td><h4>Lanes and columns</h4></td><td>Build the grid of rows and steps, including text, emotion chart, grid, and divider lanes.</td><td><a href="/pages/ZXxfwYY21Yz9PCv9X7ja">/pages/ZXxfwYY21Yz9PCv9X7ja</a></td><td><a href="/files/lzhRTbwhkI9ERJO9CO6b">/files/lzhRTbwhkI9ERJO9CO6b</a></td></tr><tr><td><h4>Cards</h4></td><td>The card types and what each is for, from text and stage to metric, planning, and embed.</td><td><a href="/pages/4HUzjikg0AfVJ2NlJRz9">/pages/4HUzjikg0AfVJ2NlJRz9</a></td><td><a href="/files/oWFRfSjbUPDGKBJZEBgb">/files/oWFRfSjbUPDGKBJZEBgb</a></td></tr></tbody></table>

<br>

***

### Add content

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Add and edit cards</h4></td><td>Add a card, edit it inline, and use the toolbar, details panel, colours, and multi-select.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td><td><a href="/files/szy31A7TJPqItjAw4XPo">/files/szy31A7TJPqItjAw4XPo</a></td></tr><tr><td><h4>Bulk edit cards</h4></td><td>Select many cards at once and tag, assign, format, or delete them together.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td><td><a href="/files/dPSpl0CH2H7YFFgX0GLI">/files/dPSpl0CH2H7YFFgX0GLI</a></td></tr><tr><td><h4>Enhanced paste</h4></td><td>Paste tables and text from Excel, Google, Miro, or Mural straight in as cards.</td><td><a href="/pages/8B3eINtya42YPRLS2j7a">/pages/8B3eINtya42YPRLS2j7a</a></td><td><a href="/files/ylURnhkv471WBQAVbcAL">/files/ylURnhkv471WBQAVbcAL</a></td></tr></tbody></table>

<br>

***

### Manage and navigate

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Filters and views</h4></td><td>Filter a map by lane, persona, tag, or portfolio item, and save views to reuse.</td><td><a href="/pages/QwHFLVleY7QejI9V4gc3">/pages/QwHFLVleY7QejI9V4gc3</a></td><td><a href="/files/vRGOt9dTWPwjQkgLFlUJ">/files/vRGOt9dTWPwjQkgLFlUJ</a></td></tr><tr><td><h4>Version history</h4></td><td>View earlier versions of a map and restore one in a new working copy.</td><td><a href="/pages/aLe0UdsSSiKGSOJEzvb8">/pages/aLe0UdsSSiKGSOJEzvb8</a></td><td><a href="/files/PvNntJz3VH0t6GisXZlO">/files/PvNntJz3VH0t6GisXZlO</a></td></tr><tr><td><h4>Keyboard shortcuts</h4></td><td>Speed up editing with the journey map editor's keyboard shortcuts.</td><td><a href="/pages/o36BXm16V4HFa0yNsHsC">/pages/o36BXm16V4HFa0yNsHsC</a></td><td><a href="/files/mMlojGAAheVu5fqXElLi">/files/mMlojGAAheVu5fqXElLi</a></td></tr></tbody></table>


# How to create a journey map

Start a new journey map and build it your way, with Smaply AI, from scratch, or from a template.

Go from nothing to a structured journey map in a few clicks. Create the map first, then pick how to fill it: let Smaply AI draft the whole thing from a sentence, start from a blank canvas, or open a template.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fap6qGEVWVilK3KytVoBw%2FHow%20to%20create%20and%20edit%20a%20journey%20map.mp4?alt=media&token=188f95b4-4db3-412f-bcd3-92ced03ca8e0>" %}

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

#### Prerequisites

You need the Editor or Admin role at the account or workspace level. Viewers cannot create journey maps.
{% endhint %}

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

#### Plan availability

Creating a journey map is available on all plans. The Free plan is capped at 10 maps total.

Smaply AI can generate up to 3 maps per month on Free, and is uncapped on Repository and above. It also depends on the account-level AI Features setting; if an Admin has turned AI off for the account, the option does not appear.

Your own saved templates require Repository. Built-in Smaply Templates are available on all plans.
{% endhint %}

#### How to start a new journey map

A new map starts the same way no matter how you plan to build it. Create the map, choose where it lives, and you land in the editor ready to fill it.

{% stepper %}
{% step %}
**Click + New journey on the Dashboard**

In the quick-create row at the top of the Dashboard, click **+ New journey**.

<figure><img src="/files/o6OtpAAJw2fepMFYgZR9" alt="The Dashboard of a workspace. A quick-create row near the top shows three buttons: + New journey, + New persona, and + New metric."><figcaption><p>Dashboard quick-create row</p></figcaption></figure>
{% endstep %}

{% step %}
**Choose where the map lives**

In the **New journey map** dialog, pick the **Account** and **Workspace** the map belongs to. Both default to the one you're working in, so if you only have one of each, this is a quick confirmation.

<figure><img src="/files/yQRF9TxKyYTTLLFzJXhm" alt="The New journey map dialog with the Workspace dropdown open, showing a list of workspaces to choose from. An Account dropdown sits above it."><figcaption><p>New journey map > choose Account and Workspace</p></figcaption></figure>
{% endstep %}

{% step %}
**Click Create**

Smaply creates the map, shows a brief **Setting up your map** screen, and opens it in the editor. The map is auto-named with the date and time; rename it any time from the title in the editor's top bar.

<figure><img src="/files/0iVs4rH1frYAXS7R1HUw" alt="The Create your journey map start screen inside the editor. A prompt field with a Generate button sits below the heading, with Try chips beneath it, and a Templates row showing a Blank journey card and several template cards."><figcaption><p>The start screen in the editor for a brand-new map</p></figcaption></figure>
{% endstep %}
{% endstepper %}

#### Choose how to build your map

A brand-new map opens on the **Create your journey map** start screen. Pick one of three ways to build it:

* [**With Smaply AI**](#with-smaply-ai) - Describe the journey in a sentence and let AI draft the stages, steps, and content. Fastest when you don't have an existing model to work from.
* [**Blank journey**](#blank-journey) - Start from an empty canvas and build it lane by lane. Best when you have a clear plan or want full control.
* [**From a template**](#from-a-template) - Open a pre-built structure for a common scenario. Best when your situation matches a known pattern.

{% tabs %}
{% tab title="With Smaply AI" %}
Smaply AI generates a complete first draft from a short description: a name, a structured description, color-coded stages with steps, and whichever extra lanes you ask for. Everything it produces is editable, so treat the result as a starting point you refine.

{% embed url="<https://www.youtube.com/watch?v=39-WxZLf004>" %}

{% stepper %}
{% step %}
**Describe the journey and click Generate**

Type a sentence describing the journey in the prompt field, then click **Generate**. To see the shape of a good prompt, click one of the **Try** chips (**B2C in-store return**, **B2B contract renewal**, or **Employee onboarding**).

<figure><img src="/files/IpP2TsLSe2TdiQthgJAJ" alt="The Create your journey map prompt field filled with a sentence describing a new customer opening an online savings account, with the Generate button enabled."><figcaption><p>Describe the journey, then Generate</p></figcaption></figure>

{% hint style="info" icon="language" %}
Smaply AI understands several languages but generates in English by default. To get your draft in another language, add a line like "Generate the content in German" to the prompt.
{% endhint %}
{% endstep %}

{% step %}
**Refine the name and description**

Smaply AI pre-fills a **Journey map name** and a structured **Journey map description** (User Goals, Business Goals, Journey Start, Journey End). Edit either freely. For a different angle, click **View** next to **Need inspiration?** to swap in another description style. Click **Generate journey steps** to continue.

<figure><img src="/files/iYs9lMdPJduJPbgiONyc" alt="Step 2 of the Smaply AI wizard, Refine your journey map name and description, showing an editable name field and a structured description with User Goals, Business Goals, Journey Start, and Journey End sections."><figcaption><p>Step 2 of 3, refine the name and description</p></figcaption></figure>
{% endstep %}

{% step %}
**Customize the stages and steps**

Smaply AI lays out color-coded stages with steps. Rename stages and steps inline, reorder them, delete what you don't need, or add more with **+ Add step** and **+ Add stage**. The **Journey structure preview** on the right updates as you go.

Use the **Quick add journey content** toggles to control how much AI scaffolds: **Stages and steps**, **Step descriptions**, **Emotion chart**, **Storyboard images**, **Channels**, and **Satisfaction slider**. Click **Add to Journey Map** to build the map.

<figure><img src="/files/wiEm9TSYf4g2wX6aMiqU" alt="Step 3 of the Smaply AI wizard, Customize stages and steps. The left pane lists editable color-coded stages with their steps; the right pane shows a journey structure preview and a Quick add journey content section with toggles for Stages and steps, Step descriptions, Emotion chart, Storyboard images, Channels, and Satisfaction slider."><figcaption><p>Step 3 of 3, customize stages and choose what to populate</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The generated map opens in the editor with the lanes you selected populated and ready to edit.
{% endtab %}

{% tab title="Blank journey" %}
On the start screen, click the **Blank journey** card in the **Templates** row.

The map opens as an empty canvas with a single **Stage** lane, ready for you to build out. Add the lanes, columns, and cards you need:

* [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes)
* [How to add and manage columns](/journey-maps/lanes/how-to-add-and-manage-columns)
* [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards)
* [How to use stage cards](/journey-maps/cards/how-to-use-stage-cards)
  {% endtab %}

{% tab title="From a template" %}
On the start screen, pick a template card from the **Templates** row. **Smaply Templates** are built-in and available on every plan; your own saved templates appear here too. The map opens with the template's structure already in place, ready to edit.

<figure><img src="/files/l2vKhP6gvcBuiZRyx3uc" alt="The Templates row on the start screen. The first card is Blank journey; the rest are templates, including a built-in Smaply Template and account-specific templates."><figcaption><p>The Templates row on the start screen</p></figcaption></figure>

The template cards you see are specific to your account. To save a map you've built as a reusable template, see [How to create and use templates](/account-and-team/customization/how-to-create-and-use-templates).
{% endtab %}
{% endtabs %}

#### 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 manage lanes</strong></td><td>Add, rename, reorder, pin, and delete the rows of your map.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards, edit them inline, and use the toolbar and details panel.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use stage cards</strong></td><td>Build the high-level phases across the top of your map.</td><td><a href="/pages/YeVZqUkvqujOSrFxYHsT">/pages/YeVZqUkvqujOSrFxYHsT</a></td></tr><tr><td><strong>How to create and use templates</strong></td><td>Save a map as a template and reuse it for new maps.</td><td><a href="/pages/LY87TNBIxycYQoy5aUly">/pages/LY87TNBIxycYQoy5aUly</a></td></tr><tr><td><strong>How to import from image</strong></td><td>Already have a map elsewhere? Rebuild it in Smaply from a screenshot.</td><td><a href="/pages/gUbzvZgq0NRwr87aVZTt">/pages/gUbzvZgq0NRwr87aVZTt</a></td></tr></tbody></table>


# Cards

All card types and how to use them in journey maps

Cards are the atomic content units of a journey map. Any card type can go in any lane; lane types only set the default card type for convenience.

#### Why use cards

* Capture every kind of journey content - text, images, sentiment, metrics, work items, and more - in one consistent unit
* Mix card types freely across any lane, so the grid holds exactly the content each row needs

#### In this section

* [**Add and edit cards**](/journey-maps/cards/how-to-add-and-edit-cards) - General flow for adding and editing cards.
* [**Stage cards**](/journey-maps/cards/how-to-use-stage-cards) - Label and organise the high-level phases of a journey map.
* [**Text cards**](/journey-maps/cards/how-to-use-text-cards) - Add and format text content.
* [**Image cards**](/journey-maps/cards/how-to-use-image-cards) - Add images and adjust their display.
* [**Slider cards**](/journey-maps/cards/how-to-use-slider-cards) - Rating or scoring cards.
* [**Icon cards**](/journey-maps/cards/how-to-use-icon-cards) - Icon-based cards for quick visual markers.
* [**Embed cards**](/journey-maps/cards/how-to-use-embed-cards) - Embed content from Figma, Google Docs, YouTube, and more.
* [**Metric cards**](/journey-maps/cards/how-to-use-metric-cards) - Display metrics on a journey map.
* [**Planning cards**](/journey-maps/cards/how-to-use-planning-cards) - Link work items from external planning tools.
* [**Portfolio item cards**](/journey-maps/cards/how-to-use-portfolio-item-cards) - Add portfolio items to a journey map.
* [**Linked map cards**](/journey-maps/cards/how-to-use-linked-journey-map-cards) - Link to another journey map from a card.
* [**Comment on a card**](/journey-maps/cards/how-to-comment-on-a-card) - Add comments to any card, @mention teammates, and delete comments.


# How to add and edit cards

Add cards to a journey map, edit their content, and use the card details panel to manage tags, personas, and comments.

Cards are how content lands on a journey map. Add them through the in-lane picker, edit them via the floating toolbar, and manage tags, personas, and comments from the card details panel.

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

#### In this guide

1. [How to add a card](#how-to-add-a-card)
2. [How to edit a card](#how-to-edit-a-card)
3. [The card toolbar](#the-card-toolbar)
4. [The card details panel](#the-card-details-panel)
5. [Card color and background style](#card-color-and-background-style)
6. [Card header](#card-header)
7. [Span a card across columns](#span-a-card-across-columns)
8. [Set a card's height](#set-a-cards-height)
9. [Select multiple cards](#select-multiple-cards)
10. [Card types](#card-types)
    {% endhint %}

***

#### How to add a card

Each lane has a default card type that matches its purpose (a Text lane defaults to text cards, a Stage lane to stage cards, and so on), but any card type can sit in any lane.

{% stepper %}
{% step %}
**Hover where you want the card**

The **+ Add card** button appears on hover at the position you point to: above, below, or between existing cards, or in an empty cell. Wherever the button shows is where the new card lands.

<figure><img src="/files/e5vR5o856zMwQjBxVWbt" alt="A journey map canvas with the Add card button revealed below the Review past performance data text card in the Journey Steps lane. The button shows a plus icon and the label + Add card on a blue background."><figcaption><p>+ Add card revealed on hover</p></figcaption></figure>
{% endstep %}

{% step %}
**Click + Add card**

The card type picker opens with a search box at the top, the lane's default card type as a quick-select (with an Enter shortcut), and two grouped sections below: **BASIC CARDS** (Image, Stage, Icons, Slider) and **ADVANCED CARDS** (Embed, Planning, Metric, Link journey map, Opportunity, Pain point, Solution, Custom Card). The button and picker are the same in every position.

<figure><img src="/files/Sz8Et6R64At7WeBTYav3" alt="The card type picker open below an + Add card button. A search field at the top, then a highlighted Text quick-select with an Enter return hint. Below, a BASIC CARDS group lists Image, Stage, Icons, and Slider. Below that, an ADVANCED CARDS group starts with Embed, Planning, and Metric."><figcaption><p>Card type picker, opened in a Text lane</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a card type**

Press Enter to add the lane default, or click any type from the picker. Start typing in the search box to narrow the list. The new card appears in the slot and is ready to edit.
{% endstep %}
{% endstepper %}

Picking **Metric** or a portfolio item type (**Opportunity**, **Pain point**, **Solution**, or a custom type) opens a picker of existing items instead of dropping an empty card. You can select several items there and add them in one go, and the confirm button shows the count, like **Add 2**.

{% hint style="info" icon="tag" %}
Which card types appear in the picker depends on your plan. On lower plans, some advanced types are hidden.
{% endhint %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Paste content from a spreadsheet to create multiple cards at once**

If you're starting from rows in a spreadsheet, [How to use enhanced paste](/journey-maps/how-to-use-enhanced-paste) covers the bulk-create flow.
{% endhint %}

***

#### How to edit a card

{% stepper %}
{% step %}
**Click the card to select it**

A blue outline appears around the card and the floating **card toolbar** opens above it. The card is in selected state, not edit state.
{% endstep %}

{% step %}
**Click into the card body to edit text**

On text and stage cards, clicking into the body puts you in inline edit mode. Type to add or change content. Other card types use their own modals or details-panel fields for editing (see [Card types](#card-types) below).
{% endstep %}

{% step %}
**Use the toolbar for everything else**

Color, header, span, delete, duplicate, and the card details panel all open from the floating toolbar described in the next section.
{% endstep %}
{% endstepper %}

Edits autosave as you type. Most card types have no Save button; metric cards and portfolio item cards are the exceptions and save their data via a Save button inside the card details panel.

***

#### The card toolbar

The toolbar floats above any selected card. The first four buttons (bold, font size, font family, list style) appear only on text and stage cards, where the body text is editable. Every card has the last five.

<figure><img src="/files/qmqjQl84O3cefDlSofti" alt="A Text card &#x27;Review past performance data&#x27; selected on a journey map. The floating card toolbar sits directly above the card. From left: a bold B with chevron, a 14 with chevron for font size, an A for font family with chevron, a bulleted-list icon with chevron, a paint-bucket icon, a small horizontal-bar icon for the card header, a square-with-arrows icon for show card details, a trash icon, and a three-dot vertical icon."><figcaption><p>Floating card toolbar on a selected Text card</p></figcaption></figure>

| Button             | Tooltip           | What it does                                                                                                          |
| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| **B**              | Bold              | Toggles bold on the selected text. Text and stage cards only.                                                         |
| **14**             | Font size         | Sets the font size. Text and stage cards only.                                                                        |
| **A** (serif)      | Font family       | Switches font. Text and stage cards only.                                                                             |
| List icon          | List style        | Bullet or numbered list. Text and stage cards only.                                                                   |
| Paint bucket       | (color/styling)   | Opens the color and background style picker. See [Card color and background style](#card-color-and-background-style). |
| Small bar          | Card header       | Opens the header popover. See [Card header](#card-header).                                                            |
| Square with arrows | Show card details | Opens the card details panel on the right.                                                                            |
| Trash              | Delete card       | Removes the card. Cmd+Z (or Ctrl+Z) undoes the delete.                                                                |
| Three-dot          | (more)            | Opens the overflow menu (Duplicate, Card details, Expand, Shrink, Height, Delete).                                    |

The three-dot menu mirrors a few toolbar options and adds keyboard shortcuts. **Duplicate** has Cmd+D (or Ctrl+D). **Expand** widens the card by one column; **Shrink** narrows by one (greyed out when the card already spans a single column). **Height** opens a submenu to fix the card's height instead of letting it grow with content - see [Set a card's height](#set-a-cards-height) below. **Delete** has the Delete key shortcut.

<figure><img src="/files/jaZL6aI3w4fh2sJaoURE" alt="The three-dot overflow menu open from the card toolbar. Items listed top to bottom: Duplicate with CMD + D shortcut, Card details, Expand, Shrink (greyed out), Height, Delete with the Delete key shortcut."><figcaption><p>Three-dot menu on the card toolbar</p></figcaption></figure>

***

#### The card details panel

The card details panel slides in from the right and holds metadata that doesn't fit on the card face. Open it three ways:

* Click **Show card details** (the square-with-arrows icon) on the card toolbar.
* Click the three-dot menu and choose **Card details**.
* Double-click the card.

<figure><img src="/files/mW1dDXdbhOY5evRHs098" alt="The card details panel open on the right side of the canvas. The panel header reads Text, with a pin-panel icon and a close icon top-right. Three expanded sections: Personas (a Sarah from product chip with an edit pencil and remove X, plus an Add a persona dropdown), Card tags (an empty placeholder reading Add card tags with a + Add card tags button), and Comments (0) with an Add a comment textbox."><figcaption><p>Card details panel for a Text card</p></figcaption></figure>

The panel header shows the card's type (in the screenshot, **Text**). Three sections appear at the bottom of the panel on every card type, in this order:

* **Personas** - Assigned personas appear as chips. Use **Add a persona** to assign more. For the dedicated flow, see [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).
* **Card tags** - Card-level tags for filtering and grouping. **+ Add card tags** opens the tag picker.
* **Comments** - Comments on this card. The count in the heading reflects how many comments exist. See [How to comment on a card](/journey-maps/cards/how-to-comment-on-a-card).

For Text cards, those three sections are the whole panel. Other card types add per-type sections **above** Personas, where the card's specific data lives (an image and its caption for Image cards, a metric selector for Metric cards, a linked-item picker for Planning cards, and so on). The per-card-type articles linked under [Card types](#card-types) cover those.

***

#### Card color and background style

Open the color picker by clicking the paint-bucket icon on the toolbar.

<figure><img src="/files/h6r4Cm9C0el66J0wkx9x" alt="Changing a card&#x27;s accent color and background style from the toolbar color picker."><figcaption><p>Changing a card's color and background style</p></figcaption></figure>

<figure><img src="/files/Z49KVo7LvfMcETIJEM3e" alt="The color and styling picker open above a selected Text card. Top row: seven primary accent color swatches (red, orange, yellow, green, blue, indigo, purple). Second row: five secondary swatches (white, light grey, medium grey, black, and a no-color option shown as white with a red strikethrough), plus a chevron-down for more. Below: a Brand colors section with one custom blue swatch and an edit icon. Below that: a Background style section listing Light background, White background, Solid background, and Transparent background, each with a small preview icon."><figcaption><p>Color and background style picker</p></figcaption></figure>

The picker has two parts:

* **Accent color** - Seven primary swatches on the top row, five secondary swatches on the second (including a "no color" option with a red strikethrough). Brand colors set up for the account appear below. Accent color drives the colored bar at the bottom of the card.
* **Background style** - Four named styles control how the card body fills:
  * **Light background** (default) - Soft tinted fill matched to the accent.
  * **White background** - Solid white card body, accent shown only on the bottom bar.
  * **Solid background** - The accent color fills the whole card body.
  * **Transparent background** - No fill, accent shown only on the bottom bar.

Changes apply immediately. There's no apply or save action on the picker.

***

#### Card header

A card header is an optional colored bar at the top of the card with a title and an icon. Headers help signal what kind of content the card holds (a touchpoint, a channel, a system) at a glance.

{% stepper %}
{% step %}
**Open the Card header popover**

With the card selected, click the **Card header** icon (small horizontal bar) on the toolbar.
{% endstep %}

{% step %}
**Tick Enable**

The header bar appears immediately on the card. The default text reads **YOUR TITLE** until you change it.

<figure><img src="/files/T6gcNJ63MF3Hn6R65Gx5" alt="The Card header popover open beside the canvas. Top row reads Header with an Enable checkbox on the right. Below: a small color-swatch square and a text input field showing the placeholder YOUR TITLE. Then a color palette: seven primary swatches on the first row, five secondary swatches on the second, with a chevron-down. A Brand colors section follows with one custom blue swatch. Below: an Icon section labeled with a &#x27;View more&#x27; link, showing a grid of standard icons. The selected Text card on the left now shows a YOUR TITLE header bar at its top."><figcaption><p>Card header popover with the bar enabled</p></figcaption></figure>
{% endstep %}

{% step %}
**Type your title and pick a color and icon**

The header's accent color is independent of the card body's accent. Click an icon from the grid to add one, or click **View more** to open the full library.
{% endstep %}

{% step %}
**Close the popover**

Click outside the popover to close it. The header stays on the card. To remove it later, reopen the popover and uncheck **Enable**.
{% endstep %}
{% endstepper %}

***

#### Span a card across columns

Drag the right edge of a card to make it span more columns. The card snaps to column boundaries as you drag, so you can't leave it half-way across a column.

<figure><img src="/files/NakYttaKjEG01SJN8YmK" alt="Dragging the right edge of a card to extend it across more columns."><figcaption><p>Dragging a card edge to span columns</p></figcaption></figure>

<figure><img src="/files/wXWLHNK72cfLTLXBln4F" alt="A journey map canvas showing a Stage card titled Prepare for Renewal in the Journey Stages lane. The stage card spans all four visible columns of the map, with the lane below containing four separate text cards (Review past performance data, Analyze current contract terms, Develop renewal strategy, Align with internal stakeholders) one per column."><figcaption><p>A Stage card spanning four columns in the Journey Stages lane</p></figcaption></figure>

You can also span via the toolbar's three-dot menu: **Expand** widens the card by one column, **Shrink** narrows by one. **Shrink** is greyed out when a card already sits in a single column.

When you drag one stage card past another in the same lane, the other card moves to a new row in that lane so both stay visible.

***

#### Set a card's height

By default, a card's height grows and shrinks with its content, so cards with different amounts of text can end up at different heights even in the same lane. Open the three-dot menu and choose **Height** to fix cards to a matching size instead, so a lane's cards line up for a tidier, more consistent-looking map.

<figure><img src="/files/QWvAlu0L8X4x1ftH9Ivd" alt="The Height submenu open from the card&#x27;s three-dot menu, listing Auto (grows with content), Small at 40 px, Medium at 80 px, Large at 160 px, and Custom."><figcaption><p>Height submenu on the three-dot menu</p></figcaption></figure>

* **Auto** (default) - The card grows and shrinks to fit its content.
* **Small**, **Medium**, **Large** - Fixed heights of 40, 80, and 160 pixels.
* **Custom** - Enter any height from 40 to 400 pixels.

<figure><img src="/files/28U8ucDgXCB2QmdkndqJ" alt="The Custom height option open in the Height submenu, showing a number input labelled Custom height in pixels with helper text reading 40-400 px."><figcaption><p>Setting a custom height</p></figcaption></figure>

When a fixed height leaves extra room below the content, the content centers vertically in that space rather than sitting at the top. If the content is taller than the fixed height, it's clipped, with a small chevron at the bottom you can click to expand the card and see the rest.

Height is set per card, not per row or lane, so cards in the same row can each use a different height. It's available on text and stage cards - the same card types where you can edit body text directly (see [The card toolbar](#the-card-toolbar) above). Other card types, such as Image, Icon, Slider, Embed, Planning, Metric, Linked journey map, and Portfolio item cards, don't have a Height option. Switch back to **Auto** at any time to return to content-driven height.

**To give every card in a lane a matching height**, use Height on a multi-card selection instead of setting each card one by one. Select all the cards in a lane (or Shift+click several), then open the same **Height** menu from the bulk toolbar. Bulk selections add one extra option, **Match largest**, which sets every selected card to the height of the tallest one in the selection - the fastest way to line up a lane without picking a pixel value yourself. See [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards) for the full walkthrough.

***

#### Select multiple cards

Shift+click a second card while one is already selected to add it to the selection. The card toolbar above the individual cards disappears and a **Bulk edit** toolbar appears at the bottom of the viewport.

<figure><img src="/files/G1xygbDQiYOZLKLR7PdX" alt="Two text cards selected on a journey map: Review past performance data and Analyze current contract terms, each with a blue selection border. The bulk-edit toolbar sits at the bottom of the viewport: a close X on the left, a Bulk edit label with a 2 text cards count below it, then formatting controls (bold, font size 14, font family A, paint-bucket), then Header, Tags, Persona, and Delete buttons."><figcaption><p>Two text cards selected, bulk-edit toolbar at the bottom</p></figcaption></figure>

The bulk toolbar shows the count and card type ("2 text cards" here). When you mix card types in a selection, the formatting buttons drop off and only **Tags**, **Persona**, and **Delete** remain. For the full bulk-edit walkthrough including header, color, and font changes across many cards, see [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards).

***

#### Card types

| Card type                   | What it's for                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text card**               | Free-form text content. The default in Text lanes. See [How to use text cards](/journey-maps/cards/how-to-use-text-cards).                                          |
| **Stage card**              | Marks a stage across one or more columns. See [How to use stage cards](/journey-maps/cards/how-to-use-stage-cards).                                                 |
| **Image card**              | Display an image, optionally with a caption. See [How to use image cards](/journey-maps/cards/how-to-use-image-cards).                                              |
| **Slider card**             | One or more sliders between two labels, for ratings or scores. See [How to use slider cards](/journey-maps/cards/how-to-use-slider-cards).                          |
| **Icon card**               | Choose from preset icon templates. See [How to use icon cards](/journey-maps/cards/how-to-use-icon-cards).                                                          |
| **Embed card**              | Embed external content (Figma, YouTube, Google Docs, and similar). See [How to use embed cards](/journey-maps/cards/how-to-use-embed-cards).                        |
| **Metric card**             | Show a live metric from a connected data source. See [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).                                        |
| **Planning card**           | Link a work item from Jira, Asana, Linear, or another planning tool. See [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).                |
| **Portfolio item card**     | Display an opportunity, pain point, solution, or custom portfolio item. See [How to use portfolio item cards](/journey-maps/cards/how-to-use-portfolio-item-cards). |
| **Linked journey map card** | Link to another journey map and surface its summary. See [How to use linked journey map cards](/journey-maps/cards/how-to-use-linked-journey-map-cards).            |
| **Comments**                | Comments aren't a card type; they're available on every card. See [How to comment on a card](/journey-maps/cards/how-to-comment-on-a-card).                         |

***

#### 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>Bulk edit cards</strong></td><td>Edit tags, personas, colors, and headers across many cards at once.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr><tr><td><strong>Use enhanced paste</strong></td><td>Turn rows from a spreadsheet into multiple cards in one paste.</td><td><a href="/pages/8B3eINtya42YPRLS2j7a">/pages/8B3eINtya42YPRLS2j7a</a></td></tr><tr><td><strong>Add and manage lanes</strong></td><td>Add, rename, reorder, and delete lanes on a journey map.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>Add and manage columns</strong></td><td>Add columns between existing ones, reorder, and remove.</td><td><a href="/pages/WNBA1RdaCt3rMhxOcLHD">/pages/WNBA1RdaCt3rMhxOcLHD</a></td></tr><tr><td><strong>Assign a persona to a card</strong></td><td>Tag a card with one or more personas from the card details panel.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>Comment on a card</strong></td><td>Add comments, @mention teammates, and delete comments on a card.</td><td><a href="/pages/Kk7GjJu76NovaA8LF2EL">/pages/Kk7GjJu76NovaA8LF2EL</a></td></tr></tbody></table>


# How to use stage cards

Label and organise the high-level phases of a customer experience, with each phase spanning the steps it covers.

Stage cards mark the major phases of a journey, like Discover, Onboard, or Support. Each one is a chevron-shaped card that sits in the Stages lane above your steps and stretches across as many step columns as the phase covers.

<figure><img src="/files/yvqart2IcfUz92p5AB2X" alt="A journey map editor with a Stages lane at the top. A blue chevron-shaped stage card labelled Discover &#x26; Apply spans several step columns, followed by a yellow stage card labelled Activate &#x26; Onboard. Below the Stages lane, a Steps lane holds text cards reading Research Account Options, Start Online Application, Submit Documents &#x26; Information, and Receive Account Approval."><figcaption><p>A stage card spans the step columns that belong to one phase</p></figcaption></figure>

A blank journey opens with one Stages lane and one empty stage card. To add another, hover an empty cell and click **+ Add card**, then choose **Stage**. In a Stages lane, **Stage** is the Enter quick-select; in any other lane it sits under **BASIC CARDS** in the picker.

***

#### How to label a phase

Click into the stage card and type. The text you enter becomes the phase label, and changes save automatically.

<figure><img src="/files/cwsrTAZ3mM0xtFYZwAh2" alt="A selected stage card labelled Discover &#x26; Apply with a blue selection border and a chevron-shaped right edge. The floating toolbar above shows bold, font size 14, font, list formatting, fill colour, show card details, delete, and a three-dot overflow menu."><figcaption><p>Click into the card to edit the label</p></figcaption></figure>

The floating toolbar above a selected stage card carries the same text formatting as a text card: bold, font size, font, list formatting, and the **fill** control for accent colour and background style. Stage cards are one of two card types you edit inline; every other type opens its own configuration UI.

***

#### How to span a stage card across step columns

The defining behaviour of a stage card is that it stretches across the step columns its phase covers. You can resize it by dragging or from the overflow menu.

{% stepper %}
{% step %}
**Select the stage card**

Click the card once to select it. A selection border appears around the chevron and the floating toolbar opens above it.
{% endstep %}

{% step %}
**Drag the right edge, or use Expand and Shrink**

Drag the right edge of the card to cover more or fewer columns. It snaps to column boundaries as you drag. For single-column steps, open the toolbar's three-dot menu and use **Expand** to add a column or **Shrink** to remove one.
{% endstep %}
{% endstepper %}

<figure><img src="/files/zogEXRBdgs4AEMmjh44b" alt="A stage card labelled Discover &#x26; Apply selected and spanning three step columns, with a chevron-shaped right edge and its floating toolbar above. The step cards Research Account Options, Start Online Application, and Submit Documents &#x26; Information sit in the columns beneath it."><figcaption><p>The selected stage card spans the three step columns beneath it</p></figcaption></figure>

The chevron points forward to signal the progression from one phase to the next. When two stage cards sit side by side, the leftmost card's point tucks under the next card's left edge.

{% hint style="warning" %}

#### **Important: Spanning over another stage card moves it to a new row**

If you span a stage card into a column where another stage card already sits, the overlapped card moves to a new row in the same lane instead of being overwritten. The lane grows taller to hold the extra row.
{% endhint %}

<figure><img src="/files/0mHEslKETgbwYAyzfpzY" alt="A Stages lane with the Discover &#x26; Apply stage card spanning across the top row, and a second blank chevron-shaped stage card pushed down to a new row underneath because its column is already covered by the spanning card."><figcaption><p>A second stage card drops to a new row when its column is already spanned</p></figcaption></figure>

***

#### What stage cards share with other cards

Stage cards use the same toolbar, 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.

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

***

#### 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 add and manage lanes</strong></td><td>Add the Stages lane that holds your stage cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to add and manage columns</strong></td><td>Set up the step columns that stage cards span across.</td><td><a href="/pages/WNBA1RdaCt3rMhxOcLHD">/pages/WNBA1RdaCt3rMhxOcLHD</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple stage cards and apply tags, personas, or formatting in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr><tr><td><strong>How to filter a journey map</strong></td><td>Filter the map by persona or tag to focus on the stages that matter.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr></tbody></table>


# How to use text cards

Write narrative notes, descriptions, and explanations on a card, then format the text with bold, colour, alignment, lists, and your choice of font.

Text cards are the free-form cards you type narrative into: descriptions, notes, and explanations that sit alongside the steps of a journey. They are the default card in a Text lane and in Grid cells, and the on-card toolbar gives you the full set of text-formatting controls.

<figure><img src="/files/BQkTTiBJlc98xs925gcx" alt="A selected text card reading Customer compares savings account options and reads reviews before applying, with a blue selection border and a floating formatting toolbar above it showing bold, font size 14, a boxed A menu, list, fill colour, card header, card details, delete, and a three-dot menu."><figcaption><p>A selected text card with its formatting toolbar</p></figcaption></figure>

To add one, hover an empty cell in any lane and click **+ Add card**. **Text** is the default in a Text lane (press Enter to confirm) and sits in the **BASIC CARDS** group of the picker in any other lane, marked with a green TT icon.

<figure><img src="/files/TkoYxrpgtklCE28qTpF7" alt="The Add card picker open below a Research Account Options card, with a search box reading Type to search, a highlighted quick-select row, and a BASIC CARDS group listing Text with a green TT icon, Image, Icons, and Slider, followed by ADVANCED CARDS."><figcaption><p>+ Add card picker, Text under BASIC CARDS</p></figcaption></figure>

***

#### How to edit the text on a card

Click into the card and type. Text cards edit inline, so what you type is the card's content, and changes save as you go without a Save button. Click out of the card or into another to finish.

Pasting works two ways, and they behave differently. Paste into a card's text editor and any incoming formatting is cleared, so the text matches the card. Paste into a lane and the content fans out into multiple cards across the lane instead, one per row or line, which is how you turn a spreadsheet or a list into cards in one go. For that path, see [How to use enhanced paste](/journey-maps/how-to-use-enhanced-paste).

***

#### How to format the text in a text card

With a text card selected, the floating toolbar above it carries the formatting controls. Left to right: **B** for bold, the font size, the boxed **A** menu, a bulleted **list**, and the fill (paint bucket) for the card's colour and background. The controls to the right of the fill (card header, card details, delete, and the three-dot menu) are shared with every card type and are covered in the parent article.

The boxed **A** opens the rest of the text formatting in a single menu:

<figure><img src="/files/U2PB0JwDWN4XLGhRDW3W" alt="The boxed A menu open on a selected text card, listing Highlight, Color, Link, Left align, Center align, Right align, and Font, each of the first three and the last showing a submenu arrow."><figcaption><p>The boxed A menu holds highlight, colour, link, alignment, and font</p></figcaption></figure>

* **Highlight** - apply a highlight colour behind the text.
* **Color** - set the text colour.
* **Link** - turn selected text into a link.
* **Left align**, **Center align**, **Right align** - align the text in the card.
* **Font** - choose the font for the text.

Use the toolbar's font-size control and the **B** bold button alongside these. The bulleted **list** control and the fill sit directly on the toolbar rather than in this menu.

{% hint style="info" %}
The card's accent colour and background style are set with the fill control and are shared across card types, so they are covered in the parent article. A text card also takes its colour from its lane, which you set on the lane itself.
{% endhint %}

***

#### How to format many text cards at once

To format more than one card together, select the cards, then filter the selection to **Text**. With the selection narrowed to text cards, styling and text-formatting actions apply to all of them at once.

<figure><img src="/files/fby3u5AhpCJmYkRQbRLU" alt="A bulk-selection filter menu listing card types with counts (Text 4, Image 2, Icons 1, Slider 1, Pain point 1, Opportunity 1) above a bulk-action bar showing Filter 10 items, Tags, Persona, and Delete."><figcaption><p>Filter a multi-card selection to Text to format them together</p></figcaption></figure>

See [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards) for the full bulk-selection flow.

***

#### How to span a text card across columns

A text card can stretch across more than one column, which is useful for labelling a process or phase that runs over several steps, for example a process bar in a Grid lane. Select the card, open the three-dot menu, and click **Expand** to grow it one column at a time; **Shrink** pulls it back and stays greyed out until the card spans more than one column. The keyboard shortcuts are the Right arrow to expand and the Left arrow to shrink.

<figure><img src="/files/jlR8l7F41xKO0zNoRxIs" alt="A text card reading Customer compares savings account options and reads reviews before applying, selected and spanning the three step columns of the Discover and Apply stage in a journey map editor."><figcaption><p>A text card spanned across three step columns</p></figcaption></figure>

In a Grid lane, spanned text cards are how you build horizontal process bars across the grid.

<figure><img src="/files/xgkfVutga5rPwY1hE7Ly" alt="A Grid lane titled Process Overview with rows System A to D and text cards spanned horizontally across columns to form coloured process bars, including a green bar labelled Process B and a yellow bar labelled Process C."><figcaption><p>Grid lane: processes made of spanned text cards</p></figcaption></figure>

For the lanes and columns that text cards span, see [How to use grid lanes](/journey-maps/lanes/how-to-use-grid-lanes) and [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes).

***

#### What text cards share with other cards

Text cards use the same toolbar tail, card details panel, and colour system as every other card type. The defining feature of a text card is the text formatting above; the rest is shared:

* Accent colour, background style, and card header (the fill control and the controls after it)
* Card details panel for personas, tags, and comments
* Duplicate, expand, shrink, height, and delete from the three-dot menu
* Multi-select with Shift+click

See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the canonical walkthrough of these mechanics. Inline editing is shared with stage cards; see [How to use stage cards](/journey-maps/cards/how-to-use-stage-cards).

***

#### 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 tail, details panel, colours, and headers.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use stage cards</strong></td><td>Mark the phases of a journey with stage cards, which also edit inline.</td><td><a href="/pages/YeVZqUkvqujOSrFxYHsT">/pages/YeVZqUkvqujOSrFxYHsT</a></td></tr><tr><td><strong>How to use enhanced paste</strong></td><td>Paste a spreadsheet or list into a lane to fan it out into many cards at once.</td><td><a href="/pages/8B3eINtya42YPRLS2j7a">/pages/8B3eINtya42YPRLS2j7a</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards, filter to Text, and apply formatting or tags in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</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>


# How to use image cards

Add an image to a journey map, set how it sits in its card, and swap it out whenever you need a different visual.

Image cards put a visual on the map: a storyboard frame, a screenshot, a photo of a research artefact, or anything that carries more than words can. Pick an image from Unsplash or Giphy or upload your own, then adjust how it fits the card.

<figure><img src="/files/hJuTl4ehtjdeJJtVlltI" alt="A journey map lane labelled Storyboard holding an image card. The card shows a photo of a person typing on a laptop, with a small attribution credit in the bottom-right corner of the image."><figcaption><p>An image card in a journey map lane</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**, then choose **Image**. **Image** is the default in an Image lane (press Enter to confirm) and sits under **BASIC CARDS** in the picker in any other lane. The **Add image** chooser opens straight away so you can pick the image as you add the card.

***

#### How to choose an image for the card

The **Add image** chooser gives you two built-in sources and an upload option. Unsplash and Giphy both work without a login, and the credit for a chosen image shows on the card automatically.

<figure><img src="/files/NQfb7UMfViiHeUgwBQGN" alt="The Add image chooser with an Unsplash tab selected and a Giphy tab beside it. Below is a search field with a Search button, an OR divider, and an upload dropzone reading Upload a file or drag and drop, JPG, PNG, GIF or SVG up to 3.5MB."><figcaption><p>Add image chooser: Unsplash, Giphy, or upload</p></figcaption></figure>

{% stepper %}
{% step %}
**Pick a source**

Stay on the **Unsplash** tab for stock photography, or click **Giphy** for animated GIFs. To use your own file instead, skip to uploading below.
{% endstep %}

{% step %}
**Search, or upload your own**

Type a term in the search field and click **Search** to browse results from the selected source, then click an image to place it on the card. To use a local file, click **Upload a file** or drag and drop it onto the dropzone. Uploads accept JPG, PNG, GIF, or SVG up to 3.5MB.
{% endstep %}
{% endstepper %}

***

#### How to adjust the way an image displays

With an image card selected, the left-most button on the floating toolbar opens the image display options. Use them to control how the image sits inside the card without changing the image itself.

<figure><img src="/files/JZMgnTfWW4BndhoymrdO" alt="The image card toolbar with its left-most dropdown open, listing Shape, Align, and Padding (each with a submenu arrow) and a Reset action below them."><figcaption><p>Image display options on the toolbar</p></figcaption></figure>

* **Shape** - crop the image to a preset shape: Original, Square 1:1, Portrait 3:4, Landscape 4:3, Circle, or Message.
* **Align** - position the image within the card, vertically (top, center, bottom) and horizontally (left, center, right).
* **Padding** - set the space around the image: None, Small, Medium, or Large.
* **Reset** - restore the display settings to their defaults.

To see the image on its own, click **Full screen** on the toolbar (the icon beside the display-options dropdown). The same **Full screen** button sits at the top of the card details panel.

***

#### How to change the image

To swap in a different image, open the card details panel (click **Show card details** on the toolbar) and click **Change image**. This reopens the **Add image** chooser, where you pick a new image the same way you did the first.

<figure><img src="/files/0ZGkjkMBTST1wEu9NScV" alt="The image card details panel showing a Full screen button and a Change image button at the top, followed by collapsed Personas, Card tags, and Comments sections."><figcaption><p>Change image reopens the source chooser</p></figcaption></figure>

***

#### What image cards share with other cards

The display options and **Change image** are what's specific to an image card. Everything else on it is shared with every other card type:

* Accent colour, background style, and card header (the fill control and the buttons after it on the toolbar)
* Card details panel for personas, tags, and comments
* Duplicate, expand, shrink, and delete from the three-dot menu
* Multi-select with Shift+click

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

***

#### 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 use text cards</strong></td><td>Add narrative notes alongside your visuals and format the text.</td><td><a href="/pages/icqgg4Jls9Iv7VWRvRls">/pages/icqgg4Jls9Iv7VWRvRls</a></td></tr><tr><td><strong>How to use embed cards</strong></td><td>Embed live external content like Figma frames or YouTube videos instead of a static image.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td></tr><tr><td><strong>How to add and manage lanes</strong></td><td>Add an Image lane that defaults to image cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colours in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to use slider cards

Score a step on a journey map with one or more sliders, each between two labels you set, for sentiment, satisfaction, or any rating.

A slider card holds one or more sliders, each a handle on a track between two end labels you set, so you can show where a step lands between, say, Unhappy and Happy, or Low effort and High effort. Add more than one to keep related ratings for the same step on a single card.

<figure><img src="/files/sFI2wcamvgO1b4FYrMbm" alt="One slider card holding two sliders. The first, titled Sentiment, has its handle a little past the middle between Unhappy and Happy. The second, titled Perceived effort, has its handle left of centre between Effortless and Hard work."><figcaption><p>A slider card holding two sliders</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**, then choose **Slider**. **Slider** sits under **BASIC CARDS** in the picker. A new slider card starts with a single slider, no title, empty labels, and its handle at the middle of the track. Cards created before this change keep their original handle position, which is why an older slider card in the same lane can still show its handle at the far left.

<figure><img src="/files/Tf2CjhYHxJsX6CB5Wovw" alt="Three slider cards in a Sliders lane. The left card holds two sliders, Sentiment and Perceived effort. The middle card is an older empty slider with its handle resting at the far left of the track. The right card is a newly added slider with its handle at the middle of the track and no title or labels set yet."><figcaption><p>A newly added slider starts at the middle of the track</p></figcaption></figure>

***

#### How to add and edit sliders

A card's sliders are configured from the toolbar, not the card details panel. Each slider has its own title and its own pair of end labels.

{% stepper %}
{% step %}
**Open Edit sliders**

Select the card and click **Sliders** on the floating toolbar.

<figure><img src="/files/2Bcj7ESiJlnm5QcQ8Vjj" alt="A selected slider card holding one slider titled Sentiment, with its floating toolbar showing Display and Sliders buttons, followed by card header, fill, show card details, delete, and overflow."><figcaption><p>Display and Sliders on the slider card toolbar</p></figcaption></figure>
{% endstep %}

{% step %}
**Fill in each slider's title and labels**

The **Edit sliders** popover lists the card's sliders. Type into **Slider title** to name what it measures, and into **Start label** and **End label** to set the text at the left and right ends of that slider's track.

<figure><img src="/files/shoMHFnsN92HZ1Du2OhX" alt="The Edit sliders popover with one slider: a Slider title field reading Sentiment, and Start label and End label fields reading Unhappy and Happy, with an Add slider link below."><figcaption><p>Edit sliders, with one slider configured</p></figcaption></figure>
{% endstep %}

{% step %}
**Add more sliders, reorder, or delete**

Click **+ Add slider** to add another. Use the drag handle at the left of a slider's row to reorder it, which also reorders the sliders on the card face. Each slider gets its own delete control once the card holds two or more, so you can always remove one without leaving the card empty. A card needs at least one slider.

<figure><img src="/files/EeDIxBWO28oPWe5u7fxZ" alt="The Edit sliders popover with two sliders, Sentiment and Perceived effort, each with a drag handle and a delete icon, and an Add slider link below."><figcaption><p>A delete icon appears per slider once there's more than one</p></figcaption></figure>
{% endstep %}
{% endstepper %}

There's no numeric scale or point count to configure for a slider: each one is a single handle between the two labels you set.

***

#### How to choose a display style

Click **Display** on the floating toolbar to switch how every slider on the card renders. The style applies to the whole card, not per slider:

* **Standard** - a filled track with a round handle
* **Dot** - an empty track with a square marker
* **Progress** - a filled bar with no handle

<figure><img src="/files/H7cIY3KPMHXOwBXjWIMU" alt="The Display menu open with three options: Standard, Dot, and Progress. Standard is selected."><figcaption><p>Display: Standard, Dot, or Progress</p></figcaption></figure>

<figure><img src="/files/tQvfpZf3hCJz63g7kSfg" alt="The same two-slider card rendered in Dot style: each slider shows an empty track with a small square marker at the value, no fill."><figcaption><p>The same card in Dot style</p></figcaption></figure>

<figure><img src="/files/pedBlKnXXMP99vKNXE9C" alt="The same two-slider card rendered in Progress style: each slider shows a filled bar with no handle, ending where the value sits."><figcaption><p>The same card in Progress style</p></figcaption></figure>

***

#### How to set a slider's value

Drag a slider's handle along its track to the point that represents the step. The handle only responds to dragging while its card is selected, so click the card first if a drag doesn't seem to do anything. Each slider's position saves as you go and moves independently of the others on the same card.

***

#### What slider cards share with other cards

The sliders, their titles, labels, and display style are what's specific to a slider card. Everything else on it is shared with every other card type:

* Accent colour, background style, and card header (the fill control and the buttons after it on the toolbar)
* Duplicate, expand, shrink, and delete from the three-dot menu
* Multi-select with Shift+click
* Card details panel for personas, tags, and comments

<figure><img src="/files/fBobmuNkru2Q1hAFQM13" alt="The slider card details panel showing only the universal Personas, Card tags, and Comments (0) sections."><figcaption><p>The details panel holds the universal sections only</p></figcaption></figure>

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

***

#### 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 use text cards</strong></td><td>Add narrative notes alongside a rating and format the text.</td><td><a href="/pages/icqgg4Jls9Iv7VWRvRls">/pages/icqgg4Jls9Iv7VWRvRls</a></td></tr><tr><td><strong>How to use stage cards</strong></td><td>Mark the phases of a journey that your sliders score against.</td><td><a href="/pages/YeVZqUkvqujOSrFxYHsT">/pages/YeVZqUkvqujOSrFxYHsT</a></td></tr><tr><td><strong>How to add and manage lanes</strong></td><td>Add a lane to hold your slider cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colours in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to use icon cards

Show channels, a checklist, or a set of statuses on a card by picking an icon template and customising its icons, sizing, and layout.

Icon cards show a set of labelled icons on a card, like the channels a step happens on, a checklist, or a row of statuses. Icons laid out in a row reflow to fit the card's width, so the layout holds up whether the card is wide or narrow.

<figure><img src="/files/mkivEnaL9Sg6F2Gpu0Aa" alt="An icon card in a Channels lane on a journey map. The card stacks six labelled icons: a red Email envelope, an SMS bubble, an orange Notification bell, a blue Facebook badge, a green Phone handset, and an In person figure."><figcaption><p>An icon card built from the Channels template</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**. **Icons** is the default in a lane set up for icons (press Enter to confirm) and sits under **BASIC CARDS** in the picker in any other lane. A new card reads **Add icons card** with a **Choose a template** button. For the shared add-card mechanics, see [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

<figure><img src="/files/4znQqMs1zELJdGuG84Fo" alt="A populated icon card next to a new, empty icon card. The new card reads Add icons card with a Choose a template button."><figcaption><p>A new icon card before a template is chosen</p></figcaption></figure>

***

#### How to choose an icon template

Click **Choose a template** to open the **Choose a template** dialog. Pick a template to fill the card with a starting set of icons you can then adjust.

<figure><img src="/files/5R8Gqh9njovLmXn0vQvw" alt="The Choose a template dialog listing seven templates as cards with an icon and a name, most with a one-line description: Channels (Communication channels), Checklist (Steps or tasks), Social (Social media platforms), Quote (Highlight quotes or insights), Emojis (Expressive emoji set), Single (Start from scratch), and Social Media."><figcaption><p>The Choose a template dialog</p></figcaption></figure>

The default set is **Channels**, **Checklist**, **Social**, **Quote**, **Emojis**, and **Single**, and your account may have more, like the **Social Media** template shown in the dialog above. The template sets the card's starting icons, colours, and layout. Everything it gives you can be changed on the card afterwards, so pick the template closest to what you need and adjust from there.

{% hint style="info" icon="compass" %}
To build or change the templates this dialog offers, see [How to use icon templates](/account-and-team/customization/how-to-use-icon-templates).
{% endhint %}

***

#### How to add and edit icons

Select the card and click **Icons** on the floating toolbar to open **Edit icons**, which lists every icon on the card.

<figure><img src="/files/B4tD9GrLYlp6BTOleSed" alt="The Edit icons popover listing six icon rows (Email, SMS, Notification, Facebook, Phone, In person), each with a drag handle, an icon swatch, a label field, a link icon, and a delete icon, with an Add icon link below."><figcaption><p>Edit icons</p></figcaption></figure>

Each row has a drag handle to reorder it, the icon, a label field, a link icon to point the icon at a URL, and a delete icon to remove the row. Edit the label inline and changes save as you go. Click **+ Add icon** to add a row.

Click a row's icon to open **Customize icon**, where you can pick a new colour, a brand colour, or search the icon library to swap the glyph.

<figure><img src="/files/Z8yo2xzrjVoNZvl0phBE" alt="The Customize icon popover with an accent colour grid, a Brand colors section, and a Search icons field showing a grid of icon results."><figcaption><p>Customize icon</p></figcaption></figure>

***

#### How to set the display

Click **Display** on the floating toolbar to control how every icon on the card renders.

<figure><img src="/files/gc9B87REzkoYW97WPvbg" alt="The Display popover with six settings: Direction (down arrow selected, right arrow option), Size (S, M selected, L), Spacing (Compact selected, Equal), Label align (Middle selected, Top), Show labels (checked), and Interactive (checked)."><figcaption><p>Display</p></figcaption></figure>

* **Direction** - lay the icons out in a column (down) or a row (right). Only a row wraps to fit the card's width. See [How the layout responds to card width](#how-the-layout-responds-to-card-width).
* **Size** - S, M, or L. Changes the icon's size, not how many fit per row.
* **Spacing** - **Compact** packs icons close together; **Equal** spreads them evenly across the full width of the card.
* **Label align** - in the down direction, **Middle** centres each label against its icon and **Top** aligns it with the icon's top edge.
* **Show labels** - turn labels off to show icons alone, which also lets more fit in a row.
* **Interactive** - when on, anyone with edit access can click an icon on the map to toggle it on or off, and the on/off state is shared with everyone viewing the map. Turn it off to keep the icons fixed.

***

#### How the layout responds to card width

In the row direction, icons wrap onto additional rows as the card gets narrower, and unwrap back onto one row as it gets wider. The card's height adjusts to fit however many rows the icons need.

<figure><img src="/files/UasedOsozkQ7Bj949Bk8" alt="A row-direction icon card spanning two columns, wide enough that all six icons sit in a single row."><figcaption><p>Wide enough for one row</p></figcaption></figure>

<figure><img src="/files/2sX3Ts94xRFAphoasIr0" alt="The same card narrowed to one column. The six icons have wrapped into two rows of three."><figcaption><p>Narrower: the same icons wrap onto a second row</p></figcaption></figure>

Turning off **Show labels** shortens each icon's footprint, so a narrow card can fit more icons per row before wrapping.

<figure><img src="/files/CRKIuJhBfUAxpKBfCW2z" alt="The same narrow card with Show labels off. All six icons now fit in a single row of icons alone, with no labels underneath."><figcaption><p>Labels off: the same narrow card fits every icon on one row</p></figcaption></figure>

The column direction doesn't wrap. Its icons stay in a single left-aligned column regardless of card width, so resizing the card only changes how much empty space sits beside them.

***

#### What icon cards share with other cards

The toolbar's shared tail is the same as any other card: **Card header**, the **fill** control for colour and background, **Show card details**, delete, and the three-dot overflow menu. **Display** and **Icons** are specific to icon cards and sit ahead of this shared tail.

<figure><img src="/files/QQJa4ex16KqAaovhkmZe" alt="The floating toolbar above a selected icon card, showing Display and Icons buttons followed by card header, fill, show card details, delete, and a three-dot overflow menu."><figcaption><p>The toolbar on a selected icon card</p></figcaption></figure>

The card details panel holds only the universal **Personas**, **Card tags**, and **Comments** sections; icon configuration lives in the toolbar, not here.

<figure><img src="/files/dhKsTUR43WMpcolgoiWY" alt="The icon card details panel showing only the universal Personas, Card tags, and Comments (0) sections."><figcaption><p>The details panel holds the universal sections only</p></figcaption></figure>

For the toolbar tail, the colour and background picker, the card header, spanning, and multi-select, see [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

***

#### 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 icon templates</strong></td><td>Build and edit the icon templates that the Choose a template dialog offers, at the account level.</td><td><a href="/pages/slsfRG28ukTuwANdbWJw">/pages/slsfRG28ukTuwANdbWJw</a></td></tr><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 add and manage lanes</strong></td><td>Add a lane to hold your icon cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colours in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</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>


# How to use embed cards

Embed live content from Figma, Google Docs, Sheets, Slides, Miro, YouTube, and other sources onto a journey map by pasting a share link.

Embed cards put live content from the tools your team already uses, like a Figma frame, a Google Doc, a Miro board, or a YouTube video, directly on a journey map. You paste a share link and the content renders in the card.

<figure><img src="/files/rJ4pb8OeSpJUjVXAv8ou" alt="An embed card on a journey map showing a rich link preview of a website: a page thumbnail, the site favicon and URL, the page title, and a short description. The card sits in a lane labelled Embed content."><figcaption><p>An embed card showing a rich preview of the embedded link</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**, then choose **Embed**. It sits under **ADVANCED CARDS** in the picker. Embed cards take a share link rather than typed content, so adding one opens the **Embed** modal straight away.

{% hint style="info" icon="tag" %}
Embed cards are an advanced card type. On the **Free** and **Repository** plans you can add up to 3 advanced cards per map. Advanced cards are unlimited from the **Framework** plan.
{% endhint %}

***

#### How to embed content from a URL

When you add an embed card, the **Embed** modal opens with logos for some of the supported sources and the prompt **Paste a URL to embed**.

{% stepper %}
{% step %}
**Copy a share link from the source**

Open the source tool (Figma, a Google file, Miro, YouTube, and so on) and copy its share or embed link. The link has to be one that anyone with access to the map can open, not a private editing URL tied to your own login. For per-source guidance, see [How to use embed integrations](/integrations/how-to-use-embed-integrations).
{% endstep %}

{% step %}
**Paste the URL into the Embed modal**

Paste the link into the URL field. The **Embed** button stays greyed out until the field has a URL in it, then turns active.

<figure><img src="/files/wCItJhF89BZRc9iWVBbn" alt="The Embed modal with a URL typed into the input field. Logos for Miro, Figma, YouTube, a generic web globe, and Google Sheets sit above the prompt Paste a URL to embed. The Embed button to the right of the field is now active."><figcaption><p>The Embed button activates once the field has a URL</p></figcaption></figure>
{% endstep %}

{% step %}
**Click Embed**

The modal closes and the content renders on the card. By default it shows as a rich preview.
{% endstep %}
{% endstepper %}

***

#### Which sources you can embed

Smaply embeds content from Figma, Google Docs, Google Sheets, Google Slides, Miro, Mural, YouTube, Power BI, Tableau, Monday.com, SharePoint, and OneDrive. Generic web URLs work too, rendering as a rich link preview when the page exposes the right metadata.

This article is the home for embedding content onto cards. The link type each source needs and how to set a source's own sharing so the embed renders for everyone are covered in [How to use embed integrations](/integrations/how-to-use-embed-integrations).

***

#### How to switch between rich preview and a simple link

An embed card shows in one of two display modes, set by the **Display as** toggle in the card details panel. The toggle sits inside the **Card details** section, which opens collapsed, so expand it to reach the toggle.

{% stepper %}
{% step %}
**Open the card details panel**

Select the card and click **Show card details** on the toolbar, or double-click the card. The panel opens on the right.
{% endstep %}

{% step %}
**Expand Card details and pick a mode**

Expand the **Card details** section, then choose **Embed (rich media)** or **Simple link** under **Display as**.

<figure><img src="/files/8HyVCduGfcqQxcBzKvES" alt="The embed card details panel headed Embed. An expanded Card details section shows a Display as toggle with two options, Embed (rich media) selected and Simple link, above an Open link button. Below sit the collapsed Personas, Card tags, and Comments sections."><figcaption><p>Display as toggle inside the expanded Card details section</p></figcaption></figure>
{% endstep %}
{% endstepper %}

**Embed (rich media)** is the default and renders the full preview: a thumbnail, title, and description for a link, or the live content for a supported source. **Simple link** collapses the card to a compact favicon, the page title, and an **Open link** link.

<figure><img src="/files/FcQwEcMFfTtJacgNO8Ny" alt="An embed card switched to Simple link display, showing a compact favicon, the page title, and an Open link link. The card sits in a lane labelled Embed content."><figcaption><p>The same card in Simple link mode</p></figcaption></figure>

***

#### How to open the embedded content

To open the source in a new tab, click **Open link** on the card's toolbar. The same button is also in the card details panel.

<figure><img src="/files/xQZGAThjKleXPsEWJPt8" alt="The floating toolbar for a selected embed card. From left: an Open link button labelled with text and an open-in-new icon, then a card header icon, a fill (paint bucket) icon, a show card details icon, a delete icon, and a three-dot overflow menu."><figcaption><p>Open link is the leftmost button on the embed card toolbar</p></figcaption></figure>

If the card is blank, or shows a permission prompt or a login screen, the cause is almost always the source's own sharing setting rather than Smaply. See [How to use embed integrations](/integrations/how-to-use-embed-integrations) for how to set each source's sharing so the embed renders for everyone who opens the map.

***

#### What embed cards share with other cards

Embed cards use the same toolbar tail, card details panel, colour system, and multi-select as every other card type. The Display as toggle and the embedded content are what's specific to this type; the rest is shared:

* Accent colour, background style, and card header (the fill control and the controls after it)
* Card details panel for personas, tags, and comments
* Duplicate, expand, shrink, and delete from the three-dot menu
* Multi-select with Shift+click

See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the canonical walkthrough of these mechanics. To put an embed card in its own lane, see [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes).

***

#### 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 embed integrations</strong></td><td>Get a shareable link from each source and set its sharing so the embed renders for everyone.</td><td><a href="/pages/xEXHdynnj0g2GXg8mY4m">/pages/xEXHdynnj0g2GXg8mY4m</a></td></tr><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 add and manage lanes</strong></td><td>Add a lane to hold your embed cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colour in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</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>


# How to use metric cards

Show a live metric, like monthly signups or conversion rate, on a journey map, and set how it displays on each card.

A metric card surfaces a metric on a journey map: a number or a chart that updates from its data source, like monthly user account creation or a conversion rate next to the step it relates to. The metric is the data; the card is how that data appears, and the same metric can sit on as many maps as you like.

<figure><img src="/files/0pngpm5tCiPhzkQeZn7h" alt="A journey map lane labelled Metrics holding a metric card titled User account creation, with the subheading Monthly user account creation, a JUN-2026 period label, a large value of 731.55, and a bar chart of monthly values below it."><figcaption><p>A metric card showing a value and chart on the map</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**, then choose **Metric**. It sits under **ADVANCED CARDS** in the picker. A metric card shows existing metric data rather than typed content, so adding one opens the **Add metric** picker straight away.

{% hint style="info" icon="tag" %}
Metric cards are an advanced card type. On the **Free** and **Repository** plans you can add up to 3 advanced cards per map. Advanced cards are unlimited from the **Framework** plan.
{% endhint %}

***

#### How to add a metric to the card

When you add a metric card, the **Add metric** picker opens. From here you either reuse a metric that already exists or create a new one.

<figure><img src="/files/dMzB1vN9mnK1y2ffeaOk" alt="The Add metric picker. A Search or create metric field with a greyed-out Create button sits at the top, with All, Current map, and Created by you filters and a Filters control. A Most relevant list of existing metrics follows, each with its source (Manual), a type label (Comparison, Number, or Series), and a created date; two metrics, Comparison metric and Number metric, are selected. The right pane reads 2 metrics will be added, select more items or click Add to insert them into the map, above a blue Add 2 button."><figcaption><p>Add metric picker: select one or several metrics, then click Add</p></figcaption></figure>

* **Reuse an existing metric** - The picker lists the metrics in your workspace, each with its source and type. Type in **Search or create metric** to narrow the list, or use the **All**, **Current map**, and **Created by you** filters. Click a metric to select it, or pick several to add them in one go, then click **Add**. When you select more than one, the button shows the count, like **Add 2**. Because one metric can appear on many maps, reusing it keeps every card in sync with the same data.
* **Create a new one** - Type a name in **Search or create metric** and click **Create**. This opens the metric builder, where you pick the data source and metric type and map its fields.

Creating a metric, choosing its source (Manual, a CSV upload, or an integration like Google Analytics or Qualtrics), its type (Number, Series, or Comparison), and its fields, is its own task. See [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric) for the full walkthrough.

***

#### How to change how the metric displays on this card

Each card holds its own display of the metric, so the same metric can show as a number on one map and a chart on another. Open that display from the card to change the chart type, headings, and other display options.

{% stepper %}
{% step %}
**Select the card and click Edit metric**

Click the card once to select it, then click **Edit metric** on the floating toolbar. **Edit metric** is the leftmost button; the rest of the toolbar is shared with every card type.

<figure><img src="/files/JORkzByUzfdub4KCOcYB" alt="The floating toolbar for a selected metric card titled User account creation. From left: an Edit metric button with a pencil icon and label, then a card header icon, a fill (paint bucket) icon, a show card details icon, a delete icon, and a three-dot overflow menu."><figcaption><p>Edit metric is the leftmost button on the metric card toolbar</p></figcaption></figure>
{% endstep %}

{% step %}
**Adjust the display and save**

The metric builder opens with the data on the left and a live preview of the card on the right. Set the chart type and any headings here, then save. For what each option does and how the data source feeds the card, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).
{% endstep %}
{% endstepper %}

{% hint style="info" %}
A metric card saves through the metric builder, not as you type on the card. Editing a metric updates every card that displays it, across all your maps.
{% endhint %}

***

#### What the card details panel shows

Open the card details panel to see where the metric comes from and when it last updated. Select the card and click **Show card details** on the toolbar, or double-click the card.

<figure><img src="/files/s8MtSXcssjddslPbDVeM" alt="The metric card details panel headed Metric. A boxed section titled Series metric lists Source set to Manual, Last updated set to 3 days ago, and Metric type set to Series, above an Edit metric button. Below sit the collapsed Personas, Card tags, and Comments sections."><figcaption><p>The metric card details panel, with Source, Last updated, and Metric type</p></figcaption></figure>

The panel headed **Metric** names the metric and shows three read-only fields: **Source** (where the data comes from, such as Manual or an integration), **Last updated** (when the data last refreshed), and **Metric type** (Number, Series, or Comparison). An **Edit metric** button opens the same builder as the toolbar. Below those sit the universal **Personas**, **Card tags**, and **Comments** sections shared by every card type.

***

#### When the metric refreshes

A metric connected to an integration refreshes on load when its last update is more than roughly an hour old, so opening a map after a while pulls current data. There's no separate refresh button to press. The **Last updated** time in the card details panel tells you how fresh the data is.

***

#### What metric cards share with other cards

The metric, the **Edit metric** button, and the **Source** / **Last updated** / **Metric type** fields are what's specific to a metric card. Everything else on it is shared with every other card type:

* Accent colour, background style, and card header (the fill control and the buttons after it on the toolbar)
* Card details panel for personas, tags, and comments
* Duplicate, expand, shrink, and delete from the three-dot menu
* Multi-select with Shift+click

See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the canonical walkthrough of these mechanics. To put a metric card in its own lane, see [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes).

***

#### 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 create and configure a metric</strong></td><td>Build a metric: pick a source and type, map its fields, and set how it charts.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><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 choose a metric type</strong></td><td>Pick between Number, Series, and Comparison for what you want to show.</td><td><a href="/pages/exJ4wHPtNqRHjfhSG9Y1">/pages/exJ4wHPtNqRHjfhSG9Y1</a></td></tr><tr><td><strong>How to add and manage lanes</strong></td><td>Add a lane to hold your metric cards, or any other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colour in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to use planning cards

Pull a live work item from a connected planning tool onto a journey map, so the step shows its real status and updates as the work moves.

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) (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) 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).
{% 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>


# How to use portfolio item cards

Show an opportunity, pain point, solution, or other portfolio item on a journey map, with its scores, priority, status, and assignee in view.

A portfolio item card puts one of your portfolio items, such as an opportunity, pain point, or solution, onto a journey map. The item itself is the data and lives in your workspace; the card is a view of it on the map, so editing the item updates every card that displays it.

<figure><img src="/files/UZfAbeVZanIRIgphabxd" alt="A portfolio item card in an Opportunities lane on a journey map. The card has a blue starburst icon, a title reading Intelligent transaction dashboard with exportable statements, a truncated description, three score meters labelled Impact, Feasibility, and Potential, a Design status with a priority marker, an assignee avatar, and a footer reading Used in 1 other map."><figcaption><p>A portfolio item card shows the item's scores, status, priority, and assignee</p></figcaption></figure>

To add one, hover an empty cell and click **+ Add card**, then pick the type you want from the **CUSTOM CARDS** group at the bottom of the picker. This account's types are **Opportunity**, **Pain point**, **Solution**, **Goals**, and **Risk**; your own list depends on the portfolio item types set up in your workspace. Adding the card places a view of an existing item on the map.

<figure><img src="/files/zWgbyXrKa8s28ptvWeSz" alt="The Add card picker open with a Type to search box at the top. An ADVANCED CARDS group lists Embed, Planning, and Link journey map. Below it, a CUSTOM CARDS group lists Opportunity with a blue starburst icon, Pain point with a red icon, Solution with a green tick icon, Goals with a yellow trophy icon, and Risk with a purple question-mark icon."><figcaption><p>Portfolio item types sit in the CUSTOM CARDS group of the picker</p></figcaption></figure>

{% hint style="info" icon="tag" %}
Portfolio item cards are limited to 3 per map on the **Free** plan. They are unlimited from the **Repository** plan and above.
{% endhint %}

***

#### What a portfolio item card shows

The card face surfaces the item's headline data so you can read it without opening anything: the item's title and type icon, a truncated description, the type's score dimensions as small meters, the priority and status, and the assignee. A footer line reads **Used in N other map** when the same item appears on other journey maps.

The score dimensions belong to the portfolio item type, so they differ from one type to the next. The opportunity above is scored on **Impact**, **Feasibility**, and **Potential**; a pain point in the same workspace might be scored on **Impact**, **Reach**, and **Cost** instead. The meters on the card are read-only; scores are set on the item, not on the card.

***

#### The portfolio item card toolbar

Select the card to open its floating toolbar. A portfolio item card has no text-formatting controls, since its content comes from the item rather than from typing on the card.

<figure><img src="/files/Vc36oWFC8zeWjYLp9YFa" alt="A selected portfolio item card with a blue selection border and its floating toolbar above. The toolbar shows, from left, a Display button with a panel icon, an Edit opportunity button with a pencil icon, then a card header icon, a fill paint-bucket icon, a show card details icon, a delete icon, and a three-dot overflow menu."><figcaption><p>The toolbar adds Display and Edit [type] ahead of the shared controls</p></figcaption></figure>

Two controls are specific to this card type, on the left of the toolbar:

* **Display** - sets how much of the item the card shows on the map. See [How to change what the card displays](#how-to-change-what-the-card-displays) below.
* **Edit \[type]** - opens the underlying item for editing. The button is named for the item's type, so it reads **Edit opportunity** for an opportunity, **Edit pain point** for a pain point, and so on. Changes you make there update every card that displays the item.

Everything to the right of these (card header, fill colour, show card details, delete, and the three-dot menu) is shared with every card type and is covered in [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

***

#### The portfolio item details sidebar

Open the card's details sidebar from **Show card details** on the toolbar, the three-dot menu, or by double-clicking the card. The panel header names the item's type, and the top of the panel holds the item's data.

<figure><img src="/files/RTeTldHxJ9mVnAKN6cba" alt="The card details sidebar for a portfolio item, headed Opportunity. From the top: the item title with its blue icon and full description, then Impact 69, Feasibility 59, and Potential 100 as labelled score meters, then Priority High, Status Design, an assignee row, Opportunity tags reading 0 tags, Used in 1 other journey map, and a Linked items row reading No linked portfolio items with a plus Add linked items link. An Edit opportunity button sits below, followed by collapsed Personas, Tags, and Comments sections."><figcaption><p>The details sidebar carries the item's full data above the shared sections</p></figcaption></figure>

The type-specific rows, top to bottom:

* **Scores** - the type's score dimensions with their numeric values and meters (here **Impact**, **Feasibility**, and **Potential**).
* **Priority** - the item's priority, with its marker.
* **Status** - the item's workflow status, with its status ring.
* **Assignee** - the person the item is assigned to.
* **\[type] tags** - tags set on the item itself, separate from the card tags below. These read **Opportunity tags** for an opportunity, and so on.
* **Used in** - how many other journey maps display this same item.
* **Linked items** - portfolio items linked to this one. Use **+ Add linked items** to connect another item, for example a solution that addresses this opportunity.
* **Edit \[type]** - the same edit action as on the toolbar, opening the item for changes.

Below these, the panel carries the **Personas**, **Tags**, and **Comments** sections that appear on every card. Those, and the shared toolbar controls, live in [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

{% hint style="info" %}
The fields here are a read-only view of the item. To change a score, priority, status, assignee, or the item's own tags, open the item with **Edit \[type]**. Editing it updates every card that displays it, on this map and any other.
{% endhint %}

***

#### How to change what the card displays

The **Display** control sets how much of the item the card shows, so you can keep a map readable when several portfolio items sit on it.

{% stepper %}
{% step %}
**Select the card and open Display**

Click the card to open its toolbar, then click **Display**.
{% endstep %}

{% step %}
**Pick a display mode**

Choose one of the modes from the menu. The card redraws on the map immediately.

<figure><img src="/files/WKrrtvfVWzzxuoeX296F" alt="The Display menu open from a selected portfolio item card&#x27;s toolbar. It lists Standard, Linked items, Evidence, Compact, and Custom, with Custom showing a submenu arrow on the right."><figcaption><p>The Display menu sets how much of the item the card shows</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The modes are **Standard**, **Linked items**, **Evidence**, **Compact**, and **Custom**. **Standard** is the full face shown above, including the **Used in** indicator. **Compact** shrinks the card to its title and key markers. **Custom** opens a submenu for choosing which parts of the item to show.

***

#### Where portfolio items come from

Portfolio item cards display items you have already created; they don't create the items. The item, its type, and its scores all live in the workspace's Portfolio. For those tasks, start here:

* [How to create a portfolio item](/portfolio/how-to-create-a-portfolio-item) - add a new opportunity, pain point, solution, or other item.
* [How to create custom portfolio item types](/portfolio/how-to-create-custom-portfolio-item-types) - define the types, their score dimensions, and their fields.

***

#### 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 create a portfolio item</strong></td><td>Create the opportunity, pain point, or solution that a card displays.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>How to create custom portfolio item types</strong></td><td>Define portfolio item types and the score dimensions cards display.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</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="/pages/iDGXQS6w1CP6Vkc7j5BA">/pages/iDGXQS6w1CP6Vkc7j5BA</a></td></tr><tr><td><strong>How to use the portfolio summary</strong></td><td>See all of a workspace's portfolio items and their scores in one place.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr></tbody></table>


# How to use linked journey map cards

Link another journey map onto a card so you can see its summary and jump to it without leaving the map you're on.

A linked journey map card points to another journey map and shows a snapshot of it right on the card: a thumbnail, the map name, its description, and its performance indicator. It's how you connect a high-level map to a detailed sub-journey, or reuse one sub-flow across several parent maps, and move between them in a click.

<figure><img src="/files/W0Fp7ePgCSpsg08amc6E" alt="A journey map lane labelled Linked journeys holding a linked journey map card. The card shows a small map thumbnail, the map name L1 Product: Online Account with a hierarchy icon, a truncated description, a PERFORMANCE INDICATOR heading with a green Healthy chip, and a portfolio summary reading PAIN POINT 1 of 6, OPPORTUNITY 0 of 2, SOLUTION 0 of 1 with segmented bars."><figcaption><p>A linked journey map card on a journey map lane</p></figcaption></figure>

{% hint style="info" icon="tag" %}
Linked journey map cards are available on the **Repository** plan and above. They aren't available on **Free**.
{% endhint %}

To add one, hover an empty cell and click **+ Add card**, then choose **Link journey map**. It sits under **ADVANCED CARDS** in the picker. The **Link journey map** window opens straight away so you can pick the map to link as you add the card.

These cards work the same on a standard journey map and on a hierarchy map, where they are the building blocks that link maps together.

***

#### How to pick the journey map to link

{% stepper %}
{% step %}
**Find the map in the Link journey map window**

Type in the **Search or create journey map** field to filter, or scan the **Most relevant** list. Each result shows the map name, its description, a relevance label like **Most relevant** or **Close match**, when it was last updated, and its coordinator.

<figure><img src="/files/2NnVyZWtzC4noSg0RADx" alt="The Link journey map window open over a journey map. A Search or create journey map field sits at the top with a disabled Create button beside it. Below, a Most relevant list of journey maps, each with a name, description, a match label such as Most relevant or Close match, an Updated date, and a Coordinator line. The right pane reads Select a journey map on the left to preview how the linked card will appear."><figcaption><p>Link journey map, with the ranked Most relevant list</p></figcaption></figure>
{% endstep %}

{% step %}
**Select a map to preview how the card will look**

Click a map in the list. The right pane previews how the linked card will appear before you commit, so you can confirm you've picked the right map.
{% endstep %}

{% step %}
**Add the card, or create a new map to link**

Selecting a map adds the linked journey map card to the slot. To link a brand-new map instead, type a name in the field and click **Create**, which makes the map and links it in one step.
{% endstep %}
{% endstepper %}

***

#### What the linked journey map card shows

The card face is a live snapshot of the map it links to, so it stays current as that map changes. It always shows the map thumbnail, the map name, the description, and the **PERFORMANCE INDICATOR** (a status chip such as **Healthy**).

A few fields appear only when they're set on the linked map:

* **Coordinator** - the person responsible for the linked map, shown when one is assigned.
* **Portfolio summary** - per-type counts of the pain points, opportunities, and solutions on the linked map, each as a "1 of 6" figure with a segmented bar.
* **Tags** - the linked map's tags, shown as chips.

If the linked map has no coordinator or tags, those fields are left off the card rather than shown empty.

***

#### How to preview or open the linked map

Select the card to bring up its toolbar, which adds **Display** and **Preview** to the left of the shared controls.

<figure><img src="/files/pZa6lORQU7UkZriIvnNO" alt="A selected linked journey map card with a blue selection border and its floating toolbar above. The toolbar shows Display and Preview on the left, then the shared card header, fill, show card details, delete, and three-dot overflow controls."><figcaption><p>The linked journey map card toolbar adds Display and Preview</p></figcaption></figure>

**Preview** opens the linked map in an overlay on top of the map you are on, so you can read its full stages, steps, lanes, and cards without losing your place. The overlay header carries a search, a zoom control, a **Full screen** toggle, and an **Edit map** button.

<figure><img src="/files/LJzPClhsA6rOm6v2ByeO" alt="A linked journey map open in a preview overlay on top of the current map. The overlay shows the full L1 Product: Online Account map with its stages, steps, and pain point cards. The overlay header reads L1 Product: Online Account on the left, with a search icon, zoom control, Full screen toggle, Edit map button, and close X on the right."><figcaption><p>Preview opens the linked map in an overlay, in context</p></figcaption></figure>

Switch on **Full screen** for a larger read-only view of the same map.

<figure><img src="/files/h5sVe1qXJ3u4k0aChNlN" alt="The linked journey map L1 Product: Online Account expanded to a full-screen read-only view that fills the window. The header keeps the Edit map button and a close X."><figcaption><p>Full screen gives the linked map room to read</p></figcaption></figure>

To open the linked map for editing, click **Edit map**, which opens it in a new browser tab so the map you started from stays open behind it. The card details panel carries the same actions: click **Show card details** to open the panel (header **Linked journey**), which repeats the map name, full description, and performance indicator above **Preview** and **Go to journey** buttons.

<figure><img src="/files/Woqj04Np0uBXhwfnJRuk" alt="The card details panel for a linked journey map card. The header reads Linked journey, followed by the map name L1 Product: Online Account, its full description, a Performance Indicator labelled Healthy with a green dot, and Preview and Go to journey buttons. Below sit the universal Personas, Card tags, and Comments (0) sections."><figcaption><p>The Linked journey details panel, with Preview and Go to journey</p></figcaption></figure>

***

#### What linked journey map cards share with other cards

Linked journey map 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 beneath the linked-map fields.

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

***

#### 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 create a hierarchy map</strong></td><td>Gather journey maps into a dedicated space and link them with these cards as the nodes.</td><td><a href="/pages/R4eKe96wbOcrolkAQeNP">/pages/R4eKe96wbOcrolkAQeNP</a></td></tr><tr><td><strong>How to choose between a journey map and a hierarchy map</strong></td><td>Decide when to capture something as a single journey map and when a hierarchy fits better.</td><td><a href="/pages/ANYZEQ2NKtnOB6djd635">/pages/ANYZEQ2NKtnOB6djd635</a></td></tr><tr><td><strong>How to use portfolio item cards</strong></td><td>Add the pain points, opportunities, and solutions that feed a linked map's portfolio summary.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or colour in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to comment on a card

Discuss any card in context by posting comments from its details panel and @mentioning the teammates you want to pull in.

Every card carries its own comment conversation, so feedback and questions stay attached to the exact step they're about. Open the card details panel, type in the **Comments** section, and press Enter to post. @Mention a teammate to notify them.

{% hint style="info" icon="tag" %}
Commenting on cards is available on the **Repository** plan and above. On **Free**, collaboration is limited to a single journey map.
{% endhint %}

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

#### In this guide

1. [How to add a comment to a card](#how-to-add-a-comment-to-a-card)
2. [How to @mention a teammate](#how-to-mention-a-teammate)
3. [How to delete a comment](#how-to-delete-a-comment)
4. [What a comment notifies](#what-a-comment-notifies)
   {% endhint %}

***

#### How to add a comment to a card

Comments live in the card details panel, which you open by clicking **Show card details** on the card toolbar, choosing **Card details** from the three-dot menu, or double-clicking the card. The panel works the same on every card type. For the panel itself, see [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).

{% stepper %}
{% step %}
**Open the Comments section**

In the card details panel, expand **Comments**. The heading shows the current count, so an untouched card reads **Comments (0)**.

<figure><img src="/files/ppYIekZY1BlxohDi4VUm" alt="A card details panel with Personas, Card tags, and Comments sections. The Comments section is expanded and reads Comments (0), with an empty Add a comment field below it."><figcaption><p>The Comments section on a card with no comments yet</p></figcaption></figure>
{% endstep %}

{% step %}
**Type your comment**

Click into the **Add a comment** field and write your note. The field grows to fit longer text.

<figure><img src="/files/rVRtOQ1CyMoODhf7ZgqX" alt="The Comments section with a comment being typed into the Add a comment field, reading Should we add a comparison of fee structures here? Customers ask about this a lot during research."><figcaption><p>Writing a comment in the composer</p></figcaption></figure>
{% endstep %}

{% step %}
**Press Enter to post**

There's no separate post button. Pressing Enter submits the comment, the count ticks up, and your comment appears with your name and the time you posted.

<figure><img src="/files/wFajmTyX1eDtUa5y6TXA" alt="A posted comment under a Comments (1) heading, attributed to Smaply Team with a now timestamp and a delete icon, followed by an empty Add a comment field ready for the next comment."><figcaption><p>A posted comment, with the empty composer ready for the next one</p></figcaption></figure>
{% endstep %}
{% endstepper %}

Comments stack in a single list, newest at the bottom, so a back-and-forth on a card reads in order. Anyone with access to the map sees the same conversation.

<figure><img src="/files/qeawnO6OSeiEhz4FA2VE" alt="A Comments (2) section showing two comments in one list, each attributed to Smaply Team with a timestamp and a delete icon. The first asks about adding a comparison of fee structures; the second replies that the author will pull the current fee table and add it as a metric card. An empty Add a comment field sits below."><figcaption><p>A two-comment conversation in the card's comment list</p></figcaption></figure>

***

#### How to @mention a teammate

To pull a specific person into the conversation, type `@` in the composer. A list of the people in your workspace opens, and picking one inserts a mention into your comment.

<figure><img src="/files/XXSgOVJF7kFjKNymOxAT" alt="A comment composer with an @ typed in it. A dropdown below the field lists a workspace member, Smaply Team, with their avatar, ready to be selected as a mention."><figcaption><p>Typing @ opens the list of workspace members to mention</p></figcaption></figure>

Anyone who can comment can be mentioned, including teammates with Viewer access. The mention sends them a notification so they know to look. For what that notification is and where it lands, see [What a comment notifies](#what-a-comment-notifies) below.

***

#### How to delete a comment

Hover or look to the right of any comment for the delete (trash) icon, and click it to remove that comment. Deleting is the only edit available on a posted comment, and the count drops to match.

***

#### What a comment notifies

An @mention is the only comment activity that notifies anyone. The person you mention gets an in-app notification on the notification bell at the top-right of the app. There's no email for mentions, and a plain comment with no mention notifies no one.

For the full picture of what Smaply notifies you about and where, see [About notifications](/account-and-team/about-notifications).

***

#### 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 the card details panel and the shared mechanics every card type uses.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>About notifications</strong></td><td>What an @mention sends, where it shows up, and what you can and can't change.</td><td><a href="/pages/fDF2SBvff6heg6x7MiuR">/pages/fDF2SBvff6heg6x7MiuR</a></td></tr><tr><td><strong>How to assign a persona to a card</strong></td><td>Another card details panel section: tag a card with one or more personas.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Apply tags, personas, or formatting across many cards at once.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# Lanes and columns

Lanes (horizontal rows) and columns (vertical structure) form the grid that cards snap to in a journey map

Lanes are the horizontal rows of a journey map. Columns are the vertical structure. Together they form the grid that cards snap to. Different lane types support different kinds of content: text for narrative, emotion chart for sentiment, grid for multi-row organisation, divider for visual separation.

#### Why use lanes and columns

* Structure a journey into clear rows and steps, so readers can scan across time and down dimensions
* Match each row to its content with dedicated lane types for narrative, sentiment, matrices, and visual separation

#### In this section

* [**Add and manage lanes**](/journey-maps/lanes/how-to-add-and-manage-lanes) - Create, rename, reorder, pin, duplicate, and delete lanes (text is the default lane type).
* [**Add and manage columns**](/journey-maps/lanes/how-to-add-and-manage-columns) - Add, remove, and reorganise the columns of a journey map.
* [**Emotion chart lanes**](/journey-maps/lanes/how-to-use-emotion-chart-lanes) - Visualise the emotional journey with a sentiment scale.
* [**Grid lanes**](/journey-maps/lanes/how-to-use-grid-lanes) - Multi-row lanes for tables, channels, or matrices.
* [**Flow lanes**](/journey-maps/lanes/how-to-use-flow-lanes) - Draw connector arrows between cards to map a process or blueprint.
* [**Freeform lanes**](/journey-maps/lanes/how-to-use-freeform-lanes) - Place cards anywhere on an open canvas, off the column grid.
* [**Divider lanes**](/journey-maps/lanes/how-to-use-divider-lanes) - Visual separators between sections of a journey.


# How to add and manage lanes

Add the horizontal rows that structure a journey map, then rename, recolour, reorder, pin, duplicate, and delete them.

A lane is a horizontal row of a journey map, holding one dimension of the experience across every step. To add one, click **+ Add lane** and pick a type from the picker. To manage an existing lane, open its three-dot menu for pinning, recolouring, reordering, duplicating, and deleting.

***

#### How to add a lane

Each lane has a **+ Add lane** button above it, and there is one below the last lane, so you can insert a row exactly where you want it. Clicking it opens the picker.

<figure><img src="/files/P3h8IrdPZ9VYWfJAccDs" alt="The Add lane picker open below the + Add lane button. A search box reads Type to search with Text as the Enter quick-select. BASIC LANES lists Image, Stage, Icons, Grid, Divider, and Emotion chart. ADVANCED LANES lists Embed, Planning, Metric, Linked maps, Flow, and Freeform. CUSTOM LANES lists Opportunity, Pain point, Solution, Goals, and Risk. A + Quick add content button is pinned at the bottom."><figcaption><p>The Add lane picker, grouped into Basic, Advanced, and Custom lanes</p></figcaption></figure>

Start typing in the search box to filter the list, or pick a type from one of three groups:

* **BASIC LANES** - Image, Stage, Icons, Grid, Divider, and Emotion chart.
* **ADVANCED LANES** - Embed, Planning, Metric, Linked maps, Flow, and Freeform.
* **CUSTOM LANES** - the portfolio item types in your account: Opportunity, Pain point, Solution, Goals, and Risk.

{% hint style="info" icon="tag" %}
The lane types you see depend on your plan, so the picker may not show every option above.
{% endhint %}

**Text** is the default. Press Enter to add a text lane without leaving the keyboard, or click it in the picker. A text lane holds one text card per step, which makes it the row to reach for first when you're laying out narrative content like steps, actions, or thinking.

{% hint style="info" %}
The lane type only sets the *default* card for that row. You can still drop any card type into most lanes. The two exceptions are emotion chart lanes and divider lanes, which hold their own content and don't take arbitrary cards. See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).
{% endhint %}

***

#### Quick add content

The **+ Quick add content** button pinned at the bottom of the Add lane picker builds several lanes at once, instead of adding them one row at a time. It opens the **Quick add journey content** dialog, which has two tabs.

<figure><img src="/files/ZnbNSPMLcBY6nHdLy7Iq" alt="The Quick add journey content dialog on its File import tab. Three source cards sit at the top: Image or screenshot with an AI icon (selected), Excel, and JSON. Below them a dropzone reads Upload or paste an image or screenshot, supporting .svg, .png, .jpg, .jpeg, and .webp, with Cancel and Import buttons."><figcaption><p>Quick add content, File import tab</p></figcaption></figure>

* **File import** - build lanes from a file. Pick **Image or screenshot** to have AI read a picture of a journey or framework and draft lanes from it, **Excel** to map a spreadsheet's rows and columns into lanes, or **JSON** to bring in a map exported from Smaply. This adds lanes to the map you're in. To import a whole map as a new journey instead, use the **Import** button on the journey maps list. See [How to import from image](/migration/how-to-import-from-image), [How to import from Excel](/migration/how-to-import-from-excel), and [How to import from JSON](/migration/how-to-import-from-json).
* **Lane templates** - tick the common lanes you want and add them in one go: Journey stages, Quotes, Emotion chart, Storyboard images, Channels, Sentiment, and Gantt project. Then click **Add journey content**.

<figure><img src="/files/4DR2bYdzHfWT9ZzPKrrb" alt="The Quick add journey content dialog on its Lane templates tab. A checklist offers Journey stages (pre-selected), Quotes, Emotion chart, Storyboard images, Channels, Sentiment, and Gantt project, each with a short description."><figcaption><p>Quick add content, Lane templates tab</p></figcaption></figure>

***

#### How to manage a lane

Every lane has a three-dot menu next to its title. Open it to rename, recolour, reorder, pin, duplicate, or delete the lane.

<figure><img src="/files/5Cj9vjL2u2J6ocas4MLf" alt="A lane three-dot menu open on a text lane labelled Steps. The menu lists Pin lane, Edit lane description, Change color, Select all cards, Paste content, Copy lane, Paste lane below (greyed out), Duplicate lane below, Move lane up, Move lane down, and Delete lane."><figcaption><p>The three-dot menu on a text lane</p></figcaption></figure>

The menu holds these options:

* **Pin lane** - keep the lane in view while you scroll the map vertically. Useful for a Stages or Steps row you want as a constant reference.
* **Edit lane description** - add a short note describing what the lane captures.
* **Change color** - set the lane's accent colour, which its cards pick up by default.
* **Select all cards** - select every card in the lane at once, ready for a bulk action. See [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards).
* **Paste content** - paste copied content into the lane. Pasting a list or spreadsheet here fans it out into one card per row. See [How to use enhanced paste](/journey-maps/how-to-use-enhanced-paste).
* **Copy lane** and **Paste lane below** - copy the whole lane, then paste a copy below another lane. **Paste lane below** stays greyed out until you've copied a lane.
* **Duplicate lane below** - drop a copy of the lane, with its cards, directly beneath it.
* **Move lane up** and **Move lane down** - reorder the lane one row at a time. You can also drag a lane by its title to reposition it.
* **Delete lane** - remove the lane and everything in it.

{% hint style="warning" %}

#### **Important: Deleting a lane removes its cards too**

Deleting a lane takes every card in it with it. To keep the cards, move them to another lane first by dragging them across.
{% endhint %}

Some lane types show a shorter menu. Emotion chart and divider lanes drop the card and clipboard options (they don't hold ordinary cards) and add one type-specific option instead. Those live in the lane-type articles below.

***

#### 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 manage columns</strong></td><td>Add, remove, and reorder the step columns that cross your lanes.</td><td><a href="/pages/WNBA1RdaCt3rMhxOcLHD">/pages/WNBA1RdaCt3rMhxOcLHD</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards to a lane and edit the shared toolbar, details panel, and colours.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use emotion chart lanes</strong></td><td>Plot a sentiment curve across the journey on a fixed five-point scale.</td><td><a href="/pages/MSglvHiirbEdJK3Ivwqu">/pages/MSglvHiirbEdJK3Ivwqu</a></td></tr><tr><td><strong>How to use grid lanes</strong></td><td>Build multi-row lanes for tables, channels, or matrices.</td><td><a href="/pages/lZD6w7ZNrPaXH8F0kQNn">/pages/lZD6w7ZNrPaXH8F0kQNn</a></td></tr><tr><td><strong>How to use divider lanes</strong></td><td>Separate sections of a journey with a labelled horizontal line.</td><td><a href="/pages/zzJGjcbYJh57GoelmXzE">/pages/zzJGjcbYJh57GoelmXzE</a></td></tr></tbody></table>


# How to add and manage columns

Add, move, and remove the columns of a journey map so its steps line up with the way your experience actually unfolds.

Columns are the steps of your journey map, running left to right across the canvas and grouped under the stages above them. Add, move, and remove them from the three-dot menu at the top of any column.

<figure><img src="/files/vPB5OjQkVz5uALn6avBw" alt="A journey map editor. The Stages lane at the top holds a green Discover chevron and a blue Apply chevron that each span several columns. Below it, a Steps lane holds text cards reading Research Account Options, Start Online Application, and Submit Documents and Information, with a Storyboard image lane and a Channels icon lane beneath. A three-dot menu sits centered above each column."><figcaption><p>Columns are the steps; stages group them, and a three-dot menu sits above each column</p></figcaption></figure>

Each column is one step, and cards snap to columns. A card can fill a single column or span several, depending on how much of the journey it covers.

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

#### In this guide

1. [How to add a column](#how-to-add-a-column)
2. [How to move a column](#how-to-move-a-column)
3. [How to select every card in a column](#how-to-select-every-card-in-a-column)
4. [How to delete a column](#how-to-delete-a-column)
5. [How cards span columns](#how-cards-span-columns)
   {% endhint %}

***

#### How to add a column

There are two ways to add a column, and there's no limit on how many you add:

* **Hover between two column headers** at the top of the map until a blue plus-button appears, then click it. This inserts a column right at that spot, which is the quickest way to add a step in the middle of a journey.
* **Open a column's three-dot menu** and click **Add column right** to add an empty column immediately to the right of that one.

<figure><img src="/files/QEwKhAqP9DFZxnN12wSH" alt="A column header three-dot menu open over a journey map, listing five options top to bottom: Add column right, Move column left, Move column right, Select all cards, and Delete column."><figcaption><p>The column menu: Add column right inserts an empty column</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: Inserting a column shifts the cards to its right**

Adding a column pushes existing content one step to the right. A card that spans several columns only shifts if you insert the new column at the card's starting column; insert it part-way through the span and the card stretches to cover the new column instead.
{% endhint %}

***

#### How to move a column

Open the column's three-dot menu and click **Move column left** or **Move column right**. The column and everything in it swaps places with its neighbour, one step at a time.

***

#### How to select every card in a column

Open the column's three-dot menu and click **Select all cards** to select every card in that column at once. From there you can tag them, assign personas, recolour them, or delete them together.

See [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards) for what you can do with a selection.

***

#### How to delete a column

Open the column's three-dot menu and click **Delete column**. The column and every card in it are removed, and the columns to its right shift left to close the gap.

{% hint style="warning" %}

#### **Important: Deleting a column removes its cards too**

Everything in the column goes with it, so move any cards you want to keep into another column first.
{% endhint %}

***

#### How cards span columns

Cards snap to the column grid, and a single card can span more than one column when its content covers several steps. A stage card stretches across the steps that make up one phase; a text card can span columns to label a process that runs over several steps.

Spanning is set on the card itself, and the steps differ a little by card type:

* [How to use stage cards](/journey-maps/cards/how-to-use-stage-cards) - Span a chevron-shaped stage card across the step columns its phase covers.
* [How to use text cards](/journey-maps/cards/how-to-use-text-cards) - Expand or shrink a text card across columns to build a process bar.

***

#### 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 manage lanes</strong></td><td>Add, rename, reorder, and remove the lanes that cross your columns.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to use stage cards</strong></td><td>Group your step columns into phases with chevron-shaped stage cards.</td><td><a href="/pages/YeVZqUkvqujOSrFxYHsT">/pages/YeVZqUkvqujOSrFxYHsT</a></td></tr><tr><td><strong>How to use text cards</strong></td><td>Span a text card across columns to label a process or phase.</td><td><a href="/pages/icqgg4Jls9Iv7VWRvRls">/pages/icqgg4Jls9Iv7VWRvRls</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards to a column and edit the mechanics every card type shares.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select every card in a column and apply tags, personas, or colour in one go.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to use emotion chart lanes

Plot how a persona feels at each step of a journey, set the sentiment scale, and chart one line per persona or custom group.

An emotion chart lane plots how sentiment rises and falls across the steps of a journey, as a curve with a data point at each step. Set the points and you have the emotional arc of the experience in one row, alongside the actions and touchpoints that drive it.

<figure><img src="/files/Xqg4CDPqd9GQPKLpFtfI" alt="A journey map editor with an Emotion chart lane. Inside the lane, a blue Edit chart link and a Current state legend sit above a sentiment curve plotted on a vertical scale marked 2, 1, 0, -1, -2. Round face icons mark the data point at each step: a neutral face near 0, a frowning face at -2, and a smiling face near +1, joined by a continuous line."><figcaption><p>The lane plots a sentiment curve across the journey steps</p></figcaption></figure>

To add one, hover an empty spot below a lane, click **+ Add lane**, and choose **Emotion chart** under **BASIC LANES**. The shared add-and-manage steps are covered in [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes); this article covers what's specific to the emotion chart.

An emotion chart lane holds the sentiment curve, not cards. Its three-dot menu drops the card and clipboard actions other lanes have, and adds **Edit scale** for the points on the vertical axis.

***

#### How the chart reads

Each step has a data point, and the points join into a continuous line. Drag a point up or down to change the sentiment at that step. The face icon on the point updates to match the value, so a glance at the curve shows where the experience peaks and where it dips.

You don't have to set every step. Leave a point blank and the line interpolates across the gap, drawing straight through to the next point you've set rather than breaking the curve.

***

#### How to add and assign emotion lines

A line is one sentiment curve. A lane can hold as many lines as you like, so you can compare how several personas experience the same journey, or track sentiment against a custom benchmark. New lanes start with one line.

Click **Edit chart** in the lane to open the line list. Each line shows its colour, its name, and controls to rename or delete it. The two buttons at the bottom add a new line.

<figure><img src="/files/y8q9qc520Hlk1FXJWbuE" alt="An Edit Chart panel listing one line, Current state, with a grey colour dot, an edit pencil, and a delete icon. Two buttons sit below: a filled Add persona line button and an outlined Add custom line button."><figcaption><p>Edit Chart: the line list, with buttons to add a persona or custom line</p></figcaption></figure>

* **Add persona line** - Pick a persona from your workspace. The line takes that persona's name and colour, which ties the curve to who it represents.
* **Add custom line** - Name and colour the line yourself, for sentiment that isn't tied to a single persona, like a target curve or an aggregate.

The two kinds convert into each other from the line's edit controls, so a custom line can become a persona line later, and the reverse.

{% hint style="info" icon="user-group" %}
A persona line on the chart is independent of the personas you assign to cards. Adding a persona line here doesn't assign that persona to any card, and assigning a persona to a card doesn't add a line. To assign personas to cards, see [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).
{% endhint %}

For a strategic example, here's using an emotion line to contrast current and future state on one map:

{% embed url="<https://www.loom.com/share/67bcd20749984c31aef97bdea3f928b0>" %}

***

#### How to set the sentiment scale

The vertical scale has five points, set to +2 at the top down to -2 by default, with 0 as the neutral midpoint. You can't add or remove points, but the value shown at each point is customizable: replace the default numbers with your own numbers, or with words, for example **Delighted**, **Satisfied**, **Neutral**, **Frustrated**, and **Angry**.

{% stepper %}
{% step %}
**Open Edit scale**

Click the lane's three-dot menu and select **Edit scale**.
{% endstep %}

{% step %}
**Relabel the points**

Each of the five points has a text field pre-filled with its number. Edit any of them to a number, word, or phrase that fits your scale, then click **Save**.

<figure><img src="/files/1gAhzg6CSfOje7rO9osZ" alt="An Edit scale modal with five rows. Each row shows a fixed scale point on the left (2, 1, 0, -1, -2) next to an editable text field pre-filled with that number. Cancel and Save buttons sit at the bottom right."><figcaption><p>Edit scale: relabel each of the five fixed points</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The labels you set apply to every line in the lane.

***

#### 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 manage lanes</strong></td><td>Add an emotion chart lane, and the shared mechanics for reordering, pinning, and removing lanes.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to manage personas</strong></td><td>Create and edit the personas you plot as lines on the chart.</td><td><a href="/pages/oScEAxHrtqqY2twvz5kM">/pages/oScEAxHrtqqY2twvz5kM</a></td></tr><tr><td><strong>How to assign a persona to a card</strong></td><td>Tag cards with a persona, which is separate from charting a persona line here.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>How to use grid lanes</strong></td><td>Another structured lane type: a grid of named rows that hold cards.</td><td><a href="/pages/lZD6w7ZNrPaXH8F0kQNn">/pages/lZD6w7ZNrPaXH8F0kQNn</a></td></tr></tbody></table>


# How to use grid lanes

Subdivide a lane into named rows that cross your journey's columns, for tables, channels, or matrix-style content.

A grid lane is a single lane split into named rows (sometimes called swim lanes) that cross every column of your map, so you can lay out tables, per-channel breakdowns, or any matrix-style content in one block. Each cell sits where a row meets a column, and holds cards of any type.

<figure><img src="/files/fIU0jvHSSf9iT4EjtnnT" alt="A journey map editor showing a grid lane named Process. Two rows labelled Marketing and Back office run down the left of the lane, crossing the map&#x27;s step columns. A blue Edit rows link sits at the top-left of the lane. The Marketing row holds a blue text card reading Acquisition, and the Back office row holds a red text card reading Know your customer checks."><figcaption><p>A grid lane: named rows crossing the map's columns, each cell holding cards</p></figcaption></figure>

To add a grid lane, use the **+ Add lane** picker and choose **Grid** under **BASIC LANES**, the same way you add any other lane. See [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes) for the full add and manage flow.

***

#### How to start from a grid lane template

Click **Templates** next to **Edit rows** in the lane header to open **Grid lane templates**, which offers four ready-made layouts: **Gantt chart**, **RACI Matrix**, **Prioritization matrix**, and **Project roadmap**. Pick the one closest to what you're building instead of setting up rows and cards from scratch.

<figure><img src="/files/0m6fkfgq6q281DX2wgjw" alt="The Grid lane templates dialog, showing four layout thumbnails: Gantt chart, RACI Matrix, Prioritization matrix, and Project roadmap, each with a one-line description underneath."><figcaption><p>Grid lane templates</p></figcaption></figure>

***

#### How to set up the rows

A grid lane's rows are the dimensions you're laying out down the side, like teams, channels, or systems. Define them from the **Edit rows** link at the top-left of the lane.

{% stepper %}
{% step %}
**Open Edit rows**

Click **Edit rows** at the top-left of the grid lane. The **Edit rows** dialog opens, listing the rows the lane currently has.
{% endstep %}

{% step %}
**Add, rename, recolour, or reorder the rows**

Click **+ Add row** to add a row, and type a name in each row's name field. The colour swatch on each row sets that row's background colour, the drag handle reorders the rows, and the trash icon deletes a row. Click **OK** to apply.
{% endstep %}
{% endstepper %}

<figure><img src="/files/IWPndN3AXMwIplRjeNsQ" alt="The Edit rows dialog open over a grid lane. It lists two rows, Marketing and Back office, each with a drag handle, a colour swatch, a name field, and a delete icon. A + Add row link sits below the rows, and an OK button is at the bottom right."><figcaption><p>Edit rows: name, recolour, reorder, or delete each row</p></figcaption></figure>

The row names then run down the left of the lane, one per row, and each row stretches across all of the map's columns.

***

#### How cards work in a grid cell

Each cell is where a row crosses a column, and it can hold cards of any type, which is what makes a grid flexible: a text card for a note, an icon card to show the channels active at that step, a metric, or anything else. Text cards are the default, so adding a card to an empty cell gives you a text card unless you pick another type, and a cell can hold more than one card, stacked vertically.

Adding and editing cards in a grid cell works the same as anywhere else on the map. See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the card add flow and shared mechanics, and [How to use text cards](/journey-maps/cards/how-to-use-text-cards) for the cell default.

For an applied example, here's using a grid lane to build a service-blueprint process view:

{% embed url="<https://www.loom.com/share/dec99e2a069d4324b13dbd1ee265b3aa>" %}

***

#### 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 manage lanes</strong></td><td>Add a grid lane, reorder it, recolour it, or delete it, alongside every other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to add and manage columns</strong></td><td>Set up the step columns that a grid lane's rows cross.</td><td><a href="/pages/WNBA1RdaCt3rMhxOcLHD">/pages/WNBA1RdaCt3rMhxOcLHD</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards to a grid cell and manage their tags, personas, and comments.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use text cards</strong></td><td>Write and format the text cards that fill grid cells by default.</td><td><a href="/pages/icqgg4Jls9Iv7VWRvRls">/pages/icqgg4Jls9Iv7VWRvRls</a></td></tr><tr><td><strong>How to use divider lanes</strong></td><td>Separate sections of a map with a labelled horizontal divider.</td><td><a href="/pages/zzJGjcbYJh57GoelmXzE">/pages/zzJGjcbYJh57GoelmXzE</a></td></tr></tbody></table>


# How to use flow lanes

Map a process in a flow lane by drawing connector arrows between cards, with swimlanes, columns, and lines of interaction for service blueprints.

A flow lane shows how one step leads to the next. It works like a grid lane, split into named rows (swimlanes) that cross your map's columns, with one extra ability: you draw connector arrows from card to card to trace a process, sequence, or decision flow. It is the lane type for service blueprints, system and process flows, decision trees, and dependency maps.

<figure><img src="/files/Z5q7FQ2Ev6OEJC33bfDw" alt="A journey map with a flow lane at the top. Two swimlanes hold three cards, Submit application, Approved, and Manual review, joined by grey connector arrows. An Edit rows link and a Hold Cmd to add cards hint sit in the lane header."><figcaption><p>A flow lane: cards in swimlanes, joined by connector arrows</p></figcaption></figure>

{% hint style="info" icon="tag" %}
Flow lanes are available on the **Repository** plan and above.
{% endhint %}

Here is a quick tour of flow lanes in action before the step-by-step below.

{% embed url="<https://www.youtube.com/watch?v=btPZpN7pEvs>" %}

To add a flow lane, use the **+ Add lane** picker and choose **Flow** under **ADVANCED LANES**, the same way you add any other lane. A new flow lane arrives with a small starter example (a couple of swimlanes, a few cards, and connectors) that you can edit or replace. See [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes) for the full add and manage flow.

Because a flow lane keeps the column grid, its cards reflow when you add or remove a column, which keeps the flow aligned to your journey's steps. If your diagram doesn't follow those steps and you want cards to stay exactly where you put them, use a [freeform lane](/journey-maps/lanes/how-to-use-freeform-lanes) instead.

***

#### How to start from a flow lane template

Click **Templates** next to **Edit rows** in the lane header to open **Flow lane templates**, which offers four ready-made layouts: **BPMN**, **Decision tree**, **Service blueprint**, and **User story map**. Pick the one closest to what you're mapping instead of building swimlanes and connectors from scratch.

<figure><img src="/files/40SjzP9GYqADRLedBneX" alt="The Flow lane templates dialog, showing four layout thumbnails: BPMN, Decision tree, Service blueprint, and User story map, each with a one-line description underneath."><figcaption><p>Flow lane templates</p></figcaption></figure>

***

#### How to add cards to a flow lane

In a flow lane, clicking and dragging draws connectors, so adding a card uses a modifier key to keep the two actions apart. Hold **Cmd** (Mac) or **Ctrl** (Windows) and hover an empty cell to reveal a **+ Add card** button, then click it to add a card. The lane header shows the reminder **Hold ⌘ CMD to add cards**. The connectors step out of the way while you add, so you can drop a card without catching a connector.

<figure><img src="/files/LqQVwtmXnCdhqhvIMbJs" alt="A flow lane with the Cmd key held, showing a blue + Add card button in an empty cell so a card can be added without drawing a connector."><figcaption><p>Hold Cmd or Ctrl to reveal + Add card in an empty cell</p></figcaption></figure>

Cards live where a swimlane meets a column, the same as a grid lane, and a cell can hold cards of any type. Adding and editing card content works the same as anywhere else on the map. See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the shared card mechanics.

***

#### How to connect cards

Connectors run from card to card within the same flow lane. They cannot connect to cards in another lane, but inside the lane they run from any edge to any edge, in any direction, and can cross swimlanes and span columns.

{% stepper %}
{% step %}
**Select the card to connect from**

Click a card. It shows a blue selection border and four connector attach points, one at the middle of each edge (top, bottom, left, and right).

<figure><img src="/files/nKnDQGPZfsoeVqY4pCsu" alt="A selected flow card, Submit application, showing four blue connector attach points at its top, bottom, left, and right edges, with the card toolbar above."><figcaption><p>Click a card to show its four connector attach points</p></figcaption></figure>
{% endstep %}

{% step %}
**Drag from an attach point to another card**

Drag from one of the attach points onto the card you want to connect to, and release. Smaply draws an arrow from the first card to the second, with the arrowhead at the target. Repeat to branch a card to more than one destination.

<figure><img src="/files/WTh20txoNcXcN4jCi5aY" alt="Three flow cards joined by connector arrows. Submit application points to both Approved and Manual review, and Manual review now points to Approved."><figcaption><p>The new connector, drawn from Manual review to Approved</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### How to edit or remove a connector

Click a connector to select it. Its two ends show as small circles, the **Retarget source** and **Retarget target** handles. Drag either handle onto a different card or edge to re-route that end. To remove a connector, select it and press **Delete** or **Backspace**.

***

#### How to set up swimlanes and lines of interaction

A flow lane's rows are its swimlanes, and you can also add horizontal lines of interaction across the lane, the reference lines a service blueprint uses (a line of visibility, a line of interaction, and so on). Both live in the **Edit rows** dialog.

{% stepper %}
{% step %}
**Open Edit rows**

Click **Edit rows** at the top-left of the flow lane. The dialog lists the lane's current swimlanes.
{% endstep %}

{% step %}
**Add swimlanes and lines**

Click **+ Add row** to add a swimlane, and type a name in each row's field. Click **+ Add line** to add a line of interaction: it comes named **Line of visibility** by default, so rename it to whatever the blueprint needs, set its colour with the swatch, and switch between a solid and dashed style with the toggle. Reorder rows and lines with their drag handles, remove any with the trash icon, and click **OK** to apply.

<figure><img src="/files/wrJdUUJhWs75u4qemEdK" alt="The Edit rows dialog for a flow lane, listing swimlane 1 and swimlane 2, each with a drag handle, colour swatch, name field, and delete icon, plus + Add row and + Add line links and an OK button."><figcaption><p>Edit rows: + Add row for swimlanes, + Add line for a line of interaction</p></figcaption></figure>
{% endstep %}
{% endstepper %}

A line of interaction then runs full-width across the lane, labelled with its name down the left. Connectors can cross it, so you can show a step moving from one side of the line to the other.

<figure><img src="/files/QOYoXL2Mygu1YJ9MwnCF" alt="A flow lane with a full-width horizontal Line of visibility drawn across it below the swimlanes, added as a line of interaction."><figcaption><p>A Line of visibility rendered across the flow lane</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 freeform lanes</strong></td><td>The off-grid sibling with the same connectors, where cards stay exactly where you place them.</td><td><a href="/pages/Bnaj9wTInkeAEiI52N36">/pages/Bnaj9wTInkeAEiI52N36</a></td></tr><tr><td><strong>How to use grid lanes</strong></td><td>The row-and-column lane a flow lane is built on, without the connectors.</td><td><a href="/pages/lZD6w7ZNrPaXH8F0kQNn">/pages/lZD6w7ZNrPaXH8F0kQNn</a></td></tr><tr><td><strong>How to add and manage lanes</strong></td><td>Add a flow lane, reorder it, recolour it, or delete it, alongside every other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards to a flow lane's cells and manage their tags, personas, and comments.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use divider lanes</strong></td><td>Separate whole sections of a map with a labelled horizontal divider.</td><td><a href="/pages/zzJGjcbYJh57GoelmXzE">/pages/zzJGjcbYJh57GoelmXzE</a></td></tr></tbody></table>


# How to use freeform lanes

Place cards anywhere on an open canvas and connect them with arrows, for whiteboard-style diagrams inside your journey map.

A freeform lane turns a lane into an open canvas. Cards sit wherever you drop them instead of snapping to the column grid, and they stay exactly there when columns are added or removed elsewhere on the map.

<figure><img src="/files/iRKCsX0ys5LEvwc2HN1J" alt="A freeform lane at the top of a journey map. Four cards joined by connector arrows sit off the column grid, an image card acts as a backdrop with two text cards overlaid on it as callouts, and a pale green card sits behind a cluster of three cards as a grouping zone. The flow lane below shows the column dividers the freeform lane does not have."><figcaption><p>A freeform lane: cards placed off the grid, joined by connectors</p></figcaption></figure>

{% hint style="info" icon="tag" %}
Freeform lanes are available on the **Repository** plan and above.
{% endhint %}

To add a freeform lane, use the **+ Add lane** picker and choose **Freeform** under **ADVANCED LANES**, the same way you add any other lane. A new freeform lane arrives with a small starter example, two cards reading **Start** and **End** joined by a connector, that you can edit or replace. See [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes) for the full add and manage flow.

<figure><img src="/files/5LCBmMXUcfwmVRSzxSlc" alt="A newly added freeform lane at the top of a journey map. Its header shows a Templates link and the hint Hold ⌘ CMD to add cards, and the canvas holds two cards, Start and End, joined by a connector arrow."><figcaption><p>A new freeform lane, with its starter example</p></figcaption></figure>

The lane's three-dot menu works like any other lane's, with one exception: a freeform lane has no **Duplicate lane below**. To get a second copy, use **Copy lane** and then **Paste lane below**.

***

#### How to start from a freeform lane template

The quickest way to a useful freeform lane is to start from a template instead of placing every card yourself. Click **Templates** in the lane header to open **Freeform lane templates**, which offers four ready-made diagram layouts: **Concept hierarchy**, **Mind map**, **Affinity map**, and **Root cause (Fishbone diagram)**. Pick the one closest to what you're mapping, then relabel the cards.

<figure><img src="/files/zrfB44S2Vatn6w5lKVnh" alt="The Freeform lane templates dialog, showing four layout thumbnails: Concept hierarchy, Mind map, Affinity map, and Root cause (Fishbone diagram), each with a one-line description underneath."><figcaption><p>Freeform lane templates</p></figcaption></figure>

***

#### How to add and position cards on a freeform canvas

A freeform lane has no **+ Add card** button. Adding a card uses a modifier key instead.

{% stepper %}
{% step %}
**Hold Cmd and click where you want the card**

Hold **Cmd** (Mac) or **Ctrl** (Windows) and click any spot on the canvas. The card picker opens at the point you clicked. The lane header shows the reminder **Hold ⌘ CMD to add cards**.

<figure><img src="/files/S2l8JZQQkAYuDg1nTg6J" alt="A freeform lane with the card picker open at the point on the canvas that was Command-clicked. The picker offers Text as the Enter quick-select, then BASIC CARDS with Image, Stage, Icons, and Slider, and ADVANCED CARDS with Embed, Planning, and Metric, the list continuing past the bottom of the frame."><figcaption><p>Cmd-click opens the card picker at that spot</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a card type**

A freeform lane holds every card type, and **Text** is the default, so press Enter to take it. The new card lands with its top-left corner exactly where you clicked.
{% endstep %}
{% endstepper %}

To move a card afterwards, drag it. Nothing snaps and no column highlights, so it stays where you release it. If dragging selects the card's text instead of moving the card, click away from it first to leave edit mode.

To change a card's width, drag its right edge. Freeform cards take any width, which is also why **Expand** and **Shrink** are greyed out in the card menu: there are no columns to span. Height follows the content, so a text card grows as you type and an image card scales to keep its proportions.

Editing card content, colours, tags, personas, and comments works the same as anywhere else on the map. See [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards) for the shared card mechanics.

***

#### How to connect cards in a freeform lane

Cards in a freeform lane connect with the same arrows as a flow lane. Click a card to show its four attach points, one at the middle of each edge, then drag from an attach point onto another card and release. Connectors stay inside the one lane, and inside it they run from any edge to any edge in any direction.

<figure><img src="/files/86d0LKIdFJeoBhbiT6rO" alt="A selected card in a freeform lane, reading Automated check, showing four blue connector attach points at the middle of its top, bottom, left, and right edges, with the card toolbar above it."><figcaption><p>Click a card to show its four connector attach points</p></figcaption></figure>

For the full connector walkthrough, including how to re-route and remove one, see [How to use flow lanes](/journey-maps/lanes/how-to-use-flow-lanes).

***

#### How to layer and group cards by overlapping them

Cards on a freeform canvas can overlap, which gives you two layouts the grid can't. Both are built from ordinary cards.

An image card works as a backdrop with text cards laid over it as callouts, which is how you annotate a screenshot, a photo of a whiteboard, or a piece of research. See [How to use image cards](/journey-maps/cards/how-to-use-image-cards) for getting a picture into the card.

<figure><img src="/files/qoh5JXtkHC7V8mdqZcuw" alt="An image card used as a backdrop in a freeform lane, with two white text cards overlaid on top of it as callouts reading No progress shown and Which ID counts?"><figcaption><p>An image backdrop with text cards as callouts</p></figcaption></figure>

One wide card in a pale accent colour with the **Light background** style, sitting behind a cluster, reads as a labelled zone. The card's own text becomes the group label.

<figure><img src="/files/ITgc6TUzzNHgUpbL3Pxt" alt="A wide pale green card labelled Verification steps sitting behind three white text cards reading ID document, Selfie check, and Proof of address, so the group reads as one labelled zone."><figcaption><p>A pale card behind a cluster, read as a labelled zone</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: The card you add first sits in front**

Stacking follows the order the cards were added, and you can't change it afterwards. There is no bring to front or send to back, and dragging a card doesn't restack it.

So build these layouts back to front: add the callouts before the backdrop image, and the cluster before the grouping card. A card that ends up completely covered by a later one can't be clicked at all.
{% endhint %}

<figure><img src="/files/rFNPZfftLZFs0SsQ3gaE" alt="Two overlapping cards in a freeform lane. The later-added card, Manual review, sits behind the earlier Automated check card, and its text is clipped where the two overlap."><figcaption><p>The later-added card sits behind the earlier one</p></figcaption></figure>

***

#### How to make a freeform lane taller

A freeform lane is as wide as the map, and it grows downward when the diagram needs more room. Hover the strip along the lane's bottom edge until a blue line appears across the full width of the lane, then drag that line down.

<figure><img src="/files/a0RZ6cnlAUhk5T6jYm1A" alt="The bottom of a freeform lane with a solid blue line drawn across the full width of the lane, revealed by hovering the strip at the lane&#x27;s bottom edge. The flow lane header sits directly below it."><figcaption><p>Hover the lane's bottom edge to reveal the blue resize line</p></figcaption></figure>

***

#### Why freeform cards stay put when columns change

Freeform cards belong to the canvas, not to a column, and the lane shows it: a freeform lane draws no column dividers inside it while its neighbours do. Add a column anywhere on the map and every freeform card keeps its exact position, while cards in grid and flow lanes reflow to follow the new structure.

<figure><img src="/files/iRKCsX0ys5LEvwc2HN1J" alt="A journey map with a freeform lane above a flow lane. The freeform lane holds an off-grid flow of four cards, an image backdrop with callouts, and a pale grouping zone. In the flow lane below, the card Approved sits in the second column."><figcaption><p>Before: Approved sits in the flow lane's second column</p></figcaption></figure>

<figure><img src="/files/xrJgtnUFBW5dmu1qppbD" alt="The same journey map after a column is added. Every card in the freeform lane is in exactly the same place, while in the flow lane below the card Approved has moved one column to the right."><figcaption><p>After adding a column: the freeform cards have not moved, and Approved has shifted one column right</p></figcaption></figure>

Deleting a column doesn't move freeform cards either, and it doesn't delete the ones sitting over it. For the column controls themselves, see [How to add and manage columns](/journey-maps/lanes/how-to-add-and-manage-columns).

{% hint style="warning" %}

#### **Important: A card's position carries no meaning for the columns**

Because freeform cards never reflow, a card sitting above a column has no relationship to that step. Don't read the columns underneath a freeform lane as labels for what's above them, and don't rely on horizontal position to say which step a card belongs to. Use a connector or the card's own text instead.
{% endhint %}

***

#### Freeform lanes vs flow lanes

Freeform and flow lanes both connect cards with arrows. The difference is structure: a flow lane keeps the column grid, and a freeform lane drops it.

* **Freeform lane** - an open canvas where cards stay exactly where you place them. Best for whiteboard-style diagrams that don't follow the journey's steps.
* **Flow lane** - a grid of swimlanes and columns where cards align to steps and reflow when you add a column. Best for service blueprints and process flows tied to the journey.

|                                         | **Freeform lane**                           | **Flow lane**                                                   |
| --------------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| **Best for**                            | Whiteboard-style diagrams, off-grid layouts | Service blueprints and process flows tied to journey steps      |
| **Card placement**                      | Anywhere on the canvas, and it stays there  | Snaps to a swimlane and column, and reflows when columns change |
| **Card width**                          | Any width, no snapping                      | Snaps to column boundaries                                      |
| **Column grid?**                        | <i class="fa-xmark">:xmark:</i> No          | <i class="fa-check">:check:</i> Yes                             |
| **Swimlanes and lines of interaction?** | <i class="fa-xmark">:xmark:</i> No          | <i class="fa-check">:check:</i> Yes                             |
| **Connector arrows?**                   | <i class="fa-check">:check:</i> Yes         | <i class="fa-check">:check:</i> Yes                             |

***

#### 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 flow lanes</strong></td><td>The grid-based sibling with swimlanes and columns, where connected cards follow the journey's steps.</td><td><a href="/pages/qMJDhOYEVQ0ekNH9KpPU">/pages/qMJDhOYEVQ0ekNH9KpPU</a></td></tr><tr><td><strong>How to add and manage lanes</strong></td><td>Add a freeform lane, reorder it, recolour it, or delete it, alongside every other lane type.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards to a freeform lane and manage their tags, personas, and comments.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to add and manage columns</strong></td><td>Add, remove, and reorganise the columns that freeform cards deliberately ignore.</td><td><a href="/pages/WNBA1RdaCt3rMhxOcLHD">/pages/WNBA1RdaCt3rMhxOcLHD</a></td></tr><tr><td><strong>How to use grid lanes</strong></td><td>The row-and-column lane a freeform lane drops the grid from, for tables, channels, and matrices.</td><td><a href="/pages/lZD6w7ZNrPaXH8F0kQNn">/pages/lZD6w7ZNrPaXH8F0kQNn</a></td></tr></tbody></table>


# How to use divider lanes

Split a journey map into clear sections with a full-width labelled line, useful for service-blueprint lines like Line of Visibility.

A divider lane draws a labelled horizontal line across the full width of a journey map, so you can visually separate one section from the next. It holds no cards. Add one the same way as any lane, from the **+ Add lane** picker under **BASIC LANES** (see [How to add and manage lanes](/journey-maps/lanes/how-to-add-and-manage-lanes)), then label and style the line to suit.

<figure><img src="/files/gyYL7gywK8RhI30bCRkP" alt="A journey map editor with a full-width black horizontal line labelled Dividing lane running between a Process grid lane above and an Emotion chart lane below. The divider has its own three-dot menu on the far left where the other lanes show their titles."><figcaption><p>A divider lane separating two sections of a journey map</p></figcaption></figure>

Because a divider holds no cards, its lane menu is shorter than a standard lane's. The three-dot menu carries **Pin lane**, **Edit divider**, **Duplicate lane below**, **Move lane up**, **Move lane down**, and **Delete lane**, with no card or clipboard actions. Everything specific to a divider is set in the **Edit divider lane** modal.

#### How to label and style a divider lane

Open the divider lane's three-dot menu and click **Edit divider** to open the **Edit divider lane** modal.

<figure><img src="/files/Y7hS2lXNrIcpV3gmXWe8" alt="The Edit divider lane modal with a Text field reading Dividing lane, a Text size control offering 18, 20, and 24 with 20 selected, a Line style control offering solid and dashed with solid selected, a Line weight control offering thin and thick with thick selected, a black Color swatch, and Cancel and Save buttons."><figcaption><p>Edit divider lane</p></figcaption></figure>

The modal holds everything that defines the divider:

* **Text** - the label shown on the line. Leave it blank for a plain line, or name the section it marks, for example a service-blueprint **Line of Visibility**.
* **Text size** - 18, 20, or 24.
* **Line style** - solid or dashed.
* **Line weight** - thin or thick.
* **Color** - the colour of the line and its label, set from the colour picker.

Click **Save** to apply your changes, or **Cancel** to close the modal without changing the divider.

#### 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 manage lanes</strong></td><td>Add a divider lane from the picker, then rename, reorder, pin, duplicate, or delete any lane.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to use grid lanes</strong></td><td>Organise a section into a multi-row matrix above or below a divider.</td><td><a href="/pages/lZD6w7ZNrPaXH8F0kQNn">/pages/lZD6w7ZNrPaXH8F0kQNn</a></td></tr><tr><td><strong>How to use emotion chart lanes</strong></td><td>The other special lane type: visualise sentiment across the journey with an emotion line.</td><td><a href="/pages/MSglvHiirbEdJK3Ivwqu">/pages/MSglvHiirbEdJK3Ivwqu</a></td></tr></tbody></table>


# How to copy lanes across journey maps

Copy a whole lane, cards and all, and paste it into any other journey map, even one in another workspace or account.

Copy a lane once and reuse it anywhere. **Copy lane** takes the whole lane, including all of its cards, and lets you paste it into any other journey map, whether that map is in the same workspace, another workspace, or another account you belong to.

#### How to copy a lane and paste it into another map

<figure><img src="/files/DDCFiEbrL4Bxu4impKpq" alt="Copying a lane from one journey map using the lane three-dot menu, then pasting it into another map with the Paste lane below banner."><figcaption><p>Copy a lane, then paste it into another map</p></figcaption></figure>

{% stepper %}
{% step %}
**Copy the lane**

Open the lane's three-dot menu and select **Copy lane**. This copies the entire lane, including its name, colour, and every card in it.

<figure><img src="/files/kJlWw0FL7XNv3CRzM7Z8" alt="A lane three-dot menu open on a lane labelled Opportunities to excel. The menu lists Pin lane, Edit lane description, Change color, Select all cards, Paste content, Copy lane, Paste lane below, Duplicate lane below, Move lane up, Move lane down, and Delete lane. Copy lane is highlighted and Paste lane below is greyed out."><figcaption><p>The lane menu, with Copy lane selected</p></figcaption></figure>
{% endstep %}

{% step %}
**Open the map you want to paste into and press Cmd/Ctrl+V**

Go to the destination map, then paste with **Cmd+V** (Mac) or **Ctrl+V** (Windows). The map can be in the same workspace, a different workspace, or a different account.
{% endstep %}

{% step %}
**Pick where the lane lands**

A **Paste lane below** banner appears at the bottom of the screen with a dropdown. Choose a lane from the dropdown and click **Paste**. Your copied lane is inserted directly below the lane you pick.

<figure><img src="/files/uy0YGHjcgtOBq8amInH0" alt="The paste banner at the bottom of the journey map editor, labelled Paste lane below, with an open dropdown listing destination lanes such as Stage, Customer Step, Travel Description, Linked zoomed-in maps, Metrics, and Emotional Journey."><figcaption><p>The paste banner, choosing the lane to paste below</p></figcaption></figure>
{% endstep %}
{% endstepper %}

You can also paste from the destination lane's three-dot menu with **Paste lane below**. That menu item stays greyed out until you have copied a lane.

{% hint style="info" %}
Text, image, icon, slider, stage, and embed cards paste in full. Cards that point to workspace data, such as metrics, portfolio items, and linked journey map cards, only resolve if that data exists in the destination. Pasted into a workspace or account that doesn't have it, those cards arrive in an error state. Items kept in the [Account Library](/account-and-team/how-to-use-the-account-library) stay available across every workspace in the same account.
{% endhint %}

To paste a list, spreadsheet, or other clipboard content into a lane as cards (rather than pasting a copied lane), use **Paste content**. See [How to use enhanced paste](/journey-maps/how-to-use-enhanced-paste).

#### Copy a lane vs duplicate a lane

Both make a copy of a lane with its cards. Which one you want depends on where the copy needs to go.

{% columns %}
{% column %}
**Copy lane**

Copies the lane to your clipboard so you can paste it into a different map, including one in another workspace or account.

Best for reusing a lane across maps.
{% endcolumn %}

{% column %}
**Duplicate lane below**

Drops an identical copy directly beneath the original, in the same map, in one click. It doesn't touch your clipboard.

Best for repeating a lane within one map.
{% endcolumn %}
{% endcolumns %}

#### 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 manage lanes</strong></td><td>Add, rename, recolour, reorder, pin, duplicate, and delete lanes.</td><td><a href="/pages/cEW7pumNPGKdJ65EEAz7">/pages/cEW7pumNPGKdJ65EEAz7</a></td></tr><tr><td><strong>How to use enhanced paste</strong></td><td>Paste spreadsheets and other clipboard content into a lane as cards.</td><td><a href="/pages/8B3eINtya42YPRLS2j7a">/pages/8B3eINtya42YPRLS2j7a</a></td></tr><tr><td><strong>How to copy assets across workspaces</strong></td><td>Copy whole journey maps and templates to another workspace or account.</td><td><a href="/pages/wTx8bqQ9c2foJOedyfim">/pages/wTx8bqQ9c2foJOedyfim</a></td></tr></tbody></table>


# Filters and views

Filter journey map content and save views for quick reuse

Filter journey maps by persona, tag, or other criteria. Save filter and display settings as named views to return to them later or share with teammates.

See filtering in action, from persona and lane views to combining tags with AND/OR logic and saving the result as a view.

{% embed url="<https://www.youtube.com/watch?v=-6zc9QFVfGw>" %}

#### Why use filters and views

* Focus a busy map on just the persona, tag, or content you care about right now
* Save a filter and display setup as a named view to reopen or share it without rebuilding it each time

#### In this section

* [**Filter a map**](/journey-maps/filtering-and-views/how-to-filter-a-journey-map) - Apply filters to focus on specific content.
* [**Save and apply views**](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view) - Save a filter and display setup for quick reuse.


# How to filter a journey map

Narrow a journey map to the cards that matter by filtering on lanes, personas, tags, or portfolio items.

Filter a journey map to show only the cards you care about right now. Open the **Filter** panel above the map, pick a dimension, and choose what to keep visible. Filtering is a temporary view that you (and only you) see until you clear it, so it never changes the underlying map.

#### What you can filter by

Open filtering from the **Filter** toggle in the bar above the map, next to **Views**. The **Filters** panel lists four dimensions, each opening its own submenu, with **Clear all** at the bottom:

* **Lanes** - show only specific rows of the map.
* **Personas** - show only cards assigned to one or more personas.
* **Tags** - show only cards carrying specific tags.
* **Portfolio items** - show only portfolio cards matching a type, status, priority, or assignee.

<figure><img src="/files/wDYLOIERjDuSGw40TwJL" alt="The Filters panel open on a journey map. It lists four dimensions, each with a chevron to a submenu: Lanes, Personas, Tags, and Portfolio items. A Clear all option sits at the bottom."><figcaption><p>The Filters panel and its four dimensions</p></figcaption></figure>

Filters from different dimensions combine with AND, so a tag filter applied on top of a persona filter narrows the result further.

#### How to apply a filter

{% stepper %}
{% step %}
**Open the Filter panel**

In the journey map editor, click **Filter** in the bar above the map, to the left of **Views**.

<figure><img src="/files/rKrhQzlvRcpNk5FTK6Q0" alt="The Filter and Views toggles in the bar above a journey map. Filter is on the left with a sliders icon; Views is on the right with a stacked-layers icon."><figcaption><p>The Filter and Views toggles above the map</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a dimension**

Click **Lanes**, **Personas**, **Tags**, or **Portfolio items** to open that submenu. Each submenu holds its own checkboxes plus a **Clear** for that dimension. The Tags and Portfolio items submenus carry a few extra controls, covered below.
{% endstep %}

{% step %}
**Choose what to keep visible**

Tick the values you want to keep on the map. The map updates as you go, hiding everything that doesn't match. To reset one dimension, use its **Clear**.
{% endstep %}

{% step %}
**Read the active-filter state**

A count badge appears on **Filter**, and each active filter shows as a removable pill in the bar above the map. Click the **x** on a pill to drop that one filter.

<figure><img src="/files/31xtkRbxqo36AINaQ4w4" alt="The filter bar with one active filter. Filter shows a badge reading 1, followed by Views, a pill reading &#x27;Personas: Andre the early-career professional&#x27;, a Create view button, and a Clear button."><figcaption><p>The bar while a filter is active</p></figcaption></figure>

The bar also gains a **Create view** shortcut for saving this filter as a reusable view, and a top-level **Clear**.
{% endstep %}

{% step %}
**Clear the filter when you're done**

To reset everything, click **Clear** in the bar above the map, or **Clear all** at the bottom of the Filters panel. Both remove every active filter and drop any view you have applied. To remove a single dimension instead, open its submenu and click **Clear**, or click the **x** on its pill.
{% endstep %}
{% endstepper %}

***

#### Filter by tags

The **Tags** submenu lists only the tags actually applied to cards on this map, grouped and coloured by tag category (for example **Segment: Family** or **Product: Saving Account**), plus **\[no tag set]** for cards with no tags.

<figure><img src="/files/RIKmLxtzZtZMJmTXlGPO" alt="The Tags submenu open inside the Filters panel. Checkbox options from top: [no tag set], Segment: Family, Product: Saving Account. Below the list is a Match any (OR) dropdown, a Filter by card tags only checkbox with an info icon, and a Clear button."><figcaption><p>The Tags submenu</p></figcaption></figure>

Two controls sit below the tag list:

* **Match any (OR)** sets the matching logic once you tick two or more tags. Match any keeps cards carrying any of the selected tags. The dropdown is inactive until you've selected at least two.
* **Filter by card tags only** narrows the match to tags applied directly to a card on this map. By default, tag filtering also matches data-level tags (tags on the underlying portfolio item or metric, which apply everywhere the item is used). Tick this box to ignore those and match card-level tags only.

***

#### Filter by portfolio items

The **Portfolio items** submenu filters the portfolio cards on the map by attribute. Each attribute opens a further submenu:

* **Type** - the portfolio item types in your account (for example Opportunity, Pain point, Solution, Goals, Risk).
* **Status** and **Status category** - where the item sits in your workflow.
* **Priority** - the item's priority level.
* **Assignee** - the person the item is assigned to.

<figure><img src="/files/6XJzNrF7JKMrOQChTcYF" alt="The Portfolio items submenu open inside the Filters panel. It lists five attributes, each with a chevron to a further submenu: Type, Status, Status category, Priority, and Assignee. A Clear button sits at the bottom."><figcaption><p>Portfolio items filter attributes</p></figcaption></figure>

Pick values across attributes to narrow to, say, high-priority pain points assigned to one teammate. If the map has no portfolio cards, this submenu is empty.

***

#### Filter by personas

The **Personas** submenu lists the personas assigned to a card on this map, plus **\[no persona set]** for cards with no persona. Tick one or several, and use **Match any (OR)** to keep cards assigned to any of them.

For the full persona-filtering walkthrough, including what **\[no persona set]** is useful for, see [How to filter a journey map by persona](/personas/how-to-filter-a-journey-map-by-persona).

***

#### Save a filter for reuse

If you'll return to the same filter often, save it as a view instead of rebuilding it each time. With the filter applied, click **Create view** in the bar above the map. See [How to save and apply a view](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view).

{% hint style="info" icon="compass" %}
A filter must be cleared before you can export the map to PDF. The download button is disabled while any filter is active. See [How to export a journey map as PDF](/sharing-and-exporting/how-to-export-a-journey-map-as-pdf).
{% 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>Save and apply a view</strong></td><td>Save a filter as a named view you can re-open in one click.</td><td><a href="/pages/0biJxUYNUHzaN0wxgwEg">/pages/0biJxUYNUHzaN0wxgwEg</a></td></tr><tr><td><strong>Filter a journey map by persona</strong></td><td>Use persona assignments to focus a map on one or more customer types.</td><td><a href="/pages/zxwopszZeIAP89VtDjFI">/pages/zxwopszZeIAP89VtDjFI</a></td></tr><tr><td><strong>Export a journey map as PDF</strong></td><td>Pick what to include and export the map as a PDF.</td><td><a href="/pages/bFw8ZAfXKB40zpzNx0GL">/pages/bFw8ZAfXKB40zpzNx0GL</a></td></tr></tbody></table>


# How to save and apply a view

Save a filter you use often as a named view, then reopen it on the journey map in one click.

Save a filter you reach for often as a named view, so you can reapply it from the journey map without rebuilding it each time. A view is a saved filter: select it and the map snaps back to the cards that filter shows.

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

#### Plan availability

Saved views are available on the **Repository** plan and above.
{% endhint %}

#### How to save a filter as a view

You save a view from an active filter, so apply the filter you want first. For the full filter flow across lanes, personas, tags, and portfolio items, see [How to filter a journey map](/journey-maps/filtering-and-views/how-to-filter-a-journey-map).

{% stepper %}
{% step %}
**Apply a filter to the map**

In the journey map editor, click **Filter** and set up the filter you want to save. Once at least one filter is active, a **Create view** button appears in the bar, next to **Filter** and **Views**.

<figure><img src="/files/PK6FzJE9oF3dJ38YeTAm" alt="A journey map filtered to one persona. The bar above the canvas shows the Filter button with a count badge, a chip naming the active persona filter, a blue Create view button, and a Clear button."><figcaption><p>Create view appears once a filter is active</p></figcaption></figure>
{% endstep %}

{% step %}
**Open the Create view dialog**

Click **Create view**. The **Create view** dialog opens with a **View name** field and a **Set as my default view** toggle.

<figure><img src="/files/vBmD2AKyF1rLFXhieXAV" alt="The Create view dialog. A View name field holds the text &#x27;Andre&#x27;s experience&#x27;. Below it is a &#x27;Set as my default view&#x27; toggle, then Cancel and Create view buttons."><figcaption><p>Create view dialog</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the view and save**

Give the view a name that describes what it shows, like the persona or segment it isolates. Turn on **Set as my default view** if you want this filter applied automatically each time you open the map. Click **Create view** to save it.
{% endstep %}
{% endstepper %}

***

#### How to apply or switch a saved view

Click **Views** in the bar to open the views dropdown. Use **Type to search** to find a view by name, or pick it from the list, and the map reapplies that view's filter. Once a view is active, the **Views** button relabels to the view's name with an **x** beside it; click the **x** to clear the view and return to the unfiltered map.

<figure><img src="/files/BBwCx6OO0IcO9FCQKaJB" alt="The Views dropdown open on a journey map. It has a &#x27;Type to search&#x27; box at the top and one saved view row, &#x27;Andre&#x27;s experience&#x27;, with a drag handle on its left and a chevron on its right. The Views button in the bar has been relabelled to the active view&#x27;s name with an x to clear it."><figcaption><p>Views dropdown with a saved view</p></figcaption></figure>

Saved views belong to the map, so anyone with access to it sees the same views. To send someone a single view as a read-only link, see [How to share a saved view](/sharing-and-exporting/how-to-share-a-saved-view).

***

#### How to reorder or delete a view

Open the **Views** dropdown and click **Edit views** at the bottom. The **Edit views** dialog lists every saved view, where you can drag a view to reorder it, or open a view's menu to **Set as default view** or **Delete** it.

A view stays in sync with the map. Cards you add inside the filter's scope show up in the view automatically, with no need to re-save. If you change the map's structure in a way that falls outside the view, like adding a new lane, Smaply prompts you to update the view to include or leave out the new content.

#### 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>Filter a journey map</strong></td><td>Filter by lanes, personas, tags, or portfolio items, and combine dimensions.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr><tr><td><strong>Share a saved view</strong></td><td>Generate a separate read-only link for one saved view, independent of the full map.</td><td><a href="/pages/EzewsMl4q3GLzrR9AXm0">/pages/EzewsMl4q3GLzrR9AXm0</a></td></tr><tr><td><strong>Filter a journey map by persona</strong></td><td>Narrow a map to one or more personas using the Personas filter dimension.</td><td><a href="/pages/zxwopszZeIAP89VtDjFI">/pages/zxwopszZeIAP89VtDjFI</a></td></tr></tbody></table>


# How to filter and save list views

Filter a workspace list down to the items you care about, then save that filter as a named view you can favorite to your dashboard.

Narrow the journey maps list to just the items you need, then save that filter as a named view you can reopen in one click. The same filter-and-save mechanism works on your Portfolio, Metric, and Persona lists too.

{% hint style="info" icon="compass" %}
Filtering *inside* a journey map (lanes, personas, portfolio items) works differently. For that, see [How to filter a journey map](/journey-maps/filtering-and-views/how-to-filter-a-journey-map) and [How to save and apply a view](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view).
{% endhint %}

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

#### In this guide

1. [How to filter a workspace list](#how-to-filter-a-workspace-list)
2. [How filtering combines criteria](#how-filtering-combines-criteria)
3. [How to save a filter as a view](#how-to-save-a-filter-as-a-view)
4. [How to edit and update a saved view](#how-to-edit-and-update-a-saved-view)
   {% endhint %}

#### How to filter a workspace list

Open any workspace list (for example **Journey maps** in the sidebar) and click the filter icon in the toolbar, next to the search icon. A dropdown lists the criteria you can filter by.

<figure><img src="/files/nafIzYXMZZKry9JYwIQi" alt="The journey maps list with the toolbar filter dropdown open. The dropdown lists criteria with submenu arrows: Journey map, Creator, Viewed, Created, Performance, Coordinator, Tags, and Content source, with Clear all at the bottom."><figcaption><p>The toolbar filter and its criteria</p></figcaption></figure>

On the journey maps list the criteria are **Journey map**, **Creator**, **Viewed**, **Created**, **Performance**, **Coordinator**, **Tags**, and **Content source**. Click a criterion to open its submenu and pick the values to match. **Clear all** at the bottom removes every filter at once.

The criteria differ slightly per list (the Portfolio, Metric, and Persona lists offer the criteria that fit their content), but the mechanism is the same everywhere.

***

#### How filtering combines criteria

Two rules decide what a filtered list shows:

* Different criteria combine with AND. A **Creator** filter on top of a **Tags** filter narrows the result to items that match both.
* Within one criterion, you choose how its values combine. Each submenu has an operator dropdown with three options.

<figure><img src="/files/wCCm0NhvijCo8P1GHGNJ" alt="A filter criterion submenu with several values selected and the operator dropdown expanded, showing three options: Match any (OR) with the helper text Results match any filters, Match all (AND) with Results match all filters, and Match none (NOT) with Exclude items that match the filter."><figcaption><p>The within-criterion operator: Match any, Match all, Match none</p></figcaption></figure>

* **Match any (OR)** keeps items that match at least one selected value.
* **Match all (AND)** keeps only items that match every selected value.
* **Match none (NOT)** excludes items that match the selected values.

For example, filtering **Tags** by two tags with **Match any (OR)** shows items carrying either tag; **Match all (AND)** shows only items carrying both.

***

#### How to save a filter as a view

Once a filter is applied, an active-filter bar appears above the list with a pill for each filter, a **Clear all** option, and a **Create view** link. Saving turns that filter into a named view you can reopen anytime.

<figure><img src="/files/1G0XotbfNodo4puJ93ew" alt="The Create view dialog over a filtered journey maps list. It has a name field with a lock icon and a favorite star, a View type section with two radio options, Private view (selected) and Shared view, and Cancel and Create view buttons. Above the dialog, the active-filter bar shows a Tags filter pill, Clear all, and a Create view link."><figcaption><p>The Create view dialog</p></figcaption></figure>

{% stepper %}
{% step %}
**Apply the filter you want to save**

Filter the list down to the items you want the view to show. The view stores these filters, so set them before you save.
{% endstep %}

{% step %}
**Click Create view**

In the active-filter bar above the list, click **Create view**. The **Create view** dialog opens.
{% endstep %}

{% step %}
**Name the view and pick its type**

Type a name, then choose a **View type**:

* **Private view** - visible only to you. This is the default.
* **Shared view** - visible to everyone in the workspace.

To favorite the view as you create it, click the star in the name field.

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

#### Shared views are Admin-only

Only admins can create a view that everyone in the workspace can see. If you're not an admin, the **Shared view** option is unavailable and you can save the view as private. \[VERIFY] the exact wording shown to a non-admin on the disabled **Shared view** option.
{% endhint %}
{% endstep %}

{% step %}
**Click Create view to save**

Click **Create view** in the dialog. The saved view appears in the list of views above the filters, ready to reapply.
{% endstep %}
{% endstepper %}

A favorited view appears on your **Dashboard** for quick access, so you can jump straight to a filtered list without reopening the filter.

***

#### How to edit and update a saved view

There are two separate things you can change about a view: its details (name, order, favorite status) and the filter it stores.

To edit a view's details, click the pen icon next to the saved views to open the management interface. From there you can rename a view, rearrange the order they appear in, favorite a view, or delete one.

To update the filter a view stores, select the view to apply it, change the filters (add or remove criteria), then click **Update view**. This overwrites the selected view's filters rather than creating a new one. To keep the original and save the changed filter separately, use **Create view** instead.

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to filter a journey map</strong></td><td>Filter the content inside a map by lanes, personas, tags, or portfolio items.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr><tr><td><strong>How to save and apply a view</strong></td><td>Save an in-editor filter as a named view and reapply it on the map.</td><td><a href="/pages/0biJxUYNUHzaN0wxgwEg">/pages/0biJxUYNUHzaN0wxgwEg</a></td></tr><tr><td><strong>How to bulk-edit journey maps in the list</strong></td><td>Select maps from the list and tag, copy, or archive them in bulk.</td><td><a href="/pages/Rxjr00Vt6P1VkQEfRm2t">/pages/Rxjr00Vt6P1VkQEfRm2t</a></td></tr><tr><td><strong>How to use tags</strong></td><td>Apply tags across maps, cards, and personas so you can filter by them.</td><td><a href="/pages/jphiiSaFZL5tyD29Kfyt">/pages/jphiiSaFZL5tyD29Kfyt</a></td></tr></tbody></table>


# How to bulk edit cards

Select several cards in a journey map at once and tag, recolour, style, assign personas, or delete them in a single action.

Change many cards in a journey map in one go instead of one at a time. Select the cards, then use the bulk action bar to tag them, assign personas, recolour or restyle them, or delete them together.

{% hint style="info" icon="compass" %}
If you want to act on whole journey maps from the dashboard list rather than cards inside one, see [How to bulk-edit journey maps in the list](/journey-maps/how-to-bulk-edit-journey-maps-in-the-list).
{% endhint %}

#### How to select multiple cards

There are three ways to select more than one card:

* **Select all cards in a lane** - Open the lane's three-dot menu and click **Select all cards**.
* **Select all cards in a column** - Open the column header's three-dot menu and click **Select all cards**.
* **Pick cards by hand** - Hold **Shift** and click each card you want. This works across different lanes and columns.

<figure><img src="/files/2pzkjikrIZFj6Hd819p9" alt="A column header three-dot menu open in the journey map editor, listing Add column right, Move column left, Move column right, Select all cards, and Delete column."><figcaption><p>Column menu > Select all cards</p></figcaption></figure>

#### How to apply a bulk action

<figure><img src="/files/09XU2kdL8qrjmOqVUVXR" alt="Several cards selected in a journey map, with the bulk action bar appearing at the bottom of the editor to apply an action across the whole selection."><figcaption><p>Select multiple cards, then apply a bulk action from the bar</p></figcaption></figure>

{% stepper %}
{% step %}
**Select the cards you want to change**

Use any of the three methods above. You can combine them, for example select a whole lane, then Shift+click a few more cards in another lane.
{% endstep %}

{% step %}
**Choose an action from the bulk bar**

Once two or more cards are selected, a bulk action bar appears at the bottom of the editor. Click the action you want to apply to every selected card. The actions on offer depend on whether your selection is one card type or several (see below).

<figure><img src="/files/lo895Fw3jScDmqRQdDDs" alt="The bulk action bar at the bottom of the journey map editor, labelled Bulk edit, 4 text cards. It shows bold, font size, font, and a Height icon, followed by fill, Header, Tags, Persona, and Delete actions."><figcaption><p>The bulk bar for a single-type selection, with the full action set</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The **Tags**, **Persona**, **fill** (colour and background), and **Delete** actions are always available. **Tags** and **Persona** add or remove the same tag or persona across the whole selection. **Delete** removes every selected card at once.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Give a whole lane a matching height**

Select all the cards in a lane (see above), then use **Height** on the bulk bar. Beyond the usual Auto/Small/Medium/Large/Custom sizes, a bulk selection unlocks **Match largest**, which sets every selected card to the height of the tallest one - the quickest way to make a lane's cards line up. See [Set a card's height](/journey-maps/cards/how-to-add-and-edit-cards#set-a-cards-height) for how Height works on a single card.
{% endhint %}

#### Which actions you get: same type vs mixed type

The bulk bar changes depending on the cards you pick. Card formatting and the card header only work when every selected card is the same type, because not all card types share those controls. **Height** is a middle case: it stays on the bar for any selection made up of text and stage cards, since both support it, even though that's technically two types.

{% columns %}
{% column %}
**One card type selected**

The bar reads **Bulk edit** with a count, for example **3 text cards**. You get the full action set: text formatting (**Bold**, size, font), **Height**, **fill**, **Header**, **Tags**, **Persona**, and **Delete**.

Single-type selections also unlock that type's own actions, such as changing the display type of portfolio cards.
{% endcolumn %}

{% column %}
**Mixed card types selected**

The bar reads **Filter** with a count, for example **3 items**. Only the actions every card shares stay on the bar: **fill**, **Tags**, **Persona**, and **Delete**. **Height** also stays if the mix is only text and stage cards.

To reach a type's formatting actions, narrow the selection with the **Filter** dropdown.
{% endcolumn %}
{% endcolumns %}

<figure><img src="/files/XUei3e7RA4MZuf5DJJI9" alt="The bulk action bar for a mixed selection, labelled Filter, 3 items, showing only the fill, Tags, Persona, and Delete actions."><figcaption><p>A mixed-type selection keeps only the shared actions</p></figcaption></figure>

To work on one type within a mixed selection, click **Filter** and choose a card type. The dropdown lists each type in the selection with its count.

<figure><img src="/files/wOW5k3xKxP5bc5g7n5Eo" alt="The Filter dropdown open above the bulk bar, listing Stage, Text, and Image card types, each with a count of 1."><figcaption><p>Filter the selection down to one card type</p></figcaption></figure>

Once the selection is narrowed to a single type, that type's actions appear on the bar, the same set you would see if you had selected only those cards to begin with.

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</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>The card toolbar, details panel, colours, and header for a single card.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use text cards</strong></td><td>Text formatting in detail, including bulk formatting by filtering a selection to Text.</td><td><a href="/pages/icqgg4Jls9Iv7VWRvRls">/pages/icqgg4Jls9Iv7VWRvRls</a></td></tr><tr><td><strong>How to assign a persona to a card</strong></td><td>Assigning personas to cards, including bulk-assigning to a selection.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>How to use tags</strong></td><td>Applying tags to cards and filtering a journey map by them.</td><td><a href="/pages/jphiiSaFZL5tyD29Kfyt">/pages/jphiiSaFZL5tyD29Kfyt</a></td></tr></tbody></table>


# How to bulk-edit journey maps in the list

Select several journey maps from the dashboard list at once and tag, archive, or update them all in a single action.

Change many journey maps at once instead of opening each one. Select the maps you want from the dashboard list, then use the bulk edit bar at the bottom of the screen to tag them, archive them, or update shared settings across the whole selection.

#### How to select maps and open the bulk edit bar

The row checkboxes are hidden until you hover, so they're worth pointing out. Hover over a row to reveal its checkbox, then tick the maps you want.

{% stepper %}
{% step %}
**Open the journey maps list**

In the workspace sidebar, click **Journey maps**.
{% endstep %}

{% step %}
**Select the maps you want**

Hover over the left side of a map's row and a checkbox appears. Tick it to select that map. To select everything in the list, use the checkbox in the header row next to **NAME**.
{% endstep %}

{% step %}
**Use an action from the bulk edit bar**

Once at least one map is selected, a dark **Bulk edit&#x20;*****N*****&#x20;items** bar pins to the bottom of the screen, showing a live count of what you've selected. Pick an action from the bar to apply it to every selected map at once.

<figure><img src="/files/iF5QEOLzLQJ8T5pgqgGY" alt="Journey maps list with two rows selected and the dark Bulk edit 2 items bar pinned at the bottom showing the Users, Coordinator, Performance, Tags, Add to account library, Remove from account library, and Archive actions. The Bulk Edit modal for Tags is open in front."><figcaption><p>Selected maps, the bulk edit bar, and the Tags modal</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### What the bulk edit bar can do

The bar applies one action to every map you've selected:

* **Users** - Add or remove the people assigned to the selected maps.
* **Coordinator** - Set the coordinator across the selection.
* **Performance** - Set the performance status on every selected map.
* **Tags** - Add or remove tags in bulk. See below.
* **Add to account library** and **Remove from account library** - Move the selected maps in or out of the shared account library.
* **Archive** - Archive every selected map. There's no bulk delete; archiving is the closest action, and archived maps stay recoverable. See [How to archive a journey map](/journey-maps/how-to-archive-a-journey-map).

{% hint style="info" icon="tag" %}
The account library actions need the Account Library, available on the **Framework** plan and above once you have two or more workspaces.
{% endhint %}

***

#### How to add or remove tags on several maps at once

Tagging is the most common bulk edit, so it has its own two-step modal.

{% stepper %}
{% step %}
**Click Tags in the bulk edit bar**

The **Bulk Edit** modal opens, confirming how many maps the change will affect.
{% endstep %}

{% step %}
**Choose whether to add or remove**

In the operation dropdown, change **Keep as is** to **Add tags** or **Remove tags**. Leaving it on **Keep as is** makes no change.
{% endstep %}

{% step %}
**Pick the tags**

In the **Select tags** picker, choose the tags to apply or strip. The list shows the tags that already exist in your account.

<figure><img src="/files/eoAvMZkWMSVMbuiR1O47" alt="The Bulk Edit modal with the Select tags picker open, listing existing account tags such as Young Adult, Professional, Family, High Income, Small Business, Corporate, and Retired, each shown as a segment tag."><figcaption><p>The Select tags picker lists existing account tags</p></figcaption></figure>

{% hint style="info" %}
You can only pick from tags that already exist. To create a new tag, go to **Account settings > Tags** first, then come back and apply it here.
{% endhint %}
{% endstep %}

{% step %}
**Save the change**

Click **Save bulk edit**. The tags are added to or removed from every selected map.
{% endstep %}
{% endstepper %}

***

#### How to copy maps to another workspace

Copying maps to another workspace is a per-map action, not part of the bulk edit bar. Open a map's three-dot menu in the list and choose **Copy to other workspace**. For what does and doesn't travel with the copy, see [How to copy assets across workspaces](/account-and-team/workspaces/how-to-copy-assets-across-workspaces).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to archive a journey map</strong></td><td>Archive a map and restore it later from the workspace Archive.</td><td><a href="/pages/0p0xTsJoEwHiuKOfOd3Y">/pages/0p0xTsJoEwHiuKOfOd3Y</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Select and edit several cards at once inside a journey map.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr><tr><td><strong>How to copy assets across workspaces</strong></td><td>Copy a journey map into another workspace and what carries with it.</td><td><a href="/pages/wTx8bqQ9c2foJOedyfim">/pages/wTx8bqQ9c2foJOedyfim</a></td></tr><tr><td><strong>How to manage personas</strong></td><td>Bulk actions on the Personas list work the same way.</td><td><a href="/pages/oScEAxHrtqqY2twvz5kM">/pages/oScEAxHrtqqY2twvz5kM</a></td></tr></tbody></table>


# How to use enhanced paste

Paste tables, text, or images from Excel, Google Drive, Miro, or Mural straight into a journey map, where they land as cards across a lane.

Bring content in from outside Smaply without rebuilding it card by card. Copy a table, a block of text, or an image from another tool, paste it into a journey map, and Smaply spreads it across a lane as cards you can then rearrange.

{% hint style="info" icon="compass" %}
This covers pasting clipboard content into a lane as new cards. To paste a whole lane you copied from another map, see [How to copy lanes across journey maps](/journey-maps/lanes/how-to-copy-lanes-across-journey-maps).
{% endhint %}

You can paste from Excel, Google Drive, Miro, and Mural, among other apps. Tables and text become text cards; images and screengrabs become image cards.

#### How to paste content into a journey map

There are two ways to start a paste:

* **From a lane menu** - Open the lane's three-dot menu and click **Paste content**.
* **With the keyboard** - Press **Cmd+V** (Mac) or **Ctrl+V** (Windows) anywhere in the map.

{% stepper %}
{% step %}
**Start the paste**

Copy your content in the source tool first. Then, in the journey map, either open a lane's three-dot menu and click **Paste content**, or press **Cmd+V** / **Ctrl+V**.

<figure><img src="/files/0z23CSx6vHdtUBfDm9RU" alt="A lane three-dot menu open in the journey editor. The menu lists Change color, Pin lane, Move lane up, Move lane down, Delete lane, Add description, and Paste content, with Paste content highlighted."><figcaption><p>The lane menu, with Paste content selected</p></figcaption></figure>

If you press the shortcut with nothing on your clipboard yet, Smaply shows a prompt with the supported source apps and the **Cmd + V** hint, so you know what you can paste and how.

<figure><img src="/files/6qhgEF3U3GhnjmZyKMWe" alt="A full-screen paste prompt over a journey map reading Paste content using Command V, with icons for Mural, Excel, images, sticky notes, and tables, and the subtitle Paste images, tables and sticky notes from your favorite apps."><figcaption><p>The paste prompt and its supported sources</p></figcaption></figure>
{% endstep %}

{% step %}
**Choose the destination lane**

The **Paste content** window opens with a **Select lane** dropdown, already set to the lane you triggered the paste from. To send the cards elsewhere, pick a different lane from the dropdown. The **Clipboard content** preview below shows the cards that will be created, so you can check the paste before committing. Click **Paste** to confirm, or **Cancel** to back out.

<figure><img src="/files/jPImLZ2KXiMuJxASHOtn" alt="The Paste content window with a Select lane dropdown, a Clipboard content preview showing a row of cards to be created, a notice that excess content will be added to the last column, and Cancel and Paste buttons."><figcaption><p>The Paste content window, with a preview of the cards</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: Extra content piles into the last column**

If the pasted content has more items than the map has columns, the overflow is added to the last column rather than creating new ones. The window flags this with **Excess content will be added to the last column**. To spread everything out, [add columns](/journey-maps/lanes/how-to-add-and-manage-columns) to the map before you paste.
{% endhint %}
{% endstep %}

{% step %}
**Rearrange the new cards**

Smaply adds the content as new cards spread across the lane, one item per card, filling left to right. From here you can move, edit, or delete them like any other card. For the card toolbar and details panel, see [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards).
{% endstep %}
{% endstepper %}

For a worked example, here's a paste straight from Miro:

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2F6fx7eRqiznKoyxTmBs1r%2Fpaste_miro.mp4?alt=media&token=f59cc44a-4447-4eb2-9d06-29c0d9c88aba>" %}

#### How to paste an image or screengrab

Pasting a copied image or a screengrab creates an image card. Copy the image in another app, or take a screengrab, then paste it into the map the same way: from a lane's **Paste content** menu, or with **Cmd+V** / **Ctrl+V**. It lands as an image card in the lane you choose.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FHsjABfkk0SNuNj7GOddS%2Fcopy_and_paste_image.mp4?alt=media&token=de168fec-9fe4-4589-b916-fe971491500f>" %}

For more on working with image cards once they're on the map, see [How to use image cards](/journey-maps/cards/how-to-use-image-cards).

#### 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 copy lanes across journey maps</strong></td><td>Copy a whole lane, cards and all, and paste it into any other map.</td><td><a href="/pages/FfdIjPLBahBicIppECHQ">/pages/FfdIjPLBahBicIppECHQ</a></td></tr><tr><td><strong>How to add and edit cards</strong></td><td>Add cards, edit their content, and manage tags, personas, and comments.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to use image cards</strong></td><td>Add an image to a card and adjust how it fits.</td><td><a href="/pages/UabgkrybgXpRIkiajDwP">/pages/UabgkrybgXpRIkiajDwP</a></td></tr></tbody></table>


# How to use version history

Open a journey map's earlier versions, preview any of them, and roll back to one without losing your current work.

Every journey map keeps a running history of itself. Open the **Version history** panel to see earlier versions, preview any one of them, and restore it as a fresh working copy if you need to step back.

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

#### Plan availability

Version history is available on the **Governance** plan.
{% endhint %}

#### How version history works

Smaply saves a version of your journey map automatically every 10 minutes while you are editing. There is no save-version button to press and no way to create a version on demand. The history builds itself in the background as you work.

Version history covers journey maps only. Personas, portfolio items, and metrics do not have their own version history.

***

#### How to view and restore an earlier version

{% stepper %}
{% step %}
**Open the Version history panel**

In the journey map editor, click the history (clock) icon in the top bar, to the left of the **Share** button. The **Version history** panel opens with **Current version** at the top, followed by earlier versions listed by date and time. Each entry shows the people who edited it.

<figure><img src="/files/UemIFwa7fU69yOUi5Mfq" alt="Version history panel open in the journey map editor. The clock icon sits in the top bar to the left of the Share button. The panel lists Current version at the top, then earlier versions labelled with a date and time and the avatars of the people who edited them."><figcaption><p>Version history panel, opened from the clock icon</p></figcaption></figure>
{% endstep %}

{% step %}
**Click a version to preview it**

Clicking a version opens it as a read-only preview, so you can check its contents before deciding to restore. An **Editing locked** banner across the top confirms you are looking at a past version rather than the live map.

<figure><img src="/files/MsTgMVfgGd0Fv9LMX9Mz" alt="A past version open as a read-only preview. A black Editing locked banner runs across the top, and a floating toolbar at the bottom shows Restore this version and Close version preview."><figcaption><p>Read-only version preview with the floating toolbar</p></figcaption></figure>

To leave the preview without changing anything, click **Close version preview** in the floating toolbar at the bottom.
{% endstep %}

{% step %}
**Restore the version**

With the version you want open in the preview, click **Restore this version** in the floating toolbar. A confirmation dialog explains what happens next; confirm it to restore.

Restoring is non-destructive. It creates a new working version from the one you picked and leaves your current version untouched. The restored copy opens in a new browser tab, where you can carry on editing.
{% endstep %}
{% endstepper %}

***

#### What a restored version does and does not bring back

A version stores only the journey map's own layout and content. Anything that lives outside the map is linked in, not stored, so it always appears as it is today rather than as it was when the version was saved.

{% hint style="warning" %}

#### **Important: linked items do not roll back**

Restoring a version does not revert these. They show their current state, not their state at the time of the version:

* Portfolio items
* The content of metric cards
* The content of embed cards
* The content of planning cards
* Personas
* Tags
  {% endhint %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: restore and rename before a major change**

Before a big round of edits, restore the current version and rename the restored copy. You get a clean checkpoint to work from and a clear way to tell the two apart later.
{% 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 archive a journey map</strong></td><td>Move a journey map out of the active list and bring it back later.</td><td><a href="/pages/0p0xTsJoEwHiuKOfOd3Y">/pages/0p0xTsJoEwHiuKOfOd3Y</a></td></tr><tr><td><strong>How to create a journey map</strong></td><td>Start a new journey map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr><tr><td><strong>What's included in each plan</strong></td><td>See which features, including version history, are available on your plan.</td><td><a href="/pages/cVo65js50L1JDRFJTSTu">/pages/cVo65js50L1JDRFJTSTu</a></td></tr></tbody></table>


# How to archive a journey map

Move a journey map out of your active list while keeping it recoverable, with the option to restore it from the workspace Archive section.

Move a journey map out of your active list while keeping it recoverable. You can bring archived maps back from the workspace **Archive** section any time.

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

#### Prerequisites

Editor or Admin role at the workspace level. Viewers can't archive content.
{% endhint %}

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

#### In this guide

1. [Archive from the journey map editor](#archive-from-the-journey-map-editor)
2. [Archive from the journey maps list](#archive-from-the-journey-maps-list)
3. [Where archived journey maps live](#where-archived-journey-maps-live)
4. [How to restore an archived journey map](#how-to-restore-an-archived-journey-map)
   {% endhint %}

You can archive a journey map two ways: from the three-dot menu next to the title inside the map's editor, or from the three-dot menu on the map's row in the journey maps list. Both open the same confirmation modal.

#### Archive from the journey map editor

Use this when you already have the map open.

{% stepper %}
{% step %}
**Open the journey map**

From the workspace **Journey maps** list, click the map you want to archive to open it in the editor.
{% endstep %}

{% step %}
**Select Archive from the more menu**

Next to the map title in the top bar, click the three-dot menu and select **Archive**.

<figure><img src="/files/IeBzITecYKmekz6mS567" alt="The journey map editor top bar with the three-dot menu open next to the map title &#x27;Versioning map&#x27;. The menu shows Create a copy, Import from Excel, Export as JSON, and Archive."><figcaption><p>Editor > more menu</p></figcaption></figure>
{% endstep %}

{% step %}
**Confirm**

In the **Archive journey map** modal, click **Yes, move to archive**.

<figure><img src="/files/ZvwtysdZYXZ5CnkEZ69r" alt="The Archive journey map confirmation modal. The body reads &#x27;Are you sure you want to archive this journey map?&#x27; with buttons labelled No, cancel and Yes, move to archive."><figcaption><p>Archive journey map confirmation</p></figcaption></figure>

The editor closes and the workspace journey maps list opens. The map is no longer in the list.
{% endstep %}
{% endstepper %}

***

#### Archive from the journey maps list

Use this when you're already on the journey maps list.

{% stepper %}
{% step %}
**Open the journey maps list**

In the workspace sidebar, click **Journey maps**.
{% endstep %}

{% step %}
**Select Archive from the row menu**

On the row for the map you want to archive, click the three-dot menu and select **Archive**.

<figure><img src="/files/j8rTA698EGSohnh47Bhy" alt="A row&#x27;s three-dot menu open on the journey maps list. Menu items: Manage access, Share link (view-only), Rename, Create a copy, Import from Excel, Copy as template, Copy to other workspace, Move to hierarchy, Move to library, Manage tags, Archive."><figcaption><p>Journey maps list > row menu</p></figcaption></figure>
{% endstep %}

{% step %}
**Confirm**

In the **Archive journey map** modal, click **Yes, move to archive**.

The row disappears from the list. You stay on the journey maps page.
{% endstep %}
{% endstepper %}

***

#### Where archived journey maps live

Archived journey maps move to the workspace **Archive** section in the sidebar, between **Templates** and **Settings**.

<figure><img src="/files/g27L6GPqd5G1CmSZyEJ7" alt="The workspace sidebar showing Dashboard, Workspace, Journey maps, Hierarchies, Personas, Portfolio, Metrics, Research, Templates, Archive, and Settings. Archive sits between Templates and Settings."><figcaption><p>Workspace sidebar > Archive</p></figcaption></figure>

The Archive section organises content by type. Category buttons at the top let you switch between **Journey maps**, **Hierarchies**, **Personas**, and **Templates**. **Journey maps** is selected by default.

The list shows the same columns as the active journey maps list: **NAME**, **PERFORMANCE**, **VIEWED**, **CREATOR**, and **TAGS**.

<figure><img src="/files/ybBI7EZpeaY5m3aQUWGc" alt="The workspace Archive section with the Journey maps tab selected. One archived map named &#x27;test&#x27; is listed with columns NAME, PERFORMANCE, VIEWED, CREATOR, TAGS."><figcaption><p>Archive > Journey maps, populated</p></figcaption></figure>

With no archived maps yet, you'll see **No archived journey maps** above the message "Archived journey maps will appear here for future reference."

{% hint style="info" icon="tag" %}
On the **Free** plan you can create up to 10 journey maps, and archived maps still count toward that limit. Archiving won't free up a slot. To make room, delete maps from the Archive (see Archive vs Delete below).
{% endhint %}

***

#### How to restore an archived journey map

Restoring is a one-click action with no confirmation modal.

{% stepper %}
{% step %}
**Open the Archive section**

In the workspace sidebar, click **Archive**. **Journey maps** is selected by default.
{% endstep %}

{% step %}
**Unarchive the map**

On the row for the map you want to bring back, click the three-dot menu and select **Unarchive**.

<figure><img src="/files/k3ij2gGDaa9bBNmHLWdx" alt="The Archive section row three-dot menu open on an archived map. Two items: Unarchive and Delete."><figcaption><p>Archive > row menu</p></figcaption></figure>

The map disappears from the Archive list and returns to the workspace **Journey maps** list in its previous place.
{% endstep %}
{% endstepper %}

{% hint style="info" %}

#### Archive vs Delete

The same row menu has a **Delete** option below **Unarchive**. Archiving is reversible. Deleting permanently removes the map and cannot be undone. As a safeguard, a journey map has to be archived before you can delete it. The same archive-first rule applies to templates. Personas can be deleted directly.
{% 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>Use version history</strong></td><td>Restore a previous version of a journey map without archiving it.</td><td><a href="/pages/aLe0UdsSSiKGSOJEzvb8">/pages/aLe0UdsSSiKGSOJEzvb8</a></td></tr><tr><td><strong>Create a journey map</strong></td><td>Start a new journey map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr><tr><td><strong>Manage workspaces</strong></td><td>Rename or delete a workspace. Workspaces themselves can't be archived.</td><td><a href="/pages/C4Xe3EiMe3LM9zi32k95">/pages/C4Xe3EiMe3LM9zi32k95</a></td></tr></tbody></table>


# Journey map keyboard shortcuts

Every keyboard shortcut for the journey map editor, with Mac and Windows keys side by side.

Work faster in the journey map editor with shortcuts for undo, zoom, and the most common card actions. The table below lists the Mac and Windows keys side by side.

#### Editor keyboard shortcuts

These shortcuts work while you have a journey map open in the editor.

| Action                                 | Mac                     | Windows                 |
| -------------------------------------- | ----------------------- | ----------------------- |
| Undo                                   | `CMD + Z`               | `CTRL + Z`              |
| Redo                                   | `CMD + Y`               | `CTRL + Y`              |
| Zoom in                                | `+`                     | `+` or `CTRL + "+"`     |
| Zoom out                               | `-`                     | `-` or `CTRL + "-"`     |
| Delete card                            | `Backspace` or `Delete` | `Backspace` or `Delete` |
| Expand card (widen across columns)     | `Right arrow`           | `Right arrow`           |
| Shrink card (narrow across columns)    | `Left arrow`            | `Left arrow`            |
| Duplicate card                         | `CMD + D`               | `CTRL + D`              |
| View mode / Hand mode (pan the canvas) | `Spacebar + arrow keys` | `Spacebar + arrow keys` |
| Exit Hand mode                         | `ESC`                   | `ESC`                   |

Card shortcuts act on the card you have selected. Click a card once to select it, then use the shortcut.

#### Other editor interactions

A couple of common actions use the mouse rather than a key combination:

* **Multi-select cards** - Hold `Shift` and click each card you want to include in a selection. See [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards) for what you can do with a multi-card selection.
* **Open a card's details** - Double-click a card to open its details panel.

#### 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>Add, duplicate, delete, and expand cards, plus the card toolbar and details panel.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>How to bulk edit cards</strong></td><td>Use Shift+click to select multiple cards and apply tagging, moving, or deleting in one action.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr><tr><td><strong>How to copy lanes across journey maps</strong></td><td>Copy a lane from its menu and paste it (Cmd/Ctrl+V) into any other journey map.</td><td><a href="/pages/FfdIjPLBahBicIppECHQ">/pages/FfdIjPLBahBicIppECHQ</a></td></tr><tr><td><strong>How to use enhanced paste</strong></td><td>Paste tables, text, or images from external apps (Cmd/Ctrl+V) straight into a map as cards.</td><td><a href="/pages/8B3eINtya42YPRLS2j7a">/pages/8B3eINtya42YPRLS2j7a</a></td></tr></tbody></table>


# Hierarchy maps overview

Build hierarchies of journey maps using linked journey map cards

Hierarchy maps are a dedicated space for managing a map of maps. They use linked journey map cards to connect related journeys in any direction, from a high-level overview down to detailed sub-journeys or across related flows, so you can navigate a complex experience without cramming it onto one map.

{% hint style="info" icon="tag" %}
Hierarchy maps are available on the **Repository** plan and above.
{% endhint %}

### Get started

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Journey vs hierarchy map</h4></td><td>Decide which map type fits what you're capturing.</td><td><a href="/pages/ANYZEQ2NKtnOB6djd635">/pages/ANYZEQ2NKtnOB6djd635</a></td><td><a href="/files/3ZsFztKXi2zFrLSgbWc7">/files/3ZsFztKXi2zFrLSgbWc7</a></td></tr><tr><td><h4>Create a hierarchy map</h4></td><td>Start a new hierarchy and connect journey maps as linked nodes.</td><td><a href="/pages/R4eKe96wbOcrolkAQeNP">/pages/R4eKe96wbOcrolkAQeNP</a></td><td><a href="/files/lMYhSWxYPwYvWelHfVyG">/files/lMYhSWxYPwYvWelHfVyG</a></td></tr><tr><td><h4>Linked journey map cards</h4></td><td>The card type hierarchies are built from: link one map to another.</td><td><a href="/pages/Q15UKTZ5abMpckZ716o9">/pages/Q15UKTZ5abMpckZ716o9</a></td><td><a href="/files/kD4Sko4X2X1br2KAYEI3">/files/kD4Sko4X2X1br2KAYEI3</a></td></tr></tbody></table>


# How to choose between a journey map and a hierarchy map

Decide whether to keep a set of linked journey maps in a dedicated hierarchy space, or link them from a regular journey map instead.

A hierarchy map and a journey map are the same kind of map. You build both the same way, and both can hold **linked journey cards** that point to other maps. The real difference is where a hierarchy map lives and what it is for: it sits in the dedicated **Hierarchies** space, which is built to hold and manage a map of maps.

So the choice is mostly about convenience. If you want a separate, managed home for an overview that links out to other journeys, create a hierarchy map. If you only want to link a related map or two from a journey you are already working in, stay on the journey map.

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

#### Plan availability

Linked journey cards, and the hierarchy maps built from them, are available on the **Repository** plan and above. On the **Free** plan you can still build standard journey maps.
{% endhint %}

#### Linking is flexible, not a fixed tree

Linked journey cards connect maps in any direction, so a hierarchy takes whatever shape your experience does:

* **Zoom vertically** - link a high-level lifecycle map down into a detailed micro-journey, and that into the steps beneath it.
* **Connect horizontally** - link related journeys side by side, like the same stage across different channels or teams.

A hierarchy map is not a rigid top-down tree. It is a canvas you arrange to match how your journeys actually relate.

#### When to use a hierarchy map

* **You want a map of maps** - a high-level overview or management map that links out to the detailed journeys around it, kept in its own space so it does not get lost among your regular journey maps.
* **You are managing a portfolio of connected journeys** - keep the overview clean and let each linked map carry the granular detail, instead of cramming everything onto one map.
* **Different people own different journeys** - link maps that separate teams maintain, while keeping them connected in one view.

<figure><img src="/files/hcX7pCKnFQubI0pWjwUM" alt="A hierarchy map in the editor. A high-level journey sits in the top Linked maps lane, with two more detailed journeys linked in the lane below it. Each shows a map thumbnail, its name, and a Performance Indicator."><figcaption><p>A hierarchy map: a high-level journey linked to the detailed journeys around it</p></figcaption></figure>

#### When a single journey map is enough

* You only need to link one or two related maps from a journey you are already building. Any journey map can hold linked journey cards, so you do not need a hierarchy map for the occasional link.
* The work fits on one map without becoming hard to read.

To build a hierarchy map, see [How to create a hierarchy map](/hierarchy-maps/how-to-create-a-hierarchy-map). For how the linking card works on any map, see [How to use linked journey map cards](/journey-maps/cards/how-to-use-linked-journey-map-cards).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to create a hierarchy map</strong></td><td>Build a hierarchy and connect journey maps as linked nodes.</td><td><a href="/pages/R4eKe96wbOcrolkAQeNP">/pages/R4eKe96wbOcrolkAQeNP</a></td></tr><tr><td><strong>How to use linked journey map cards</strong></td><td>The card that links one map to another and shows its details.</td><td><a href="/pages/Q15UKTZ5abMpckZ716o9">/pages/Q15UKTZ5abMpckZ716o9</a></td></tr><tr><td><strong>How to create a journey map</strong></td><td>Start a single journey map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr></tbody></table>


# How to create a hierarchy map

Gather your related journey maps into one space and link them so you can move between a high-level overview and the journeys it connects to.

A hierarchy map gathers your existing journey maps into one space, linked together so you can move between a high-level overview and the detailed journeys it connects to. Create one from the **Hierarchies** area, then add each journey map as a linked node.

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

#### Prerequisites

The journey maps you want to link already exist in this workspace (or in the Account Library). A hierarchy map connects maps you have already built; it does not create them. To make the underlying maps first, see [How to create a journey map](/journey-maps/how-to-create-a-journey-map).
{% endhint %}

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

#### Plan availability

Hierarchy maps are built from linked journey map cards, available on the **Repository** plan and above.
{% endhint %}

#### How to create a hierarchy map

{% stepper %}
{% step %}
**Open the Hierarchies area**

In the workspace sidebar, click **Hierarchies**. The list shows every hierarchy map in the workspace, or an empty state if you have not made one yet.

<figure><img src="/files/ZnzgiI7DvjhuT2tYWG3L" alt="The Hierarchies area in a workspace, with no hierarchy maps yet. A New hierarchy button sits in the top-right corner and the sidebar shows Hierarchies selected below Journey maps."><figcaption><p>[Workspace name] / Hierarchies, empty state</p></figcaption></figure>
{% endstep %}

{% step %}
**Create the hierarchy map**

Click **+ New hierarchy** in the top-right corner. There is no naming dialog. Smaply creates the hierarchy map straight away and opens it in the editor, which works like a journey map: a **Stage** lane across the top and a **Linked maps** lane below it.

<figure><img src="/files/qA3AmhvN1CKdt4XgnY76" alt="A new, empty hierarchy map open in the editor. It has a Stage lane at the top and a Linked maps lane below, where an empty cell shows an Add a linked Journey Map prompt with a Link journey map button."><figcaption><p>New hierarchy map, before any maps are linked</p></figcaption></figure>
{% endstep %}

{% step %}
**Rename it**

Click the auto-generated title in the top bar and type a name that describes the experience the hierarchy covers, for example the product or lifecycle it maps.
{% endstep %}

{% step %}
**Add your top-level map as a linked node**

In the **Linked maps** lane, click **Link journey map** on the empty-cell prompt. (You can also hover any empty cell, click **+ Add card**, and pick **Link journey map** from the picker.)

<figure><img src="/files/mt42bRZks0bEjUdE6bVV" alt="The Add card picker open on an empty cell in a hierarchy map. Link journey map is the highlighted quick-select entry at the top, followed by BASIC CARDS (Text, Image, Stage, Icons, Slider) and ADVANCED CARDS (Embed, Planning)."><figcaption><p>Add card picker, Link journey map at the top</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick the map to link**

In the **Link journey map** dialog, search the workspace's maps in the **Search or create journey map** field. Select a result to load a preview of how the linked node will appear on the right, then click **Select** to add it. Start with your highest-level map, the lifecycle or overview that anchors the structure.

<figure><img src="/files/wH8LtogHGseiAYmJcqba" alt="The Link journey map dialog with a map selected in the results list. The right pane previews the linked node showing the map name and a Healthy performance indicator. A blue Select button confirms the choice."><figcaption><p>Link journey map dialog, with a map selected to preview</p></figcaption></figure>

To link a map that does not exist yet, type its name and click **Create**. The new map opens for you to build out, then becomes available to link.
{% endstep %}

{% step %}
**Build out the hierarchy**

Repeat the link step to add the rest of your maps. Linking is flexible, so arrange them to match your experience:

* **Zoom in** - add another **Linked maps** lane (the lane's three-dot menu offers **Duplicate lane below**) and link the detailed journeys that sit under a higher-level map.
* **Link across** - add more linked maps along a lane to connect related journeys side by side, like the same stage across different channels.

The same map can be linked into more than one hierarchy, so a reusable journey like login or checkout can appear in several places.

<figure><img src="/files/hcX7pCKnFQubI0pWjwUM" alt="A built-out hierarchy map with three linked journey nodes across two Linked maps lanes. A Level 1 product map sits in the upper lane above two Level 2 maps in the lower lane, each node showing a map thumbnail, name, and Healthy performance indicator."><figcaption><p>A hierarchy map with a Level 1 map over two Level 2 sub-journeys</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Sub-journeys can come from other workspaces**

A linked node can point at a map from a different workspace through the Account Library. The row menu on a hierarchy map also offers **Copy to other workspace** and **Move to library**. See [How to use the Account Library](/account-and-team/how-to-use-the-account-library) for sharing maps across workspaces.
{% endhint %}

#### How to navigate between linked journeys

Each node carries the linked map's live details and two ways to open it without leaving the hierarchy.

Select a node and click **Preview** in its toolbar to open the linked map in an overlay. From the preview header, switch on **Full screen** for a larger read-only view, or click **Edit map** to open the linked journey in a new tab.

<figure><img src="/files/FMYZDvBzd1Esb8OaPfl6" alt="A linked journey map rendered in a preview overlay on top of the hierarchy map. The overlay header shows the map name, a Full screen toggle, and an Edit map button."><figcaption><p>Preview overlay of a linked journey map</p></figcaption></figure>

To see the node's details, click **Show card details** in the toolbar. The side panel carries the linked map's description and performance indicator, with **Preview** and **Go to journey** buttons. **Go to journey** opens the underlying map, the same destination as **Edit map** in the preview header.

<figure><img src="/files/S7HPq2gsL1LoDrREkmYk" alt="The details side panel for a linked journey node, showing the linked map&#x27;s name, description, and a Healthy performance indicator, with Preview and Go to journey buttons above the Personas, Card tags, and Comments sections."><figcaption><p>Linked journey node details, with Preview and Go to journey</p></figcaption></figure>

For the full set of fields a linked node can display and how to switch between condensed and custom layouts, see [How to use linked journey map cards](/journey-maps/cards/how-to-use-linked-journey-map-cards).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to choose between a journey map and a hierarchy map</strong></td><td>When to reach for a hierarchy map instead of a single journey map.</td><td><a href="/pages/ANYZEQ2NKtnOB6djd635">/pages/ANYZEQ2NKtnOB6djd635</a></td></tr><tr><td><strong>How to use linked journey map cards</strong></td><td>Every field a linked node can show, plus condensed and custom display settings.</td><td><a href="/pages/Q15UKTZ5abMpckZ716o9">/pages/Q15UKTZ5abMpckZ716o9</a></td></tr><tr><td><strong>How to create a journey map</strong></td><td>Build the underlying maps you link into a hierarchy.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr></tbody></table>


# Personas overview

Create and use customer personas to ground journey maps in real user archetypes

Personas represent the customer types your journey maps are about. Assign them to cards, filter journeys by persona, and keep research connected to real archetypes.

New to personas? This walkthrough covers the whole workflow, from building a persona with live data to filtering your journey maps by it.

{% embed url="<https://www.youtube.com/watch?v=sorVbcQTg5k>" %}

Prefer to read? The guides below break it down step by step.

### Build personas

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a persona</h4></td><td>Create a persona, pick template cards, and fill in the core details.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td><td><a href="/files/1TuZbdvr3NEsYrV6Pdqd">/files/1TuZbdvr3NEsYrV6Pdqd</a></td></tr><tr><td><h4>Edit a persona</h4></td><td>Change card content, the layout, the icon and colour, and the info panel.</td><td><a href="/pages/QSksmHh3bfnMcEMGSGYE">/pages/QSksmHh3bfnMcEMGSGYE</a></td><td><a href="/files/oahyRWdJxdTS1AKuXBqu">/files/oahyRWdJxdTS1AKuXBqu</a></td></tr><tr><td><h4>Manage personas</h4></td><td>Duplicate, archive, restore, delete, and bulk-edit personas from the list.</td><td><a href="/pages/oScEAxHrtqqY2twvz5kM">/pages/oScEAxHrtqqY2twvz5kM</a></td><td><a href="/files/TsiCUz7w3YzLC6YBgUIn">/files/TsiCUz7w3YzLC6YBgUIn</a></td></tr></tbody></table>

<br>

***

### Use personas on maps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Assign a persona to a card</h4></td><td>Mark which personas a card is relevant for, on any journey map.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td><td><a href="/files/2J7w3u77DuYd2gC3FnM1">/files/2J7w3u77DuYd2gC3FnM1</a></td></tr><tr><td><h4>Filter map by personas</h4></td><td>Show one persona's content at a time on a journey map.</td><td><a href="/pages/zxwopszZeIAP89VtDjFI">/pages/zxwopszZeIAP89VtDjFI</a></td><td><a href="/files/vRGOt9dTWPwjQkgLFlUJ">/files/vRGOt9dTWPwjQkgLFlUJ</a></td></tr></tbody></table>


# How to create a persona

Build a customer persona from a template, set its layout, and start filling in their story.

Build a structured profile for a customer archetype you can assign to journey map cards, use in emotion charts, and filter your maps by.

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

#### Prerequisites

You need Editor or Admin access in the workspace to create personas.
{% endhint %}

#### How to create a persona from scratch

Personas live at the workspace level. Create one from the **Personas** list in the workspace sidebar.

{% stepper %}
{% step %}
**Open Personas in your workspace**

In the workspace sidebar, click **Personas**. The list shows every persona in the workspace.

<figure><img src="/files/wW8htpMqoEsJlcridP8t" alt="The Personas list in a workspace, showing two personas named &#x27;Priya the household financial juggle&#x27; and &#x27;Andre the early-career professional&#x27;, with columns for Name, Updated, Updated by, Created, Creator, Tags, and Used in. Personas is selected in the workspace sidebar. A + Create persona button sits in the top right."><figcaption><p>Workspace > Personas</p></figcaption></figure>
{% endstep %}

{% step %}
**Click + Create persona**

In the top right, click **+ Create persona**. The **Customize persona** modal opens with a suggested name, a layout picker, and the template card checklist.

<figure><img src="/files/4JH5ln10eHiapQfyykuX" alt="The Customize persona modal with &#x27;Sofia the first-time saver&#x27; in the Name field. The Layout section shows three layout options with the first selected. Below, Template cards are listed in a two-column grid: Profile picture, Name with tagline, Needs, Channels, Journey Stage, Bio, Quote, Personality, and Goals are checked and badged Recommended; Motivations and Demographics are unchecked. A Create button sits at the bottom right."><figcaption><p>Customize persona modal</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the persona**

Type a name in the **Name** field, replacing the suggested one. A name your team will recognize reads better on a card than "Persona 1", so something like "Sofia the first-time saver" works well.
{% endstep %}

{% step %}
**Pick a layout**

Under **Layout**, choose how the persona page splits into two columns. All three are starting points; you can change the layout later from the editor.

* **Thin/Thick** - A narrow left column and a wide right column. Selected by default, and a good fit for short cards (image, name) on the left with longer-form content (bio, goals) on the right.
* **Equal/Equal** - Two columns of the same width.
* **Thick/Thin** - A wide left column and a narrow right column.
  {% endstep %}

{% step %}
**Choose your template cards**

Under **Template cards**, check the cards you want added to the new persona. The nine recommended cards are checked by default; uncheck any you don't need, or check **Motivations** and **Demographics** to include them.

See [What each template card covers](#what-each-template-card-covers) below for a description of each one.
{% endstep %}

{% step %}
**Click Create**

Click **Create** at the bottom right of the modal. Smaply opens the new persona in the full-page editor with your layout and template cards in place.
{% endstep %}

{% step %}
**Fill in the cards**

Click any card to add its content. Add a photo or avatar from the **Image** card with **Add image**, set the name and tagline on the name card (shown as "Persona Name" until you fill it in), drag the **Personality** slider, and write into **Bio**, **Quote**, and **Goals**. Changes save as you type.

Template cards aren't the only way to add content. Click **+ Quick add** in the header for more template cards, or use the card-type picker to add any supported card type: Image, Text, Slider, Icons, Embed, Metric, or Planning. See [How to edit a persona](/personas/how-to-edit-a-persona) for the full set of editing options.

<figure><img src="/files/Kb0FvMJLhf1OVMk5y1Ug" alt="The persona editor for &#x27;Sofia the first-time saver&#x27;. The header shows a colored persona icon, the name, an info icon, counters, a layout toggle, and a + Quick add button. The left column holds Image, Persona Name, Journey Stage, and Channels cards; the right column holds Bio, Quote, Personality, and Goals cards."><figcaption><p>Persona editor, ready to fill in</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" icon="compass" %}
You can also create a persona while working in a journey map. Open a card, and in its **Personas** section click **+ Create new persona**. See [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).
{% endhint %}

***

#### What each template card covers

Template cards are pre-built sections Smaply can drop into a new persona so you start with structure instead of a blank page. Nine arrive checked (badged **Recommended**); the last two are off by default.

| Template card     | What it holds                                                   | Pre-selected                        |
| ----------------- | --------------------------------------------------------------- | ----------------------------------- |
| Profile picture   | An image or avatar to humanize the persona                      | <i class="fa-check">:check:</i> Yes |
| Name with tagline | A fictional but representative name with a tagline              | <i class="fa-check">:check:</i> Yes |
| Needs             | Unmet requirements or expectations                              | <i class="fa-check">:check:</i> Yes |
| Channels          | Preferred communication or engagement platforms                 | <i class="fa-check">:check:</i> Yes |
| Journey Stage     | Current stage in the buying process                             | <i class="fa-check">:check:</i> Yes |
| Bio               | A brief story about their background, work, and lifestyle       | <i class="fa-check">:check:</i> Yes |
| Quote             | A direct quote reflecting their perspective or mindset          | <i class="fa-check">:check:</i> Yes |
| Personality       | Key traits that influence their behavior and decision-making    | <i class="fa-check">:check:</i> Yes |
| Goals             | Primary objectives they want to achieve                         | <i class="fa-check">:check:</i> Yes |
| Motivations       | What drives them to take action or make decisions               | <i class="fa-xmark">:xmark:</i> No  |
| Demographics      | Key attributes such as age, location, education, and background | <i class="fa-xmark">:xmark:</i> No  |

You don't have to settle the full set at creation. Anything you skip is one click away later from **+ Quick add** in the editor.

***

#### What happens after you create a persona

The persona lands in the workspace **Personas** list and is ready to use wherever personas appear:

* Assign it to journey map cards so each card shows which persona it applies to. See [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).
* Filter a journey map by persona to focus a map on one persona's experience. See [How to filter a journey map by persona](/personas/how-to-filter-a-journey-map-by-persona).
* Use it as a line in an emotion chart lane to plot that persona's sentiment across the journey.

***

#### 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>Assign a persona to a card</strong></td><td>Tag specific cards on a journey map with one or more personas.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>Filter a map by personas</strong></td><td>Narrow a journey map to the cards relevant to one persona at a time.</td><td><a href="/pages/zxwopszZeIAP89VtDjFI">/pages/zxwopszZeIAP89VtDjFI</a></td></tr><tr><td><strong>Create a journey map</strong></td><td>Start a new journey map with Smaply AI, from scratch, or from a template.</td><td><a href="/pages/LfyJzQKJ0Sv9rMnQYKEQ">/pages/LfyJzQKJ0Sv9rMnQYKEQ</a></td></tr></tbody></table>


# How to edit a persona

Change card content, add or remove cards, switch the layout, and set the icon, color, and details on an existing persona.

Open a persona in the full-page editor to fill in its cards, restructure its layout, set its icon and color, and keep its description and tags current as you learn more about the customer.

{% hint style="info" icon="compass" %}
If you haven't built this persona yet, start with [How to create a persona](/personas/how-to-create-a-persona). This article picks up once a persona exists.
{% endhint %}

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

#### Prerequisites

You need Editor or Admin access to edit personas.
{% endhint %}

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

#### In this guide

1. [Open a persona for editing](#open-a-persona-for-editing)
2. [Change card content](#change-card-content)
3. [Add cards](#add-cards)
4. [Remove a card](#remove-a-card)
5. [Change the layout](#change-the-layout)
6. [Set the persona icon and color](#set-the-persona-icon-and-color)
7. [Edit the description, tags, and linked maps](#edit-the-description-tags-and-linked-maps)
   {% endhint %}

#### Open a persona for editing

In the workspace sidebar, click **Personas**, then click the persona you want to edit. It opens in the full-page editor with its cards laid out across two columns.

<figure><img src="/files/Kb0FvMJLhf1OVMk5y1Ug" alt="The persona editor for &#x27;Sofia the first-time saver&#x27;. The app bar at the top right shows a download icon and a blue Share button. The persona header row below has the colored icon tile, name, and info icon on the left, with linked-map and tag counters, a layout toggle, and a Quick add button on the right. Cards are arranged in two columns: Image, Persona Name, Journey Stage, and Channels on the left; Bio, Quote, and Goals on the right."><figcaption><p>The persona editor</p></figcaption></figure>

Everything you change here saves automatically. There is no separate save step for card content, layout, or the info panel.

The top bar also has a **download** icon and a **Share** button: export the persona as a PDF, or share it with a read-only public link. See [How to share or export a persona](/sharing-and-exporting/how-to-share-or-export-a-persona).

***

#### Change card content

Click any card to edit it in place. Type into a text card, drag the handle on a slider card, swap the image on an image card, and the change saves as you go.

Persona cards use the same card model as journey map cards, so the floating toolbar, color and background options, and card details panel work the same way. For how a specific card type behaves, see the matching article under [How to add and edit cards](/journey-maps/cards/how-to-add-and-edit-cards): configuring a metric source, embedding external content, or setting up an icon card is covered there rather than repeated here.

***

#### Add cards

You can add cards two ways, depending on whether you want a ready-made section or a blank card of a specific type.

* **From the template list** - Click **+ Quick add** in the header to reopen the same template cards offered at creation (Profile picture, Bio, Goals, and so on). Search by name, tick the cards you want, and click **Add**. Nothing is pre-selected, so only what you tick is added.
* **From the card-type picker** - Add a blank card of a chosen type directly, the same way you add a card in a journey map.

<figure><img src="/files/T3mo9lCXvHlJLsnZhYDa" alt="The Quick add drawer titled &#x27;Quickly add template cards for your persona&#x27;. A &#x27;Select template cards to add&#x27; search field sits above a checklist of template cards (Profile picture, Name with tagline, Needs, Channels, Journey Stage, Bio), each marked Recommended, with empty checkboxes. An Add button is at the bottom right."><figcaption><p>+ Quick add, template cards</p></figcaption></figure>

The card-type picker groups the types available in personas:

* **Text** is the default and sits at the top of the picker.
* **Basic cards:** Image, Slider, Icons.
* **Advanced cards:** Embed, Metric, Planning.

<figure><img src="/files/NzMAUB3bDXuOVJUBwTI8" alt="The card-type picker. Text is at the top with an Enter shortcut. Under BASIC CARDS: Image, Slider, Icons. Under ADVANCED CARDS: Embed, Metric, Planning. A CUSTOM CARDS group begins below."><figcaption><p>Card-type picker, Basic and Advanced groups</p></figcaption></figure>

Stage, Portfolio item, and Linked journey cards are specific to journey maps and aren't available in personas.

***

#### Remove a card

Click the card to select it, then click the trash icon (**Delete card**) in the floating toolbar that appears above it. The card is removed straight away, with no confirmation prompt, so remove only the card you mean to.

<figure><img src="/files/RG4EzwsLkRIdsZApfNsj" alt="A selected Personality slider card with its floating toolbar above it. The toolbar&#x27;s trailing icons include a card header toggle, fill color, expand, a trash icon for Delete card, and an overflow menu."><figcaption><p>Selected card with Delete card in the toolbar</p></figcaption></figure>

***

#### Change the layout

The layout sets the relative width of the persona's two columns. Click the layout toggle in the header to open the same three options offered at creation, and pick the one that fits your cards.

<figure><img src="/files/E80TnNgM8oKOg3KrDi1O" alt="The layout toggle expanded to show three options, each a two-pane icon: a narrow-left/wide-right pane, two equal panes, and a wide-left/narrow-right pane. The first option is selected."><figcaption><p>Layout toggle, three width options</p></figcaption></figure>

The three options are a narrow-then-wide split (good for short cards on the left and longer-form content on the right), two equal columns, and a wide-then-narrow split. Switching is non-destructive: your cards stay put and only the column widths change.

***

#### Set the persona icon and color

The persona's icon, color, and name all live in one modal. This is the only place to set the icon and color; the creation modal doesn't include them.

{% stepper %}
{% step %}
**Open the Persona edit modal**

Click the colored avatar tile to the left of the persona name in the header. The **Persona edit** modal opens.
{% endstep %}

{% step %}
**Pick an icon**

Under **Image**, choose an icon from the grid. It offers solid shapes and a set of face illustrations; the selected one is framed.
{% endstep %}

{% step %}
**Pick a color**

Under **Color**, click a swatch. Your workspace **Brand colors** appear as a separate row below the standard swatches. To rename the persona at the same time, edit the name field at the top of the modal.

<figure><img src="/files/nVKf7VwPosKy4mcETtb7" alt="The Persona edit modal. At the top, the current icon tile sits next to the persona name field (&#x27;Sofia the first-time saver&#x27;). An Image section shows a grid of icon choices (shapes and face illustrations) with one framed. A Color section shows two rows of swatches with one checked, and a Brand colors row below. Cancel and Save buttons are at the bottom right."><figcaption><p>Persona edit, icon and color</p></figcaption></figure>
{% endstep %}

{% step %}
**Click Save**

Click **Save** to apply the icon, color, and name. **Cancel** closes the modal without changing anything.
{% endstep %}
{% endstepper %}

***

#### Edit the description, tags, and linked maps

Click the info icon next to the persona name to open the collapsible info panel.

<figure><img src="/files/jQzw6pJTggNnOM6UjZRP" alt="The persona info panel open, showing an editable Description field, a Tags section with an Add tag link, and a Linked journey maps list."><figcaption><p>Persona info panel</p></figcaption></figure>

It holds three things:

* **Description** - A free-text summary of the persona. Click it to edit; it saves as you type.
* **Tags** - Click **Add tag** to label the persona. Tags are searchable and filterable from the Personas list.
* **Linked journey maps** - A read-only list of the journey maps where this persona is assigned to a card. To change what's here, assign or unassign the persona on a map. See [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).

To delete the whole persona rather than a single card, use the three-dot menu on its row in the **Personas** list. That is permanent and separate from editing.

#### 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>Create a persona</strong></td><td>Start a new persona from the Customize persona modal and pick its template cards.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td></tr><tr><td><strong>Assign a persona to a card</strong></td><td>Tag specific cards on a journey map with one or more personas.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>Share or export a persona</strong></td><td>Create a read-only public link to a persona, or export it as a PDF.</td><td><a href="/pages/FJ6yN3C95BvKbdxz2fx1">/pages/FJ6yN3C95BvKbdxz2fx1</a></td></tr><tr><td><strong>Add and edit cards</strong></td><td>Card mechanics shared across journey maps and personas: the toolbar, details panel, and per-type cards.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr></tbody></table>


# How to assign a persona to a card

Tag journey map cards with the personas they apply to, so the map shows whose experience each step belongs to.

Mark which customer a card applies to by assigning one or more personas to it. Assigned personas show as small avatars on the card and let you filter the whole map down to a single persona's experience.

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

#### Prerequisites

* At least one persona in your workspace. See [How to create a persona](/personas/how-to-create-a-persona).
* Editor or Admin access to the journey map.
  {% endhint %}

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

#### In this guide

1. [How to assign a persona from the card details panel](#how-to-assign-a-persona-from-the-card-details-panel)
2. [How assigned personas appear on the card](#how-assigned-personas-appear-on-the-card)
3. [How to remove a persona from a card](#how-to-remove-a-persona-from-a-card)
4. [How to assign a persona to several cards at once](#how-to-assign-a-persona-to-several-cards-at-once)
   {% endhint %}

#### How to assign a persona from the card details panel

{% stepper %}
{% step %}
**Open the card's details panel**

Click the card, then click **Show card details** on the card toolbar. You can also double-click the card. The details panel slides in from the right.
{% endstep %}

{% step %}
**Open the Personas section**

In the panel, expand the **Personas** section and click the **Add a persona** field.

<figure><img src="/files/ZdjfRQ206DvyDSU8d3mb" alt="The card details panel with the Personas section expanded. An empty Add a persona field sits below the section heading, ready to assign the first persona."><figcaption><p>Card details > Personas</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a persona from the dropdown**

The dropdown lists every persona in the workspace, each with its colored avatar. Click the one you want to assign to the card.

<figure><img src="/files/mbuG6wuRcfA8jBaHbejB" alt="The Add a persona dropdown open, listing three workspace personas, each with a colored avatar: Priya the household financial juggler, Andre the early-career professional, and Sofia the first-time saver. A + Create new persona option sits at the bottom."><figcaption><p>Add a persona dropdown</p></figcaption></figure>

To assign more than one persona, open the field again and pick another. There's no limit on how many a card can carry. Personas already on the card drop out of the dropdown the next time you open it.

If the persona you need doesn't exist yet, click **+ Create new persona** at the bottom of the dropdown to build it without leaving the map. For the full persona setup, see [How to create a persona](/personas/how-to-create-a-persona).
{% endstep %}
{% endstepper %}

***

#### How assigned personas appear on the card

An assigned persona shows as a small colored avatar at the card's bottom-left. It sits tucked under the edge of the card at rest and expands to a full avatar when you select the card. Hover the avatar to see the persona's full name.

<figure><img src="/files/O0Nt1Yp0LAUZgqXgMitt" alt="A selected journey map card reading &#x27;Customer begins the online application process, expecting a straightforward and easy experience.&#x27; A blue persona avatar sits at the card&#x27;s bottom-left, expanded because the card is selected, with a tooltip reading &#x27;Sofia the first-time saver&#x27;."><figcaption><p>Assigned persona on a selected card</p></figcaption></figure>

When a card carries several personas, their avatars line up in a row along the bottom edge. Once cards have personas assigned, you can narrow the whole map to one persona at a time. See [How to filter a journey map by persona](/personas/how-to-filter-a-journey-map-by-persona).

***

#### How to remove a persona from a card

Open the card's details panel and expand **Personas**. Each assigned persona appears as a chip with an edit pencil and a remove **x**. Click the **x** to take the persona off the card.

<figure><img src="/files/hakSoZN8iKxwe10Ad6Qb" alt="The Personas section of a card details panel with Sofia the first-time saver assigned. Her chip shows the blue avatar, her name, an edit pencil, and a remove x. An empty Add a persona field sits below for assigning more."><figcaption><p>Personas section with one persona assigned</p></figcaption></figure>

The persona is removed from the card straight away, with no confirmation. This only un-assigns it from this card. The persona itself stays in your workspace, along with any other cards it's assigned to.

***

#### How to assign a persona to several cards at once

To assign a persona to a batch of cards in one action, select the cards first, then use the bulk toolbar.

Shift+click each card you want, or use **Select all cards** on a lane or column to grab a whole row or step. The bulk action bar appears at the bottom of the editor. Click **Persona**, then pick the persona to apply it to every selected card.

<figure><img src="/files/KhGLj3S9qW9LJpBGQ0w9" alt="The bulk action bar at the bottom of the journey map editor, labeled &#x27;Bulk edit, 3 text cards&#x27;. It shows formatting controls followed by Header, Tags, a Persona action with a person icon, and Delete."><figcaption><p>Bulk action bar with the Persona action</p></figcaption></figure>

The **Persona** action works the same way on a mixed selection of card types. For the full multi-select flow and the other bulk actions, see [How to bulk edit cards](/journey-maps/how-to-bulk-edit-cards).

***

#### 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>Filter a journey map by persona</strong></td><td>Narrow a map to the cards relevant to one persona at a time.</td><td><a href="/pages/zxwopszZeIAP89VtDjFI">/pages/zxwopszZeIAP89VtDjFI</a></td></tr><tr><td><strong>Create a persona</strong></td><td>Build a structured persona profile in your workspace so it's available to assign.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td></tr><tr><td><strong>Add and edit cards</strong></td><td>Add cards, edit them inline, and use the card details panel and toolbar.</td><td><a href="/pages/DI00pTOdaJmOwltHKgIa">/pages/DI00pTOdaJmOwltHKgIa</a></td></tr><tr><td><strong>Bulk edit cards</strong></td><td>Select multiple cards and apply tags, personas, or other changes at once.</td><td><a href="/pages/D239Y2x0Gzcz0VuWHA1p">/pages/D239Y2x0Gzcz0VuWHA1p</a></td></tr></tbody></table>


# How to filter a journey map by persona

Narrow a journey map to one or more personas so the map shows only the cards relevant to them.

Narrow a journey map to one or more personas to focus on the cards that apply to them. Useful when a map covers several customer types and you want to look at one experience (or a small group) at a time.

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

#### Prerequisites

* At least one persona in your workspace. See [How to create a persona](/personas/how-to-create-a-persona).
* At least one card on the journey map has a persona assigned. See [How to assign a persona to a card](/personas/how-to-assign-a-persona-to-a-card).
  {% endhint %}

#### How to filter by persona

{% stepper %}
{% step %}
**Open the Filter panel**

In the journey map editor, click **Filter** in the top-left of the canvas, next to **Views**.

<figure><img src="/files/qlaW3ybwoQJRSikaJgeY" alt="The journey map editor for &#x27;L1 Product: Online Account&#x27;. The Filter and Views buttons sit at the top-left of the canvas. Step-description cards show small persona avatars at their bottom edge where personas are assigned."><figcaption><p>Journey map editor > Filter</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick the Personas dimension**

In the filter panel, click **Personas**. The panel lists four filter dimensions: **Lanes**, **Personas**, **Tags**, and **Portfolio items**.

<figure><img src="/files/iXBb2t4nPW2jl6hcEiDL" alt="The filter panel open on a journey map, showing four dimensions: Lanes, Personas, Tags, and Portfolio items. Each has a chevron indicating a submenu. A Clear all option sits at the bottom of the panel."><figcaption><p>Filter panel > dimensions</p></figcaption></figure>
{% endstep %}

{% step %}
**Select one or more personas**

The **Personas** submenu lists each persona assigned to a card on this map as a checkbox, with **\[no persona set]** at the top of the list. Tick one persona or several. The matching mode is **Match any (OR)**, so cards assigned to any of the ticked personas stay visible.

<figure><img src="/files/Uo2bk6kLTqfKQgFVFJgu" alt="The Personas submenu open inside the filter panel. Checkbox options from top: [no persona set], Andre the early-career professional, Priya the household financial juggler, Sofia the first-time saver. A Match any (OR) dropdown sits below the list, with a Clear button at the bottom of the submenu."><figcaption><p>Personas submenu, options listed</p></figcaption></figure>

**\[no persona set]** is the option for cards with no persona assigned. Tick it on its own to see only those cards, or tick it alongside named personas to include both groups.
{% endstep %}

{% step %}
**Review the filtered map**

The map updates immediately. Only cards assigned to a ticked persona stay visible. Cards with no persona are hidden unless **\[no persona set]** is also ticked.

<figure><img src="/files/aMlftL55IUM1QlhmktoG" alt="The journey map filtered by &#x27;Sofia the first-time saver&#x27;. Most cells are empty; the visible Step-descriptions card reads &#x27;Customer begins the online application process, expecting a straightforward and easy experience.&#x27; The top toolbar shows a chip &#x27;Personas: Sofia the first-time saver&#x27;, a Create view link, and a Clear button. The Filter button has a badge showing &#x27;1&#x27;."><figcaption><p>Map filtered by one persona</p></figcaption></figure>

The top toolbar gains a **Clear** button and a **Create view** shortcut for saving this filter as a reusable view. The filter is reflected in the page URL, so you can bookmark the filtered view or share the link.
{% endstep %}

{% step %}
**Clear the filter when done**

You have two ways to clear:

* **Clear** at the bottom of the **Personas** submenu removes only the persona filter, leaving other dimensions in place.
* **Clear all** at the bottom of the main filter panel (or **Clear** in the top toolbar) removes every active dimension.

<figure><img src="/files/8kIGOfrcSwYUPjTG4ohm" alt="The filter panel and Personas submenu open while a filter is active. The Personas row has a &#x27;1&#x27; badge. The Sofia the first-time saver checkbox is ticked, with a Match any (OR) dropdown below. A Clear button sits at the bottom of the Personas submenu, and Clear all sits at the bottom of the main filter panel."><figcaption><p>Per-dimension Clear and Clear all</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### What happens when you select \[no persona set]

Ticking **\[no persona set]** on its own hides every card that has a persona assigned and leaves the cards without an assignment visible.

<figure><img src="/files/k84U1yH5RHGelubvlp14" alt="The journey map filtered to show only cards with no persona assigned. The stage headers (Discover &#x26; Apply, Activate &#x26; Onboard) and step headers remain, along with Pain Points and other untagged cards. Five of the six Step-descriptions cells are now empty because those cards carry personas. The Filter button has a &#x27;1&#x27; badge and the top toolbar shows a Personas chip."><figcaption><p>Map filtered to cards with no persona</p></figcaption></figure>

This is the easiest way to find cards that still need a persona assigned, or to look at content that's intentionally shared across all personas.

***

#### Save a persona view for reuse

If you'll come back to the same persona filter regularly, save it as a view. With the filter applied, click **Create view** in the top toolbar to name and save the combination. See [How to save and apply a view](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view).

***

#### Combine persona filtering with other dimensions

You can apply persona filtering on its own or alongside **Lanes**, **Tags**, or **Portfolio items**. Filters across different dimensions combine with AND, so adding a tag filter on top of a persona filter narrows the result further. For the full filter flow across all dimensions, see [How to filter a journey map](/journey-maps/filtering-and-views/how-to-filter-a-journey-map).

***

#### 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>Create a persona</strong></td><td>Build a structured persona profile in your workspace so it's available to assign and filter by.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td></tr><tr><td><strong>Assign a persona to a card</strong></td><td>Tag specific cards on a journey map with one or more personas.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>Filter a journey map</strong></td><td>Filter by lanes, tags, or portfolio items, and combine dimensions.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr><tr><td><strong>Save and apply a view</strong></td><td>Save filter combinations as named views you can re-open later.</td><td><a href="/pages/0biJxUYNUHzaN0wxgwEg">/pages/0biJxUYNUHzaN0wxgwEg</a></td></tr></tbody></table>


# How to manage personas

Sort, duplicate, share, archive, and delete personas from the workspace Personas list, one at a time or in bulk.

Everything you do to a persona after it exists lives on the **Personas** list: sort the list, make copies, share a persona across workspaces or with a public link, archive one for later, or delete it for good. Work on a single persona from its row menu, or tick several and act on them at once.

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

#### In this guide

1. [The Personas list](#the-personas-list)
2. [Duplicate a persona](#duplicate-a-persona)
3. [Add a persona to the Account Library](#add-a-persona-to-the-account-library)
4. [Archive and restore a persona](#archive-and-restore-a-persona)
5. [Delete a persona](#delete-a-persona)
6. [Act on several personas at once](#act-on-several-personas-at-once)
   {% endhint %}

#### The Personas list

Open it from **Personas** in the workspace sidebar. Each persona is a row, sorted and searchable across these columns:

* **Name** - the persona icon and name.
* **Updated** / **Updated by** - when the persona last changed and who changed it.
* **Created** / **Creator** - when it was made and who made it.
* **Tags** - any tags applied, with a **+N** indicator when there are more than fit.
* **Used in** - how many journey maps the persona is assigned to. A used persona shows a link like **1 map** that opens those maps; an unused one shows **(not used)**.

<figure><img src="/files/2ZWmm3duP8AY91NgFGUo" alt="The Personas list page in a workspace, showing three personas as rows with columns for Name, Updated, Updated by, Created, Creator, Tags, and Used in. A search icon, filter icon, and a + Create persona button sit above the table. Each row has a checkbox and a three-dot menu."><figcaption><p>Workspace sidebar > Personas</p></figcaption></figure>

Click any column heading to sort by it. Use the search and filter icons above the table to narrow a long list. Everything you can do to a single persona is in its three-dot menu at the start of the row.

<figure><img src="/files/A2KUN3kMdnKoDw9P6YHz" alt="An open three-dot row menu on the Personas list with seven actions in order: Edit, Share link (view-only), Make a copy, Add to account library, Manage tags, Move to archive, Delete."><figcaption><p>The row three-dot menu</p></figcaption></figure>

* **Edit** opens the persona in the editor. See [How to edit a persona](/personas/how-to-edit-a-persona) for changing its cards, layout, icon, and name.
* **Share link (view-only)** creates a read-only public link to the persona, with optional password protection. See [How to share or export a persona](/sharing-and-exporting/how-to-share-or-export-a-persona).
* **Make a copy** duplicates the persona in this workspace (covered below).
* **Add to account library** shares it across workspaces (covered below).
* **Manage tags** applies existing tags to the persona. To create or rename tags, see [How to create and edit tags](/account-and-team/tags/how-to-create-and-edit-tags).
* **Move to archive** sets it aside without deleting it (covered below).
* **Delete** removes it permanently (covered below).

***

#### Duplicate a persona

To copy a persona within the same workspace, open its three-dot menu and click **Make a copy**. The duplicate appears in the list as a separate persona you can rename and edit on its own. The original is untouched, and the copy carries no journey map assignments of its own.

To put the same persona in a *different* workspace, share it through the Account Library instead.

***

#### Add a persona to the Account Library

The Account Library is a shared layer that makes a persona available across every workspace in your account. From a persona's three-dot menu, click **Add to account library**. The persona stays in this workspace and becomes reusable in the others.

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

#### Plan availability

The Account Library is available on the **Framework** and **Governance** plans and activates once your account has two or more workspaces. With a single workspace, **Add to account library** has nothing to share into and won't apply.
{% endhint %}

For how shared items behave once they're in the library, see [How to use the Account Library](/account-and-team/how-to-use-the-account-library).

***

#### Archive and restore a persona

Archiving sets a persona aside without deleting it. It leaves the active list but stays fully recoverable, which makes it the safe choice when you might want the persona back.

{% stepper %}
{% step %}
**Move the persona to the archive**

On the persona's row, open the three-dot menu and click **Move to archive**. Confirm in the dialog by clicking **Yes, move to archive**.
{% endstep %}

{% step %}
**Open the Archive and switch to Personas**

Click **Archive** in the workspace sidebar. The archive opens on Journey maps by default, with a row of categories across the top. Click **Personas** to see your archived personas.

<figure><img src="/files/PkjxVzn3cLIKi5ztfCpg" alt="The workspace Archive view filtered to the Personas category. An archived persona row has its three-dot menu open, showing only three actions: Unarchive, Delete, and Add to account library."><figcaption><p>Archive > Personas</p></figcaption></figure>
{% endstep %}

{% step %}
**Restore it**

Open the archived persona's three-dot menu and click **Unarchive**. It returns to the active Personas list. An archived persona's menu only offers **Unarchive**, **Delete**, and **Add to account library**, so edit it after you've brought it back.
{% endstep %}
{% endstepper %}

***

#### Delete a persona

To remove a persona for good, open its three-dot menu and click **Delete**. The confirmation dialog (**Delete persona**) names the persona and warns that it can't be restored. Click **Yes, delete this persona permanently** to confirm, or **No, cancel** to back out.

<figure><img src="/files/pBlhLYeIfFdrpCgzybmE" alt="The Delete persona confirmation dialog. It asks &#x27;Are you sure you want to delete this persona permanently?&#x27;, shows the persona name in bold, and a yellow warning reads &#x27;We will not be able to restore your persona after you delete it.&#x27; Buttons: No, cancel and Yes, delete this persona permanently."><figcaption><p>Delete persona confirmation</p></figcaption></figure>

{% hint style="danger" %}

#### **Warning: Deleting a persona is permanent and un-assigns it from every card**

There's no recovery. If the persona is assigned to cards in any journey map, deleting it silently removes that assignment from every card. The cards themselves stay in place and no notification appears on the affected maps. To keep the persona instead, use **Move to archive**.
{% endhint %}

***

#### Act on several personas at once

Tick the checkbox on two or more rows to bring up the bulk action bar, headed **Bulk edit · N items**. Close it with the **X** to clear your selection.

<figure><img src="/files/htC9L5KGsYBSkOhZFUfr" alt="The bulk action bar shown after selecting two personas. It reads &#x27;Bulk edit 2 items&#x27; with a close control, then four actions: Add to account library, Remove from account library (greyed out), Archive, and Delete."><figcaption><p>Bulk action bar, two personas selected</p></figcaption></figure>

The bar applies one action to the whole selection:

* **Add to account library** - shares all selected personas across workspaces (same plan and workspace requirement as the single-persona action above).
* **Remove from account library** - takes them back out of the library. It's greyed out unless the selection is already in the library.
* **Archive** - moves them all to the archive, where you can restore them later.
* **Delete** - removes them all permanently, with the same consequence as deleting one: any card assignments are silently dropped and can't be recovered.

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to create a persona</strong></td><td>Add a new persona from the list and fill its cards.</td><td><a href="/pages/q92JEZ67HauDof23i4mL">/pages/q92JEZ67HauDof23i4mL</a></td></tr><tr><td><strong>How to edit a persona</strong></td><td>Change a persona's cards, layout, icon, and name in the editor.</td><td><a href="/pages/QSksmHh3bfnMcEMGSGYE">/pages/QSksmHh3bfnMcEMGSGYE</a></td></tr><tr><td><strong>How to assign a persona to a card</strong></td><td>Attach personas to journey map cards, one or several at a time.</td><td><a href="/pages/42b6nVolnvr4VE3kfJ6s">/pages/42b6nVolnvr4VE3kfJ6s</a></td></tr><tr><td><strong>How to share or export a persona</strong></td><td>Create a read-only public link to a persona, or export it as a PDF.</td><td><a href="/pages/FJ6yN3C95BvKbdxz2fx1">/pages/FJ6yN3C95BvKbdxz2fx1</a></td></tr><tr><td><strong>How to use the Account Library</strong></td><td>Share and manage content across all workspaces in your account.</td><td><a href="/pages/1xJR8wxOSmPbsGgxwtjR">/pages/1xJR8wxOSmPbsGgxwtjR</a></td></tr></tbody></table>


# Portfolio overview

Track and prioritize pain points, opportunities, solutions, and custom-typed items across your workspace

Portfolio items are native Smaply objects (pain points, opportunities, solutions, or custom types) that live at the workspace level. Items naturally appear across multiple journey maps when you add them as cards, and editing once updates everywhere.

### Create and connect

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create a portfolio item</h4></td><td>Create pain points, opportunities, solutions, or custom-typed items.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td><td><a href="/files/mIO9OPAryn3Tn3CJ82yj">/files/mIO9OPAryn3Tn3CJ82yj</a></td></tr><tr><td><h4>Portfolio item cards</h4></td><td>Place a portfolio item as a card on a journey map.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td><td><a href="/files/oWFRfSjbUPDGKBJZEBgb">/files/oWFRfSjbUPDGKBJZEBgb</a></td></tr><tr><td><h4>Link portfolio items</h4></td><td>Connect items to express relationships, like a pain point to its solution.</td><td><a href="/pages/iDGXQS6w1CP6Vkc7j5BA">/pages/iDGXQS6w1CP6Vkc7j5BA</a></td><td><a href="/files/kD4Sko4X2X1br2KAYEI3">/files/kD4Sko4X2X1br2KAYEI3</a></td></tr><tr><td><h4>Custom item types</h4></td><td>Define your own item types beyond the built-in three, with custom scores.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</a></td><td><a href="/files/t5388mtoioyshjKsErKh">/files/t5388mtoioyshjKsErKh</a></td></tr></tbody></table>

<br>

***

### Prioritize

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Portfolio summary</h4></td><td>The dashboard that lands when you open the Portfolio menu.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td><td><a href="/files/RbS900fZgIeFwkxE0AgH">/files/RbS900fZgIeFwkxE0AgH</a></td></tr><tr><td><h4>Prioritization views</h4></td><td>Chart, table, and board views for ranking and managing items.</td><td><a href="/pages/y3sLp2nzfYnc9diekVpU">/pages/y3sLp2nzfYnc9diekVpU</a></td><td><a href="/files/Viy0dFfzXwvW3rubRbsj">/files/Viy0dFfzXwvW3rubRbsj</a></td></tr><tr><td><h4>Export to CSV</h4></td><td>Export the portfolio table for offline analysis.</td><td><a href="/pages/EWpdFIYYJJJqGy3W0gDt">/pages/EWpdFIYYJJJqGy3W0gDt</a></td><td><a href="/files/SCbEE63YEsuJEvHD5FMr">/files/SCbEE63YEsuJEvHD5FMr</a></td></tr></tbody></table>

<br>

***

### Research and evidence

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Add findings to portfolio</h4></td><td>Promote research insights into portfolio items, with quotes carried as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td><td><a href="/files/Q1ODCqrvKq4GFdDwUbW8">/files/Q1ODCqrvKq4GFdDwUbW8</a></td></tr><tr><td><h4>Add evidence</h4></td><td>Back an item with quotes, feedback, and source links, by hand or from research.</td><td><a href="/pages/M7pLmvLqe5OLNTD1V9B1">/pages/M7pLmvLqe5OLNTD1V9B1</a></td><td><a href="/files/RlHkJQ3mPZRLYBSc0DeR">/files/RlHkJQ3mPZRLYBSc0DeR</a></td></tr><tr><td><h4>Review insights and quotes</h4></td><td>Refine the insights and quotes in an investigation before they become evidence.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td><td><a href="/files/RLqx8vqXhiQhuGOa3vAO">/files/RLqx8vqXhiQhuGOa3vAO</a></td></tr></tbody></table>


# How to create a portfolio item

Create pain points, opportunities, solutions, or custom-typed items in your portfolio and reuse them across journey maps.

Capture a pain point, opportunity, solution, or any custom type once, then score it, prioritize it, and reuse it across every journey map in your workspace.

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

#### Prerequisites

You need Editor or Admin access in the workspace to create portfolio items. Viewers can open the portfolio but can't add to it.
{% endhint %}

You can also create a portfolio item without opening the Portfolio area at all, directly from a card on a journey map. See [How to use portfolio item cards](/journey-maps/cards/how-to-use-portfolio-item-cards) for that path.

#### How to create a portfolio item

There are two places to start a new item in the Portfolio area:

* **From a type card on the Summary** - Each type has its own card on the Portfolio Summary with a **Create \[type]** link in its footer, such as **Create solution** or **Create pain point**. Use this when you already know the type.
* **From any view's toolbar** - Open the Table, Board, or Chart view and click the blue **+ Create new** button. You pick the type as part of the create flow.

Both open the same create modal. The steps below start from a type card.

{% stepper %}
{% step %}
**Open the Portfolio area**

In the workspace sidebar, click **Portfolio**. It opens on the **Summary**, a dashboard with one card per item type: **Opportunity**, **Pain point**, **Solution**, and any custom type your account has added.

<figure><img src="/files/ldQOIZ0EKKZn60tARYKt" alt="The Smaply workspace sidebar with Portfolio selected, showing the Portfolio Summary dashboard. Each item type has its own card: Opportunity, Pain point, Solution, and a custom Goals type, each showing a total count, a Created sparkline, and Assignee, Status, and Priority breakdowns."><figcaption><p>Portfolio Summary, one card per item type</p></figcaption></figure>
{% endstep %}

{% step %}
**Start a new item**

On the card for the type you want, click **Create \[type]** in the footer, for example **Create solution**. The create modal opens on the **Details** tab.

<figure><img src="/files/vdicKD6XEDR24iDWRJ50" alt="The footer of a portfolio type card showing a Create solution link on the left and an Explore all link on the right."><figcaption><p>The Create link sits in each type card's footer</p></figcaption></figure>
{% endstep %}

{% step %}
**Name and describe the item**

**Name** pre-fills with "New \[type]"; replace it with something specific. Add detail in the **Description** field, which supports bold, font sizes, and bulleted lists.

<figure><img src="/files/djvTZmTaJu7o0uyQRAI2" alt="The Create solution modal open on the Details tab, empty. The left column has Name (pre-filled New solution) and a rich-text Description field. The right column has Priority set to None, Status set to No status, an Assignee selector, a Solution Tags field, and a Score section with Impact, Feasibility, and Reach dot ratings."><figcaption><p>Create solution, Details tab</p></figcaption></figure>
{% endstep %}

{% step %}
**Score and classify the item**

Fill in the right-hand fields to make the item findable and sortable later:

* **Priority** - **High**, **Medium**, **Low**, or **None** (the default).
* **Status** - the values depend on the type. A Solution offers **No status**, **Research**, **Discarded**, **Design**, **Development**, and **Done**.
* **Assignee** - the workspace member responsible, from **Select a user**.
* **Tags** - a type-specific field (for a solution, **Solution Tags**). Click **+ Add** to apply one.
* **Score** - rate each dimension on the five-dot scale or type a value in the box beside it. This workspace uses **Impact**, **Feasibility**, and **Reach**; an admin can rename these dimensions, so yours may differ.

<figure><img src="/files/MePNFulr3GYPD0NegzEO" alt="The Create solution modal with all Details fields filled: Name Auto-save application progress, a Description, Priority High, Status Development, and Score ratings of Impact 90, Feasibility 70, and Reach 30 shown as filled dots with matching numeric boxes."><figcaption><p>A completed item before saving</p></figcaption></figure>
{% endstep %}

{% step %}
**Save the item**

Click **Save**. The item joins its type on the Summary and appears in every view, where you can prioritize it alongside the rest of your portfolio.
{% endstep %}
{% endstepper %}

#### What happens after you save

A portfolio item is not tied to the journey map or view you created it from. The same item can sit on many maps at once, and editing it updates every instance everywhere it appears in the workspace. So a solution you create here can be dropped onto several journeys, and a later change to its status or score is reflected on all of them.

Items of a custom type are created exactly the same way: open the type's card on the Summary and click its **Create \[type]** link, or use **+ Create new** and pick the type. To define a new type with its own labels, statuses, and scoring dimensions before you can create items in it, see [How to create custom portfolio item types](/portfolio/how-to-create-custom-portfolio-item-types).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Portfolio summary</strong></td><td>The dashboard that loads when you open Portfolio, and the way into the prioritization views.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr><tr><td><strong>Custom item types</strong></td><td>Define a new portfolio type with its own labels, statuses, and scoring dimensions.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</a></td></tr><tr><td><strong>Prioritize in the chart</strong></td><td>Plot items as bubbles on configurable scoring axes for workshop-style prioritization.</td><td><a href="/pages/Bvvajkxb89h2CT9fR2mF">/pages/Bvvajkxb89h2CT9fR2mF</a></td></tr><tr><td><strong>Portfolio item cards</strong></td><td>Add an existing portfolio item as a card on a journey map.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td></tr><tr><td><strong>Add evidence</strong></td><td>Back an item with quotes and research from the Evidence tab.</td><td><a href="/pages/M7pLmvLqe5OLNTD1V9B1">/pages/M7pLmvLqe5OLNTD1V9B1</a></td></tr></tbody></table>


# How to use the portfolio summary

See every portfolio item's volume, status, priority, and ownership at a glance, then jump straight into prioritization.

The Summary is the first thing you see when you open Portfolio: one card per item type, each showing how many items you have, who owns them, and where they sit on status and priority. From here you move into the prioritization views to work item by item.

#### How to open the portfolio summary

Click **Portfolio** in the workspace sidebar to open the **Summary**.

<figure><img src="/files/ldQOIZ0EKKZn60tARYKt" alt="A Smaply workspace with Portfolio selected in the left sidebar. The Summary dashboard fills the page as a grid of cards, one per portfolio item type: Opportunity, Pain point, Solution, and Goals. A View details link sits at the top."><figcaption><p>Portfolio selected in the sidebar, showing the Summary</p></figcaption></figure>

The Summary shows one card per item type in the workspace: the three built-in types (Opportunity, Pain point, Solution) plus any custom type your account has added, like Goals. It covers every portfolio item across all journey maps in the workspace, not just the ones on a single map.

***

#### What each type card shows

Each card is a read-at-a-glance breakdown of one item type. The header gives you the type name and the total count, with a line below it telling you how many items changed in the past 30 days, so you can spot whether a type is active or stale.

<figure><img src="/files/OnpePzeN2DcGEfo5TI9j" alt="Close-up of the Opportunity card on the portfolio Summary. The header shows the Opportunity name and a total count of 8, with 8 updated in the past 30 days below it. A Created bar chart spans Jan to Jun. An Assignee breakdown lists Smaply Team. A Status breakdown groups items into Not Started, In Progress, and Completed. A Priority breakdown lists None, Low, Medium, and High. Create opportunity and Explore all links sit in the footer."><figcaption><p>One type card: counts, creation trend, and breakdowns</p></figcaption></figure>

Below the header, four breakdowns answer the questions you usually open the portfolio to ask:

* **Created** - A monthly bar chart of when items of this type were added over the past six months, so you can see whether the type is growing or went quiet.
* **Assignee** - Who owns the items, with a count each. Use it to check workload and spot unassigned work.
* **Status** - Items grouped into **Not Started**, **In Progress**, and **Completed**, for a quick read on how far along the type is. Each type can have its own named statuses, which roll up into these three categories.
* **Priority** - Items split across **None**, **Low**, **Medium**, and **High**, so you can see how much high-priority work is outstanding.

Each breakdown segment is clickable: selecting one, like an assignee's name or the **High** priority bar, opens the prioritization views filtered to that selection.

The footer has two links: **Create \[type]** (for example, **Create opportunity**) opens the create modal for that type, and **Explore all** opens the prioritization views filtered to that type.

***

#### How to move into the prioritization views

The Summary is for scanning. To work item by item, open the prioritization views, where the same items appear in three layouts you switch between.

* **View details** in the breadcrumb header opens the views with everything included.
* **Explore all** on any type card opens the same views filtered to that one type.

Both land you on the same screen, where a switcher in the top-right toolbar moves between the three views:

* [How to use the portfolio table](/portfolio/prioritization/how-to-use-the-portfolio-table) - Every item in a sortable, filterable list for detailed review.
* [How to use the portfolio kanban](/portfolio/prioritization/how-to-use-the-portfolio-kanban) - Items in status-based columns (the Board view) for tracking workflow.
* [How to use the portfolio chart](/portfolio/prioritization/how-to-use-the-portfolio-chart) - Items plotted as bubbles on scoring dimensions for workshop-style prioritization.

To return to the dashboard, click **Back to summary** in the breadcrumb.

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Create a portfolio item</strong></td><td>Add an item from the Summary or any view and fill in its details.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>Portfolio table</strong></td><td>Review every item in a sortable, filterable list.</td><td><a href="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</a></td></tr><tr><td><strong>Portfolio kanban</strong></td><td>Track items through status-based columns.</td><td><a href="/pages/2QH7fPzYbtiQHUcNCPiK">/pages/2QH7fPzYbtiQHUcNCPiK</a></td></tr><tr><td><strong>Portfolio chart</strong></td><td>Plot items on scoring dimensions for prioritization.</td><td><a href="/pages/Bvvajkxb89h2CT9fR2mF">/pages/Bvvajkxb89h2CT9fR2mF</a></td></tr><tr><td><strong>Custom item types</strong></td><td>Add your own portfolio item types beyond the defaults.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</a></td></tr></tbody></table>


# Portfolio prioritization

Chart, table, and kanban views of your portfolio for prioritization work. Toggle between them and filter to focus on the items that matter.

Prioritization is where you act on your portfolio items. From the Portfolio summary, drill into the prioritization view of your choice. All three views share the same filters; pick whichever matches the kind of decision you're making.

Watch how to turn pain points and opportunities into prioritized, trackable work across the chart, table, and kanban views.

{% embed url="<https://www.youtube.com/watch?v=k1Qt2a24OE4>" %}

#### Why use the prioritization views

* Compare items side by side and decide what to tackle first, instead of scanning a flat list
* Switch between chart, table, and kanban without losing your filters or context

#### In this section

* [**Chart**](/portfolio/prioritization/how-to-use-the-portfolio-chart) - Map items on configurable axes for comparative prioritization (impact vs effort, value vs risk, etc.).
* [**Table**](/portfolio/prioritization/how-to-use-the-portfolio-table) - Tabular view with filtering and sorting for detailed item-by-item review.
* [**Kanban**](/portfolio/prioritization/how-to-use-the-portfolio-kanban) - Status-based columns for managing item workflow (Planned).


# How to use the portfolio chart

See your whole portfolio prioritized at a glance, with the highest-impact, most-feasible items grouped together.

The **Chart** view plots every portfolio item as a bubble on your score dimensions, so the work that scores high on both axes lands in one corner and the rest sorts itself out around it. It's built for workshop-style prioritization.

#### How to open the Chart

The Chart is one of three views (**Table**, **Board**, **Chart**) that share the portfolio views screen. The screen remembers the view you used last, so you may land on the Chart already.

{% stepper %}
{% step %}
**Open the portfolio views screen**

Click **Portfolio** in the workspace sidebar to open the Summary, then click **View details** in the header or **Explore all** on any type card.
{% endstep %}

{% step %}
**Switch to the Chart**

In the **Table / Board / Chart** switcher at the top right of the toolbar, click **Chart**.

<figure><img src="/files/QBCriV6UcoqJuzJkjf6F" alt="The portfolio view switcher, a segmented control with Chart selected and labelled, and Table and Board as icon-only toggles."><figcaption><p>Table / Board / Chart switcher, Chart active</p></figcaption></figure>
{% endstep %}
{% endstepper %}

#### How to read the chart

Each bubble is one portfolio item. Three things encode its scores:

* **Position** - the two axes are your first two score dimensions. In the example below they're **HIGH IMPACT** (vertical) and **HIGH FEASIBILITY** (horizontal), so an item sitting top-right scores high on both and is a strong candidate to prioritize. Your axis labels depend on the score dimensions your workspace uses.
* **Colour** - by default, the bubble's colour is its item type, keyed by the legend across the top: **Opportunity** blue, **Pain point** red, **Solution** green, and any custom types your workspace has added (here, **Goals** in yellow). You can recolour by status or priority instead, covered below.
* **Size** - the bubble's size is a third score dimension, so a large bubble scores higher on that dimension than a small one.

<figure><img src="/files/xWOWemGbGD49FnMPVAg9" alt="The portfolio Chart view. Bubbles of different colours and sizes are plotted against a vertical HIGH IMPACT axis and a horizontal HIGH FEASIBILITY axis, each labelled with its item name. A legend across the top maps colours to types: Opportunity blue, Pain point red, Solution green, Goals yellow."><figcaption><p>The Chart view, with bubbles plotted by score</p></figcaption></figure>

Where bubbles overlap, they stack and each keeps its name label, so a cluster in one corner stays readable.

#### How to adjust the display and filter the chart

Two controls on the toolbar change what the chart shows.

**Settings** opens the **Display settings** dropdown. **Color represents** sets what the bubble colours mean: **Card type** (the default, matching the legend), **Status category**, or **Priority**. Switch it to colour the same bubbles by where items stand or how urgent they are, without changing their positions. **Show labels on chart** toggles the item-name labels on or off, which is useful when a dense chart gets crowded.

<figure><img src="/files/1vuZnEAL7NpmV9xDsT6H" alt="The Display settings dropdown open from the Settings button. It shows Color represents set to Card type, and a Show labels on chart toggle switched on."><figcaption><p>Settings > Display settings</p></figcaption></figure>

<figure><img src="/files/FwAeIIwe4wF06pnagHwF" alt="The Display settings menu with the Color represents submenu expanded, listing Card type, Status category, and Priority, with Card type selected."><figcaption><p>Color represents: Card type, Status category, or Priority</p></figcaption></figure>

The axes themselves are fixed to your first two score dimensions and are not reconfigurable from the chart.

The filter icon narrows the chart to a subset of items by **Journey map**, **Type**, **Status**, **Priority**, **Assignee**, and more. Filters combine, so you can focus a workshop on, say, high-priority pain points for a single journey map. To pull the same data into a spreadsheet, switch to the Table view and export from there. See [How to export portfolio to CSV](/portfolio/how-to-export-portfolio-to-csv).

#### 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 the portfolio table</strong></td><td>Review items row by row, with filtering, sorting, and CSV export.</td><td><a href="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</a></td></tr><tr><td><strong>How to use the portfolio board</strong></td><td>Manage items through status columns on the Board view.</td><td><a href="/pages/2QH7fPzYbtiQHUcNCPiK">/pages/2QH7fPzYbtiQHUcNCPiK</a></td></tr><tr><td><strong>How to use the portfolio summary</strong></td><td>Scan volume, status, and ownership across every item type.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr><tr><td><strong>How to create a portfolio item</strong></td><td>Add a pain point, opportunity, solution, or custom-type item.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr></tbody></table>


# How to use the portfolio table

Review every portfolio item in your workspace side by side, then filter and sort to the slice you care about.

The **Table** lists every portfolio item in your workspace in one place, with scores, status, priority, and usage in columns you can sort and filter. Use it to compare items side by side and narrow down to the ones you want to act on.

#### How to open the Table

The Table is one of three views on the prioritization screen, alongside [Board](/portfolio/prioritization/how-to-use-the-portfolio-kanban) and [Chart](/portfolio/prioritization/how-to-use-the-portfolio-chart). Open it from the [Portfolio summary](/portfolio/how-to-use-the-portfolio-summary) in either of two ways:

* **View details** in the summary header opens the views screen.
* **Explore all** on any type card does the same, scoped to that type.

The views screen remembers the last view you used. If it opens on Board or Chart, click **Table** in the **Table / Board / Chart** switcher at the top right of the toolbar.

<figure><img src="/files/NQAegGkMJZSwxacI55gh" alt="The Table / Board / Chart view switcher. Table is selected and shows a text label; Board and Chart are icon-only."><figcaption><p>The view switcher, top right of the toolbar</p></figcaption></figure>

***

#### Reading the columns

Each row is one portfolio item. The first column shows its **Name** with a type icon, so you can tell opportunities, pain points, solutions, and any custom types apart at a glance.

<figure><img src="/files/7LvGHa4GJoDCpP2QC5Vh" alt="The portfolio Table with 24 items in rows. Columns run from Name, through a SCORES group of three dimensions, Used in, a LINKS group, Status, Priority, Tags, and Updated. A 24 results count sits at the top left."><figcaption><p>The portfolio Table, populated</p></figcaption></figure>

Two column groups sit under shared headers:

* **SCORES** holds the three scoring dimensions for your items, shown here as Impact, Feasibility, and Reach. These names are set by an admin, so yours may read differently. The defaults are Impact, Reach, and Cost.
* **LINKS** breaks down how many other portfolio items each item is linked to, counted by type. Linking expresses relationships such as a pain point connected to the solution that addresses it. See [How to link portfolio items](/portfolio/how-to-link-portfolio-items).

**Used in** counts the journey maps that contain the item. It is clickable, which is how you find every map an item appears on without opening the item first. The remaining columns, **Status**, **Priority**, **Tags**, and **Updated**, hold the same values you set when you create or edit an item.

***

#### How to filter and sort the list

Click the filter icon in the toolbar to narrow the list. Each dimension expands to its own set of values, so you can combine filters, for example High priority items of one type that are still in progress.

<figure><img src="/files/6nvm4Plcqzn20DNYoaPn" alt="The filter menu open over the table, listing Journey map, Type, Status, Status category, Priority, Assignee, Tags, Updated, and Content source, each with a submenu arrow, and a Clear all option at the bottom."><figcaption><p>Filter dimensions</p></figcaption></figure>

You can filter by **Journey map**, **Type**, **Status**, **Status category**, **Priority**, **Assignee**, **Tags**, **Updated**, and **Content source**. Each one expands to a checklist of its values, so you tick the ones you want.

<figure><img src="/files/lTymRJiGu4aR23etJtuQ" alt="The table filter menu with the Status dimension expanded into a checklist of status values such as No status, Research, Not Started, Discarded, Design, Development, In Progress, Done, and Canceled."><figcaption><p>A filter dimension expanded to its values</p></figcaption></figure>

**Clear all** removes every filter at once. The result count at the top left updates as you go, so a filtered list reading "24 results" tells you how many items match.

To sort, click a column header. Sorting and filtering work together, so you can sort a filtered list, for example the highest-impact items assigned to one person.

***

#### How to choose which columns show

Click **Settings** in the toolbar to open **Display columns**, then toggle any of **Scores**, **Used in**, **Links**, **Status**, **Priority**, **Tags**, and **Updated**. Turn off the columns you do not need to focus the table on the ones you are comparing.

<figure><img src="/files/1uoTd07Fp98hTHeSspjm" alt="The Display columns menu open from Settings, with checkboxes for Scores, Used in, Links, Status, Priority, Tags, and Updated, all selected."><figcaption><p>Settings > Display columns</p></figcaption></figure>

#### How to export the table to CSV

The download icon on the toolbar, to the right of the view switcher, exports the list to a CSV file. Any filters you have applied carry through, so you can export the whole portfolio or just the slice you have narrowed to. For the full export flow, see [How to export portfolio to CSV](/portfolio/how-to-export-portfolio-to-csv).

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Use the portfolio chart</strong></td><td>Plot items on configurable axes for workshop-style prioritization.</td><td><a href="/pages/Bvvajkxb89h2CT9fR2mF">/pages/Bvvajkxb89h2CT9fR2mF</a></td></tr><tr><td><strong>Use the portfolio board</strong></td><td>Manage items in status-based columns.</td><td><a href="/pages/2QH7fPzYbtiQHUcNCPiK">/pages/2QH7fPzYbtiQHUcNCPiK</a></td></tr><tr><td><strong>Use the portfolio summary</strong></td><td>Scan volume, activity, and status across all item types.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr><tr><td><strong>Export portfolio to CSV</strong></td><td>Export the portfolio, or a filtered subset, for offline analysis.</td><td><a href="/pages/EWpdFIYYJJJqGy3W0gDt">/pages/EWpdFIYYJJJqGy3W0gDt</a></td></tr></tbody></table>


# How to use the portfolio kanban

Lay your portfolio out in columns by status, priority, assignee, or tag category, and drag items between them to move them along.

The Board view is Smaply's kanban board for your portfolio: it lays every item out in columns so you can see your work by where it stands. It groups by status out of the box, you can drag a card from one column to another to move it along, and you can switch the grouping to priority, assignee, or tag category whenever a different cut is more useful.

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

#### Prerequisites

Anyone in the workspace can open and read the Board. Moving cards (which changes the field the board is grouped by) needs Editor access at the workspace level.
{% endhint %}

#### How to open the Board view

The Board lives on the portfolio views screen, alongside the Table and Chart views. The Portfolio menu opens on the Summary dashboard first, so you get there in two moves.

{% stepper %}
{% step %}
**Open the portfolio views screen**

Click **Portfolio** in the workspace sidebar to open the Summary, then click **View details** in the header (or **Explore all** on any type card). Both open the views screen.
{% endstep %}

{% step %}
**Switch to the Board**

In the **Table / Board / Chart** switcher at the top right, click **Board**.

<figure><img src="/files/yqEwfjFlF3hDxMksoOyO" alt="The portfolio view switcher, a segmented control with Board selected and labelled, and Table and Chart as icon-only toggles."><figcaption><p>The Table / Board / Chart switcher, Board active</p></figcaption></figure>

The screen remembers the last view you used, so the next time you open the portfolio it lands here.
{% endstep %}
{% endstepper %}

***

#### What the columns mean

By default the Board groups items by status, and each column is a status category: **Not Started**, **In Progress**, **Completed**, and **No status** for items whose status hasn't been set. Each column header carries a live count and a `...` menu, and cards show the item's type icon and title.

<figure><img src="/files/wtoIBRQLZdzgoWwynhzc" alt="The portfolio Board view with four columns: Not Started (4 items), In Progress (17 items), Completed (2 items), and No status (1 item). Each card shows a type icon and a title, and each column header shows a count and a three-dot menu."><figcaption><p>Portfolio Board, grouped by status category</p></figcaption></figure>

The categories are fixed, but the individual statuses underneath them are not. Each portfolio item type defines its own statuses, and each maps to one of these categories. A type's statuses might run Research, Design, Development, and Done, for example, where Research and Design count as In Progress and Done counts as Completed. That is why two cards in the same column can show different underlying statuses. To change which statuses a type has and how they group, see [How to create custom portfolio item types](/portfolio/how-to-create-custom-portfolio-item-types).

***

#### How to group the board by priority, assignee, or tag category

Status is only the default. Open **Settings** (the **Display settings** menu) and pick a different dimension under **Group columns by** to lay the same items out a different way:

* **Status** - delivery stage (the default).
* **Priority** - High, Medium, Low, and None columns, to see how much high-priority work is outstanding.
* **Assignee** - one column per owner, to balance and review workload.
* **Tag category** - columns from one of your tag categories.

<figure><img src="/files/DnX58Qg1NcenFe8ImqtF" alt="The Board Display settings menu open with the Group columns by submenu expanded, listing Status, Priority, Assignee, and Tag category. Status is selected."><figcaption><p>Display settings > Group columns by</p></figcaption></figure>

For example, grouping by priority replaces the status columns with High, Medium, Low, and None, so the board becomes a priority backlog you can rebalance at a glance.

<figure><img src="/files/Jjo93FyQmHJGHcBOjWqc" alt="The portfolio Board regrouped by priority, with columns High, Medium, Low, and None, each holding portfolio item cards."><figcaption><p>The same board, grouped by Priority</p></figcaption></figure>

The same **Display settings** menu also sets **Card display options** (Compact or Standard) and a **Show empty columns** toggle.

***

#### How to move an item

Drag a card from one column to another to move it. The board updates the field it is grouped by to match the new column, so dragging a card to a different column changes its status when grouped by status, its priority when grouped by priority, and so on. The columns re-count as you go.

To set a value precisely, or to change several fields at once, open the item instead.

{% stepper %}
{% step %}
**Open the item**

Click the item's card to open it. The edit modal opens on the **Details** tab.
{% endstep %}

{% step %}
**Change the field and save**

Pick a new value from the **Status** dropdown (or **Priority**, **Assignee**, or **Tags** to match how the board is grouped), then click **Save**. The board re-sorts the item into its new column.
{% endstep %}
{% endstepper %}

***

#### How to filter the board

Click the filter icon in the toolbar to narrow the board to a subset of items. The same dimensions are available as on the Table view, so you can focus on one journey map, type, priority, assignee, or tag. The column counts update to reflect what's left after filtering.

#### 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 the portfolio table</strong></td><td>Review items row by row with filtering and sorting.</td><td><a href="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</a></td></tr><tr><td><strong>How to use the portfolio chart</strong></td><td>Plot items on scoring axes for workshop-style prioritization.</td><td><a href="/pages/Bvvajkxb89h2CT9fR2mF">/pages/Bvvajkxb89h2CT9fR2mF</a></td></tr><tr><td><strong>How to use the portfolio summary</strong></td><td>Scan volume, activity, and status across every item type.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr><tr><td><strong>How to create custom portfolio item types</strong></td><td>Define the statuses and scoring each type uses.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</a></td></tr></tbody></table>


# How to create custom portfolio item types

Define your own portfolio item types, with their own scoring and statuses, so the portfolio fits how your team works.

Beyond the built-in pain points, opportunities, and solutions, you can define your own portfolio item types with their own icon, scoring, and statuses. Set one up once at the account level and it works on every journey map, exactly like the built-in types.

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

#### Prerequisites

You're an Admin at the account level. Custom types live in Account Settings, which only Admins can open.
{% endhint %}

#### Where custom item types live

Custom types are managed in **Account Settings > Customization**, on the **Custom cards** sub-tab. The list shows every type in your account: the built-in **Opportunity**, **Pain point**, and **Solution** (which you can edit but not delete), plus any custom types you've added.

<figure><img src="/files/h2c2xiuQO936kBLu6sTW" alt="The Customization tab in Account settings with the Custom cards sub-tab open. A list shows Opportunity, Pain point, Solution, and a custom Goals type, each with an Edit link. A + New custom card button sits below the list, with a 4 of 8 used counter to its right."><figcaption><p>Account Settings > Customization > Custom cards</p></figcaption></figure>

{% hint style="info" %}
An account can have up to 8 portfolio item types in total: the 3 built-in types plus up to 5 custom ones. The **N of 8 used** counter next to **+ New custom card** tracks how many you've used.
{% endhint %}

***

#### How to create a custom card type

Each custom type carries the same example through the steps below: a **Risk** type for tracking risks across journeys.

{% stepper %}
{% step %}
**Open the new card dialog**

Click **+ New custom card**. A full-page dialog opens with the type's settings.

<figure><img src="/files/JQzMKDL440izn7Hem2jE" alt="The New custom card full-page dialog, empty. A Custom card details section has an Icon picker and a Name field. A Field customization section lists Description (checked), Statuses, Scores, Assignee, and Priority. A Settings section has an Enable linking toggle, switched on. The Save button at the top right is disabled."><figcaption><p>New custom card, empty</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the type and pick an icon**

Under **Custom card details**, enter a **Name** (here, *Risk*) and choose an **Icon**. The icon and color are how the type appears on cards, in the views, and in the chart legend. **Save** stays disabled until the type has a name.
{% endstep %}

{% step %}
**Choose which fields the type has**

Under **Field customization**, turn on the fields this type should carry. **Description** is on by default; **Statuses** and **Scores** are off until you turn them on. **Assignee** and **Priority** are marked **Auto-populated**, so they work without any setup. Leave **Enable linking** on under **Settings** if you want items of this type to link to other items.

<figure><img src="/files/0m7z6NzLgfJSlO2CfXvK" alt="The New custom card dialog with Name set to Risk and Description, Statuses, and Scores all checked in the Field customization list. Each checked field shows a blue Customize link. The Save button is now active."><figcaption><p>New custom card, Risk with fields selected</p></figcaption></figure>
{% endstep %}

{% step %}
**Customize the scoring model**

Next to **Scores**, click **Customize**. A type has three score dimensions, labelled **A**, **B**, and **C**, each with a name you can edit and each scored from 1 to 100. The names are yours to set; this example uses *Impact*, *Feasibility*, and *Potential*.

These three dimensions drive the prioritization chart: **A** is the vertical axis, **B** is the horizontal axis, and **C** is the bubble size. Click **Save** to return to the type.

<figure><img src="/files/7iKddXKdWRalwXDgmN80" alt="The Customize scores dialog with three editable label fields A, B, and C set to Impact, Feasibility, and Potential. A Prioritization chart explained panel below shows A as the vertical axis, B as the horizontal axis, and C as the circle size."><figcaption><p>Customize scores</p></figcaption></figure>
{% endstep %}

{% step %}
**Customize the statuses**

Next to **Statuses**, click **Customize**. Statuses sit in three fixed categories: **Not Started**, **In Progress**, and **Done**. To add, rename, reorder, or delete the individual statuses inside a category, click **Add / edit statuses** on that row.

<figure><img src="/files/pgQ5l6aEhaF2MsvO1K29" alt="The Customize statuses dialog showing three category rows: Not Started, In Progress, and Done. Each row lists its current statuses and an Add / edit statuses link. The Done category contains two statuses, Done and Canceled."><figcaption><p>Customize statuses</p></figcaption></figure>

In **Edit Statuses**, drag the handle to reorder a status, edit its name in place, or use the trash icon to remove it. **Add status** adds a new one to the category. Click **Save** to return.

<figure><img src="/files/mkbT6kCxaQ2sCrWJJmEZ" alt="The Edit Statuses dialog for the Not Started category. A single status row shows a drag handle, a color dot, an editable name field reading Not Started, and a delete icon. An Add status link sits below it, with Cancel and Save buttons."><figcaption><p>Edit Statuses, Not Started category</p></figcaption></figure>
{% endstep %}

{% step %}
**Save the type**

Click **Save** in the dialog header. The type appears in the **Custom cards** list and the **N of 8 used** counter goes up by one. Anyone in your workspaces can now create items of this type, and add them to journey maps as cards, the same way they would an opportunity or a pain point.
{% endstep %}
{% endstepper %}

***

#### How to edit a type or rename a score dimension

To change a type later, click **Edit** on its row in the **Custom cards** list. The same dialog opens, and you can rename the type, swap its icon, toggle fields, or reopen **Customize scores** and **Customize statuses**.

Two behaviours are worth knowing before you edit a type that already has items:

* Renaming a score dimension takes effect immediately, on every existing item of that type and every card that displays them.
* Structural changes, like adding or removing a field such as a status or a score, apply to existing items as well as new ones. Content does not backfill, though: if you add a default description, items created before the change keep their own.

#### How to delete a custom card type

Deleting a type removes far more than the type itself, so do this only when you're sure no items of that type are still needed.

To delete, click the trash icon on the type's row. The built-in types cannot be deleted, so the icon is only active on custom types. A **Confirm deletion** dialog explains what will happen.

<figure><img src="/files/sQmjWmvT5HuDOgVDOwNQ" alt="The Confirm deletion dialog for the Risk type. A warning explains that deleting the Risk custom card type will delete all Risk items from journey maps and the account, and that connected cards will be shown as an error on the maps where they are used. The dialog asks Are you sure you want to continue, with No, go back and a red Delete button."><figcaption><p>Confirm deletion</p></figcaption></figure>

{% hint style="danger" %}

#### **Warning: Deleting a type deletes every item of that type**

Confirming removes every item of the type from your account and your journey maps. Any card that showed one of those items is left in an error state on the maps where it was used. Click **No, go back** to keep the type; click **Delete** only if you want this cascade.
{% endhint %}

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Create a portfolio item</strong></td><td>Add an item of any type, including your custom types, from the Portfolio area.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>Use the portfolio chart</strong></td><td>Read items as bubbles positioned by the score dimensions you set here.</td><td><a href="/pages/Bvvajkxb89h2CT9fR2mF">/pages/Bvvajkxb89h2CT9fR2mF</a></td></tr><tr><td><strong>Use the portfolio table</strong></td><td>Sort, filter, and export your items across every type.</td><td><a href="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</a></td></tr><tr><td><strong>Link portfolio items</strong></td><td>Connect items to each other, like a pain point to its solution.</td><td><a href="/pages/iDGXQS6w1CP6Vkc7j5BA">/pages/iDGXQS6w1CP6Vkc7j5BA</a></td></tr><tr><td><strong>Add evidence to a portfolio item</strong></td><td>Back an item with research quotes and manually entered evidence.</td><td><a href="/pages/M7pLmvLqe5OLNTD1V9B1">/pages/M7pLmvLqe5OLNTD1V9B1</a></td></tr></tbody></table>


# How to link portfolio items

Connect related portfolio items, like a pain point to the solution that addresses it, so your team can see how challenges and responses fit together.

To link portfolio items, open one, go to its **Linked items** tab, and add the items you want to connect it to. Links work in both directions, so you only make them once.

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

#### Plan availability

Linking portfolio items is available on the **Governance** plan.
{% endhint %}

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

#### Prerequisites

* An Editor or Admin role on the workspace
* At least one other portfolio item to link to
  {% endhint %}

#### How to link one portfolio item to another

{% stepper %}
{% step %}
**Open the portfolio item**

From the **Portfolio**, open an item from the **Table** view, or click a portfolio item card on a journey map. The item opens in its edit modal.
{% endstep %}

{% step %}
**Open the Linked items tab and click + Add linked items**

Select **Linked items**, then **+ Add linked items**. The **Explore links to** view opens, with one column for each portfolio item type in your workspace.

<figure><img src="/files/oTkeiy3PX9zpMBtdSkX4" alt="The Explore links to view for a portfolio item, with a column for each portfolio item type in the workspace and a plus button on each column to add a linked item."><figcaption><p>Explore links to, one column per item type</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a type and search for the item**

Click **+** on the column for the type you want to link, for example **Solutions**. In the panel that opens, search for the item, or click **Create** to make a new one inline. Narrow the list with the **All**, **Current map**, and **Created by you** filters.

<figure><img src="/files/oFFKpsOyA8MidqBxQX0T" alt="A panel titled Add solution, with a search field, All / Current map / Created by you filters, a list of matching items each with a relevance label, and a Select button."><figcaption><p>Search for an item to link, or create one</p></figcaption></figure>
{% endstep %}

{% step %}
**Select the item**

Check the item you want and click **Select**. It joins that column. Add as many links as you need, then close the view.
{% endstep %}

{% step %}
**Review the link**

Back on the **Linked items** tab, the linked item appears grouped under its type with a progress bar. Click it to preview its full details in a side panel.

<figure><img src="/files/JdHtrXrHfSf0JRvO26Na" alt="A portfolio item&#x27;s Linked items tab showing one linked solution grouped under its type heading with a progress bar."><figcaption><p>The linked item on the Linked items tab</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### How links work

* **Any type to any type** - Link a pain point to an opportunity, an opportunity to a solution, or any other combination. Links are not limited to a fixed pain point to opportunity to solution sequence.
* **Both directions at once** - A link you add from one item shows on the other item too. You do not create it twice.
* **No limit** - Link an item to as many others as you need.
* **Status at a glance** - Each linked item carries its status, shown by colour (for example green for done, blue for in progress), with a progress bar per type so you can read how a cluster of work is tracking.

Linking is different from the same item appearing on more than one journey map, which happens on its own and is not a link. For that, see [How to use portfolio item cards](/journey-maps/cards/how-to-use-portfolio-item-cards). To back an item with quotes and sources rather than connect it to other items, see [How to add evidence to a portfolio item](/portfolio/how-to-add-evidence).

***

#### How to remove a link

Open the **Linked items** tab and click **Edit linked items** to reopen the **Explore links to** view. Find the linked item and turn its selection off. The link is removed from both items right away, and neither item is otherwise changed.

***

#### How to see links across your portfolio

The **Table** view in the portfolio prioritization views has a **Links** column showing how many links each item has, so you can spot well-connected items and gaps at a glance. See [How to use the portfolio table](/portfolio/prioritization/how-to-use-the-portfolio-table).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to add evidence to a portfolio item</strong></td><td>Back an item with quotes, feedback, and source links.</td><td><a href="/pages/M7pLmvLqe5OLNTD1V9B1">/pages/M7pLmvLqe5OLNTD1V9B1</a></td></tr><tr><td><strong>How to create a portfolio item</strong></td><td>Create pain points, opportunities, solutions, and custom-typed items.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>How to use portfolio item cards</strong></td><td>Place a portfolio item as a card on a journey map.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td></tr><tr><td><strong>How to add findings to portfolio</strong></td><td>Promote research insights into portfolio items, with quotes carried as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td></tr></tbody></table>


# 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="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. [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) view, or Cmd-click (Mac) / Ctrl-click (Windows) cards in the [Board](/portfolio/prioritization/how-to-use-the-portfolio-kanban) view. A bulk-action bar appears at the bottom with **Tags**, **Add to account library**, **Add to journey map**, and **Delete**. Click **Add to journey map**.

<figure><img src="/files/d0SZ8AgQ0ZjHBU4u9WFa" alt="A bulk-action bar reading 2 of 27 items selected, with Tags, 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="/files/uKGcPlgbx48YN5cgncPV" alt="A Bulk edit bar reading Bulk edit 3 items, with Add to portfolio (greyed out), 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, the flow first walks you through promoting it, the same guided flow as [How to add findings to portfolio](/research-hub/how-to-add-findings-to-portfolio#how-to-place-each-insight-in-the-portfolio): pick a type, match to an existing item, or skip it, for each insight. Insights already promoted skip straight past this step.
{% 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 grouped at the top under **Most relevant** and tagged accordingly. Search by name, pick a map, and click **Continue**.

<figure><img src="/files/HFUhj4K5vJ3wbOq8jEXo" alt="The Select a journey map screen with a search field and a Most relevant group of maps, each showing a title, description, owner, and last-updated date."><figcaption><p>Select a journey map</p></figcaption></figure>

Smaply AI then works out where each item best fits, shown as a progress screen while it processes.

***

#### How to place the items and confirm

You 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="/files/N6hlKFPJlGXrh2UAo6F6" 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="/files/d1nncZzTHJRAIPx8rYsd" alt="The Add to selector open, listing New lane, Journey Stages &#x26; Steps, and Opportunity as destination options."><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.
{% 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 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="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</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="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</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="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</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="/pages/iDGXQS6w1CP6Vkc7j5BA">/pages/iDGXQS6w1CP6Vkc7j5BA</a></td></tr></tbody></table>


# How to add evidence to a portfolio item

Back a portfolio item with evidence by adding quotes, feedback, and source links by hand, or by promoting findings from research.

To add evidence to a portfolio item, open it, go to the **Evidence** tab, and click **+ Add** to record a quote, a piece of feedback, or a link to a source. Quotes promoted from research land on the same tab.

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

#### Prerequisites

You need a portfolio item to add evidence to, and an Editor or Admin role on the workspace.
{% endhint %}

#### How to add evidence by hand

{% stepper %}
{% step %}
**Open the portfolio item and go to the Evidence tab**

Open the item from the **Portfolio** or from a portfolio item card on a journey map, then select the **Evidence** tab.
{% endstep %}

{% step %}
**Click + Add**

A blank **Evidence item** form opens on the tab.

<figure><img src="/files/rXrnKwNaukrl6RA5J0zx" alt="A blank evidence form on the Evidence tab, with a Details text box, a Type dropdown, three sentiment buttons, an Evidence date field, and a Source link field."><figcaption><p>The manual evidence form</p></figcaption></figure>
{% endstep %}

{% step %}
**Fill in the evidence**

Enter the **Details** (the quote or note) and pick a **Type**: **Quote**, **Feedback**, or **Other**. Type and Details are required. Optionally set the **Sentiment** (positive, neutral, or negative), an **Evidence date**, and a **Source link** back to where the evidence came from.

<figure><img src="/files/QeBIBo3mX77Q4nwl13RT" alt="The Type dropdown on the evidence form open, showing the options Quote, Feedback, and Other."><figcaption><p>Choosing the evidence type</p></figcaption></figure>
{% endstep %}

{% step %}
**Save the evidence**

Click **Add evidence**. The entry appears on the **Evidence** tab, grouped by type, with a coloured edge that matches its sentiment.

<figure><img src="/files/Rfmhtz5dmb6rYuVqHpSB" alt="The Evidence tab with one saved entry grouped under its type heading, showing a coloured left edge matching its sentiment."><figcaption><p>A saved piece of evidence on the Evidence tab</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### How to add evidence from research

You do not have to enter every piece of evidence by hand. When you promote an insight from a Research Hub investigation, its quotes are attached to the portfolio item's **Evidence** tab automatically, each one traceable back to its source transcript. Select a research quote on the tab to open its source with the quote highlighted, and use **Unlink quote** there to detach it without changing the original.

<figure><img src="/files/MxBnJctia0DMd506W04E" alt="The Evidence tab of a portfolio item promoted from research, listing quotes on the left and the full source transcript on the right with a link back to the investigation."><figcaption><p>Evidence carried over from a research investigation</p></figcaption></figure>

For the full flow of promoting insights and tracing them back to their source, see [How to add findings to portfolio](/research-hub/how-to-add-findings-to-portfolio).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to add findings to portfolio</strong></td><td>Promote research insights into portfolio items, with quotes carried as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td></tr><tr><td><strong>How to create a portfolio item</strong></td><td>Create pain points, opportunities, solutions, and custom-typed items.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>How to link portfolio items</strong></td><td>Connect related items, like a pain point to its solution.</td><td><a href="/pages/iDGXQS6w1CP6Vkc7j5BA">/pages/iDGXQS6w1CP6Vkc7j5BA</a></td></tr><tr><td><strong>How to review insights and quotes</strong></td><td>Refine insights and quotes in an investigation before promoting them.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td></tr></tbody></table>


# How to export portfolio to CSV

Export the portfolio table, or a filtered subset, as a CSV file for offline analysis or sharing outside Smaply.

Pull your whole portfolio, or just the slice you've filtered to, into a CSV you can open in a spreadsheet or share outside Smaply. The export lives in the **Table** view, the one place the portfolio leaves Smaply as data rather than a PDF.

#### How to export the portfolio

{% stepper %}
{% step %}
**Open the Table view**

From the Portfolio **Summary**, click **View details** (or **Explore all** on a type card), then select **Table** in the **Table / Board / Chart** switcher. The Table lists every portfolio item in the workspace. For filtering and column choices, see [How to use the portfolio table](/portfolio/prioritization/how-to-use-the-portfolio-table).
{% endstep %}

{% step %}
**Download the CSV**

Click the **download** icon on the toolbar, to the right of the view switcher. The CSV downloads straight away, with no further dialog.

<figure><img src="/files/0IxAtO22LFMI9OAzPdhv" alt="The right side of the portfolio Table toolbar showing a Settings button, the Table / Board / Chart view switcher with Table active, a download icon, and a + Create new button. The download icon exports the table as CSV."><figcaption><p>The download icon exports the Table as CSV</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Filters carry through to the export**

Any filters you've applied in the Table carry into the CSV, so you can export the whole portfolio or only the slice you've narrowed to. Narrow the Table first, then download.
{% endhint %}

The Table is the only view that exports; the Board and Chart views have no export of their own. To share a journey map itself rather than the portfolio data, see [How to export a journey map as PDF](/sharing-and-exporting/how-to-export-a-journey-map-as-pdf).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Use the portfolio table</strong></td><td>Filter, sort, and choose columns before you export.</td><td><a href="/pages/Mz77ioM4nJgfxggwyXja">/pages/Mz77ioM4nJgfxggwyXja</a></td></tr><tr><td><strong>Portfolio summary</strong></td><td>The dashboard you open Portfolio on, and the way into the Table.</td><td><a href="/pages/abuTV30fMWJUfseHuf1v">/pages/abuTV30fMWJUfseHuf1v</a></td></tr><tr><td><strong>Export a journey map as PDF</strong></td><td>Export the map itself, with branding, instead of the portfolio data.</td><td><a href="/pages/bFw8ZAfXKB40zpzNx0GL">/pages/bFw8ZAfXKB40zpzNx0GL</a></td></tr><tr><td><strong>Create a portfolio item</strong></td><td>Add pain points, opportunities, solutions, or custom-type items.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr></tbody></table>


# How to import portfolio items from CSV

Bring portfolio items in from a CSV file, mapping columns to fields and choosing whether each row updates an existing item or creates a new one.

Import a CSV of pain points, opportunities, solutions, or other portfolio items instead of adding them one by one. Map each column to a portfolio item field, then choose whether a row updates an existing item or creates a new one.

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

#### Prerequisites

Editor or Admin role at the workspace level. \[VERIFY]
{% endhint %}

{% stepper %}
{% step %}
**Start the import**

\[VERIFY: exact entry point, likely an Import action from the Portfolio Table or Summary, alongside the existing CSV export.]
{% endstep %}

{% step %}
**Upload your CSV**

\[VERIFY: file requirements, for example a header row, encoding, and any size or row-count limit.]
{% endstep %}

{% step %}
**Map columns to fields**

Match each column in your file to a portfolio item field, for example **Title**, **Description**, **Type**, **Scores**, **Status**, **Priority**, **Assignee**, and **Tags**. \[VERIFY: exact field list, which fields are required, and whether unmatched columns are skipped or rejected.]
{% endstep %}

{% step %}
**Choose update or create per row**

\[VERIFY: how a row is matched to an existing item, for example by an ID column or by name, and what happens to a row that doesn't match, whether it creates a new item automatically or needs a choice like the Research Hub's promote-to-portfolio flow.]
{% endstep %}

{% step %}
**Confirm and import**

\[VERIFY: whether there's a preview or summary before committing, and what confirmation the reader sees afterward.]
{% endstep %}
{% endstepper %}

{% hint style="warning" %}

#### **Important: Confirm whether this can create duplicates**

\[VERIFY: if a row doesn't match an existing item cleanly, confirm whether it's safe to import more than once without creating duplicate items, similar to the no-duplicate-detection behaviour on "Add to journey map".]
{% 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 export portfolio to CSV</strong></td><td>The reverse direction: export the portfolio table as a CSV file.</td><td><a href="/pages/EWpdFIYYJJJqGy3W0gDt">/pages/EWpdFIYYJJJqGy3W0gDt</a></td></tr><tr><td><strong>How to create a portfolio item</strong></td><td>Add a single pain point, opportunity, solution, or custom-typed item by hand.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>How to create custom portfolio item types</strong></td><td>Define the types and fields a CSV import would map columns to.</td><td><a href="/pages/v2QYLoJduQKY2uguPORV">/pages/v2QYLoJduQKY2uguPORV</a></td></tr></tbody></table>


# Research Hub overview

Run AI-assisted investigations on research files, review insights and quotes, and promote findings to portfolio

Research Hub turns raw research into reusable insights. Create an investigation with your files, let Smaply AI extract quotes and sentiment automatically, review and refine the findings, then promote the best insights to portfolio items so they can land on journey maps.

### Run an investigation

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create an investigation</h4></td><td>Start an investigation and upload research files; AI runs automatically once files are added.</td><td><a href="/pages/bYRXhV15DwXPFxORlX4I">/pages/bYRXhV15DwXPFxORlX4I</a></td><td><a href="/files/JLCeQ3iCPY7X8esdkLos">/files/JLCeQ3iCPY7X8esdkLos</a></td></tr><tr><td><h4>Review insights and quotes</h4></td><td>Review what AI extracted, then edit, add, and delete findings to refine them.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td><td><a href="/files/RLqx8vqXhiQhuGOa3vAO">/files/RLqx8vqXhiQhuGOa3vAO</a></td></tr><tr><td><h4>Add findings to portfolio</h4></td><td>Promote selected insights and quotes into portfolio items your team can prioritize.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td><td><a href="/files/Q1ODCqrvKq4GFdDwUbW8">/files/Q1ODCqrvKq4GFdDwUbW8</a></td></tr></tbody></table>


# How to create an investigation

Upload transcripts or import CSV and Excel feedback data, and let AI extract quotes, sentiment, and insights you can act on.

An investigation is a research session that groups your source files and the insights Smaply draws from them, keeping the evidence behind each finding linked to the journeys it affects.

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

#### Plan availability

Creating an investigation runs AI analysis, which is available on the **Repository** plan and above. Your account also needs Research Hub AI switched on. See [How to configure AI features](/account-and-team/how-to-configure-ai-features).
{% endhint %}

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

#### Prerequisites

Editor or Admin role at the workspace level. Viewers can't create investigations.
{% endhint %}

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

#### In this guide

1. [Create the investigation](#create-the-investigation)
2. [How to map spreadsheet columns](#how-to-map-spreadsheet-columns)
3. [What the AI does automatically](#what-the-ai-does-automatically)
4. [Explore your findings](#explore-your-findings)
5. [Manage investigations from the list](#manage-investigations-from-the-list)
   {% endhint %}

#### Create the investigation

Start from the **Research** item in the workspace sidebar. The investigation list opens with **+ Create investigation** in the top-right corner.

<figure><img src="/files/T8SAFHMnQdSPZPdWgaJt" alt="The Research landing in an empty state. A flask icon sits above the heading &#x27;Turn research into actionable insights&#x27; with the line &#x27;Upload files to extract insights and link evidence to your journeys&#x27;. A blue Create investigation button is in the top-right corner."><figcaption><p>Research, empty state</p></figcaption></figure>

Click **+ Create investigation**. The **Select your evidence source** screen opens with two cards, **Text file** and **Spreadsheet**. Each card also lists tools you can export straight from, like Zoom or Qualtrics, as a shortcut into a tailored guide for that tool.

<figure><img src="/files/p8A9kleiY1w5mXUB4BRR" alt="The Select your evidence source screen with two cards. The Text file card lists .txt, plain text or transcript, with export shortcuts for Microsoft Teams, Zoom, and Youtube. The Spreadsheet card lists .csv, rows and columns, with export shortcuts for Qualtrics, Dovetail, Medallia, Zendesk, Intercom, and Trustpilot."><figcaption><p>Select your evidence source</p></figcaption></figure>

Pick a source, or one of the tool shortcuts under it. Either way you land on a short prep guide and a drop zone for that source:

* [**Text file**](#text-file) - One or more transcripts as `.txt` files. Covers Microsoft Teams, Zoom, and Youtube exports.
* [**Spreadsheet**](#spreadsheet) - A single CSV or Excel file of structured feedback, with an extra step to confirm which columns to import. Covers Qualtrics, Dovetail, Medallia, Zendesk, Intercom, and Trustpilot exports.

{% tabs %}
{% tab title="Text file" %}
{% stepper %}
{% step %}
**Add your transcript files**

Click **Upload files** or drag your files onto the drop zone. Each file appears under **Uploaded files** with a remove control, and you can add more than one. Use the X next to a file to drop it before analyzing.

<figure><img src="/files/HFo5ghThEznDclMiaAPS" alt="The upload screen with six transcripts queued under the heading &#x27;Uploaded files (6)&#x27;, each row showing a document icon, the .txt filename, and an X remove control. The Upload and analyze button is active at the bottom right."><figcaption><p>Six transcripts queued for analysis</p></figcaption></figure>
{% endstep %}

{% step %}
**Click Upload and analyze**

Once at least one file is queued, **Upload and analyze** turns active. Click it to start. Smaply scans your files first (**Scanning your files**), then asks you to name the session: type a descriptive name in the **Name your research session** dialog and click **Continue**.

<figure><img src="/files/kTCYO9YFehCQthmA0AA1" alt="The &#x27;Name your research session&#x27; dialog with the subtitle &#x27;Add a descriptive name for this research session&#x27;. A text field reads &#x27;Account opening - spreadsheet vs transcript check&#x27; with an active Continue button beside it."><figcaption><p>Name your research session</p></figcaption></figure>
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Spreadsheet" %}
{% stepper %}
{% step %}
**Add your file**

Click **Choose a file** or drag a single CSV or Excel file onto the drop zone. Unlike the text file path, this takes one file at a time.

<figure><img src="/files/HHnvkyTI84O0XygOv3Ql" alt="The Spreadsheet upload screen with account-opening-survey-responses.csv queued under Uploaded files (1) and an active Continue button at the bottom right."><figcaption><p>A CSV file queued for import</p></figcaption></figure>
{% endstep %}

{% step %}
**Click Continue, then map your columns**

Confirm which column holds your feedback text and which are metadata (see [How to map spreadsheet columns](#how-to-map-spreadsheet-columns) below), then click **Import**. Spreadsheet investigations skip the naming step and the security scan: Smaply names the session automatically, for example "Research Sat 08 Aug morning", and you can rename it afterwards from the investigation list.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### How to map spreadsheet columns

After you click **Continue** on a spreadsheet upload, the **Confirm what to import and analyse** screen shows a preview of your file with one column already picked as the **Quote column**, the text Smaply will analyze, and up to four more picked as **Metadata**, extra context carried alongside each quote. Smaply auto-maps columns for you, so most spreadsheets need no changes here.

<figure><img src="/files/IEYMyqGkeujpPmhxBG3Z" alt="The Confirm what to import and analyse screen. Quote column and Metadata cards sit above a 5-row preview table with a role badge on each column header: date and channel are Metadata, score is Skip, feedback is Quote. A SKIPPED (1) chip sits below the table, with an Import 10 quotes button at the bottom right."><figcaption><p>Confirm what to import and analyse</p></figcaption></figure>

To adjust a column's role, click its dropdown in the preview table and choose **Quote**, **Metadata**, or **Skip**. A skipped column greys out and moves to the **SKIPPED** count below the table.

<figure><img src="/files/zkh6Ef4pRq1KiftWYH1l" alt="An open column role menu on the date column header, showing three options: Quote, Metadata, and Skip."><figcaption><p>Change a column's role from its header dropdown</p></figcaption></figure>

To add a metadata column back, click **+ Add** on the Metadata card and pick it from the unassigned columns.

<figure><img src="/files/RW1XFY51JR1gR7U8bsiT" alt="The Metadata card showing 2 of 4 columns with date and channel chips, and an open Add menu listing score as an available column to add."><figcaption><p>Add an unassigned column as metadata</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: You can't change the mapping after you import**

Review the column roles here before clicking **Import**. If you need a different mapping, upload the file again into a new investigation.
{% endhint %}

Click **Import**, labelled with your quote count (for example **Import 10 quotes**), to start analysis.

***

Whichever source you used, Smaply now works through your files. The **Analyzing your files** checklist tracks progress through **Extracting key data points**, **Cross-referencing patterns**, and **Generating insights**. Keep the tab open until it completes.

<figure><img src="/files/fXzki5IJ1gbD5FOf7rUq" alt="The &#x27;Analyzing your files&#x27; screen with a progress bar and a three-item checklist: Extracting key data points (Complete), Cross-referencing patterns (Complete), and Generating insights (in progress)."><figcaption><p>Analyzing your files</p></figcaption></figure>

{% hint style="success" icon="lightbulb" %}

#### **Tip: Get your sources right before you analyze**

You can't add files to an investigation after it's created, and the AI analysis can't be re-run on it. To analyze a different set of sources, create a new investigation. To work with more transcripts or a different spreadsheet, gather everything before you click **Upload and analyze** or **Import**.
{% endhint %}

***

#### What the AI does automatically

Once you start the analysis, Smaply works through your sources without any further input. It extracts direct quotes (from your **Quote column**, if you imported a spreadsheet), detects the sentiment behind each one (positive, neutral, or negative), cross-references recurring patterns, and groups them into insights.

When it finishes, the **Research summary** shows what came out of your sources: how many files were analyzed, how many quotes were extracted, how many insights were found, and the sentiment breakdown across all quotes.

<figure><img src="/files/OXdyoBEmYg5lYeEk5CDQ" alt="The Research summary dialog. A Summary row shows 6 Sources analyzed, 155 Quotes extracted, and 47 Insights found. A Sentiment row shows 50 Positive, 16 Neutral, and 89 Negative. An Explore findings button sits below."><figcaption><p>Research summary</p></figcaption></figure>

Every quote, sentiment value, and insight is a starting point you can edit, so the summary is where AI hands the work back to you.

***

#### Explore your findings

Click **Explore findings** on the summary to open the session view. This is where you read, refine, and curate everything the analysis produced: a **Sources** panel with your source files and their quotes on the left, and an **Insights** list in the center.

<figure><img src="/files/XGdFJSRCAbMPQ9C9VBBW" alt="The investigation session view. The left Sources panel lists the six transcripts; the center Insights panel lists generated insights with category labels and sentiment counts; a detail panel on the right shows a selected insight&#x27;s quotes and summary."><figcaption><p>Investigation session view</p></figcaption></figure>

A source expands differently depending on where it came from. A transcript expands into the full text with quotes highlighted. A spreadsheet expands into a table, one row per response, with your feedback column and any metadata columns alongside it.

<figure><img src="/files/q880mkaKbvkzMfqRg374" alt="An expanded CSV source shown as a table with columns for row number, feedback, and date. Feedback text has sentiment-highlighted spans in green and red."><figcaption><p>A spreadsheet source, expanded as a table</p></figcaption></figure>

From here, your next steps are reviewing the findings and promoting the strongest ones into your portfolio.

<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>Review insights and quotes</strong></td><td>Edit insights, refine sentiment, add or remove quotes, and work with your sources.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td></tr><tr><td><strong>Add findings to portfolio</strong></td><td>Promote selected insights and their quotes into portfolio items as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td></tr></tbody></table>

***

#### Manage investigations from the list

Every investigation you create appears in the **Research** list, with columns for **Name**, **Created By**, **Created**, **Updated**, **Sources** (file count), and **Insights** (insight and quote counts). Click any column header to sort.

<figure><img src="/files/RsdjcO2o7Hq1vHgX5e61" alt="The Research list with one investigation row showing it was created by the workspace team, with 6 files under Sources and &#x27;47 insights, 155 quotes&#x27; under Insights. Search, filter, and Create investigation controls sit in the top-right."><figcaption><p>Research list with one investigation</p></figcaption></figure>

To reopen the session view for an existing investigation, click the three-dot menu on its row and select **View Analysis**. The same menu has **Delete**, which removes the whole investigation.

<figure><img src="/files/0dX8o4UGj3GA8GQExmGz" alt="A row&#x27;s three-dot menu open on the Research list, showing two items: View Analysis and Delete."><figcaption><p>Research list, row menu</p></figcaption></figure>

Use the search and filter icons next to **+ Create investigation** to narrow a long list. The filter groups results by **File Type** (**CSV (.csv)** or **Text (.txt)**), **File Count**, **Created By**, **Status**, and **Created**, with **Clear all** to reset.

<figure><img src="/files/Zv0J4hc6tOTSggt433JK" alt="The Research list filter panel with File Type expanded, showing two checkboxes: CSV (.csv) and Text (.txt)."><figcaption><p>Filter the list by File Type</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>Review insights and quotes</strong></td><td>Work through the session view: edit insights, refine sentiment, and manage your sources.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td></tr><tr><td><strong>Add findings to portfolio</strong></td><td>Turn research insights into portfolio items, with quotes carried over as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td></tr><tr><td><strong>Configure AI features</strong></td><td>Switch Research Hub AI and other AI features on or off at the account level.</td><td><a href="/pages/DiKcSh4fYbbEx5TUJBBU">/pages/DiKcSh4fYbbEx5TUJBBU</a></td></tr></tbody></table>


# How to review insights and quotes

Review, refine, and edit the quotes and insights Smaply's AI pulled from your research transcripts, all in the investigation session view.

After Smaply analyzes your transcripts, the session view is where you check its work: read the quotes it highlighted, correct their sentiment, edit or add insights, and decide what carries forward into your portfolio. Every AI suggestion is yours to keep, change, or remove.

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

#### Plan availability

Research Hub AI is available on Smaply's paid plans (**Repository** and above). On the **Free** plan there are no AI-extracted quotes or insights to review.
{% endhint %}

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

#### Prerequisites

You have an investigation that has finished analyzing. If you haven't created one yet, see [How to create an investigation](/research-hub/how-to-create-an-investigation).
{% endhint %}

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

#### In this guide

1. [Open the session view](#open-the-session-view)
2. [Review and refine quotes](#review-and-refine-quotes)
3. [Review and edit insights](#review-and-edit-insights)
4. [Edit several insights at once](#edit-several-insights-at-once)
   {% endhint %}

#### Open the session view

From the **Research** list, open the three-dot menu on your investigation's row and select **View Analysis**. (Right after analysis finishes, **Explore findings** takes you to the same place.)

<figure><img src="/files/XGdFJSRCAbMPQ9C9VBBW" alt="Investigation session view with three panels: a Sources list on the left, an Insights list in the center, and an insight detail panel below. The header shows the investigation name and counters for Sources, Quotes, and Insights."><figcaption><p>The session view: Sources on the left, Insights in the center, the detail panel for a selected insight</p></figcaption></figure>

The session view has two working panels plus a detail panel that opens when you select an insight:

* **Sources** (left) - your uploaded transcripts and the quotes pulled from each.
* **Insights** (center) - every insight the analysis generated, grouped by category.
* **Insight details** - opens below the panels when you click an insight, where you edit its name, summary, and linked quotes.

The header carries the investigation name, running counts of **Sources**, **Quotes**, and **Insights**, and an **Exit session** button to return to the list.

***

#### Review and refine quotes

Quotes live inside the transcripts in the **Sources** panel. The top of the panel shows the sentiment split across the whole investigation; each source lists its filename, quote count, and its own positive, neutral, and negative counts.

<figure><img src="/files/PQBn7cuWScUOvdUxqcdk" alt="Sources panel showing an aggregate sentiment summary at the top and six transcript files below, each with a quote count and a breakdown of positive, neutral, and negative sentiment counts."><figcaption><p>Sources panel, with aggregate and per-source sentiment</p></figcaption></figure>

Click a source to expand its transcript. AI-extracted quotes appear as colored highlights in the text: green for positive sentiment, pink for negative. Hover a highlight to see the AI-generated summary of that quote.

<figure><img src="/files/TssXmyZoK0fujOVcg2Ff" alt="An expanded transcript in the Sources panel. Passages of the interview are highlighted in green and pink, marking the quotes the AI extracted and the sentiment it assigned to each."><figcaption><p>An expanded transcript with positive (green) and negative (pink) quote highlights</p></figcaption></figure>

You can adjust any quote directly in the transcript:

* **Change its sentiment** - switch the highlight color (green for positive, pink for negative; a neutral face marks a neutral quote).
* **Remove a quote** - deselect its highlight so the text is no longer marked as a quote.
* **Add a quote** - highlight any passage of transcript text that the AI missed.
* **Link a quote to an insight** - drag the highlight into an insight in the center panel.

***

#### Review and edit insights

The **Insights** panel lists every insight from the analysis. The count next to the heading is the total; the category tabs across the top let you filter to one category at a time. The full set is **All**, **Pain**, **Gain**, **Need**, **Expectation**, **Emotion**, **Workaround**, **Barrier**, **Opportunity**, **Trend**, and **Observation**, each tab showing how many insights fall under it.

<figure><img src="/files/pvaOwObs89r5C9uotjYP" alt="Insights panel header with a select-all checkbox, the insight count, a search icon, and an Add insight button. Below sits a row of category filter tabs (All, Pain, Gain, Need, Expectation, Emotion, Workaround, Barrier, Opportunity, Trend, Observation) above the list of insight rows."><figcaption><p>Insights panel: category tabs, search, and Add insight</p></figcaption></figure>

Each row shows the insight name, its category, and counters for its linked quotes and their sentiment. Use the search icon to find an insight by name, or **+ Add insight** to create one the analysis didn't surface.

Click any insight to open its details below the panels.

<figure><img src="/files/0CepK3gDLYL1J8BmnNEa" alt="Insight details panel. The left side lists the insight&#x27;s linked quotes; the right side has editable Insight name and Summary fields. The top row has Previous and Next navigation, a position counter, and Add to portfolio, Delete, and Close actions."><figcaption><p>Insight details: editable name and summary, linked quotes, and the panel actions</p></figcaption></figure>

The **Insight name** and **Summary** fields are editable. Edit them in place to refine the wording or correct what the AI generated. The **Quotes** list shows every quote linked to this insight, and **Previous** and **Next** step through the insights without leaving the detail view.

When an insight is ready to carry into your portfolio, click **Add to portfolio** to start the guided flow. To remove an insight, click **Delete**; **Close** returns you to the list.

{% hint style="info" %}
Insight categories (Pain, Gain, Need, and so on) are a research-synthesis layer. They are not the same as portfolio item types (Pain point, Opportunity, Solution). You choose the portfolio type later, when you add a finding to the portfolio.
{% endhint %}

***

#### Edit several insights at once

To act on more than one insight, select their checkboxes (or the checkbox beside the **Insights** heading to select all). A **Bulk edit** bar appears with the number of items selected.

<figure><img src="/files/jbTao21RWXo4GgXED3QE" alt="A Bulk edit bar showing two items selected, with Add to portfolio and Delete actions and a control to close the selection."><figcaption><p>The bulk-edit bar for selected insights</p></figcaption></figure>

From the bar you can **Add to portfolio** to send the whole selection through the add flow together, or **Delete** to remove them all at once.

#### What carries into your portfolio

Adding insights to your portfolio is its own guided flow, where you choose whether each one becomes a new portfolio item or joins an existing one, and the quotes ride along as evidence. See [How to add findings to portfolio](/research-hub/how-to-add-findings-to-portfolio).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to create an investigation</strong></td><td>Start an investigation, upload transcripts, and let AI extract quotes, sentiment, and insights.</td><td><a href="/pages/bYRXhV15DwXPFxORlX4I">/pages/bYRXhV15DwXPFxORlX4I</a></td></tr><tr><td><strong>How to add findings to portfolio</strong></td><td>Promote insights and quotes from an investigation into portfolio items as evidence.</td><td><a href="/pages/rMOU7uLeTQCUU7SflZu0">/pages/rMOU7uLeTQCUU7SflZu0</a></td></tr></tbody></table>


# How to add findings to portfolio

Promote insights and quotes from a research investigation into portfolio items, with every quote traceable back to its source.

Turn the insights you found in an investigation into portfolio items your team can prioritize, with the underlying quotes carried over as evidence and linked back to where they came from.

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

#### Plan availability

Research Hub AI is available on paid plans, from **Repository** up. Promoting an insight is a standard portfolio action with no separate gate.
{% endhint %}

Before you start, open the investigation whose findings you want to promote, and review the insights so they say what you want a portfolio item to say. See [How to create an investigation](/research-hub/how-to-create-an-investigation) and [How to review insights and quotes](/research-hub/how-to-review-insights-and-quotes).

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

#### What you'll do

1. [Open the add-to-portfolio flow](#how-to-open-the-add-to-portfolio-flow)
2. [Place each insight in the portfolio](#how-to-place-each-insight-in-the-portfolio)
3. [Trace a finding back to its source](#how-to-trace-a-finding-back-to-its-source)
4. [Filter the portfolio by investigation](#how-to-filter-the-portfolio-by-investigation)
   {% endhint %}

#### How to open the add-to-portfolio flow

You can promote insights one at a time or in a batch. Both routes open the same guided flow.

* **One insight** - Open the insight to show its detail panel, then click **Add to portfolio** in the panel header.
* **Several at once** - Select insights with their row checkboxes. A **Bulk edit** bar appears at the bottom of the **Insights** panel. Click **Add to portfolio**.

<figure><img src="/files/ziJN4uvFDzCcN588Iwmv" alt="Investigation session view with two insights checked and a Bulk edit bar showing Add to portfolio and Delete actions."><figcaption><p>Select insights, then Add to portfolio from the Bulk edit bar</p></figcaption></figure>

***

#### How to place each insight in the portfolio

The flow lists every insight you're promoting under **Items** on the left. Select an item to choose where it goes, using the options on the right under **Select how to add this insight to the portfolio**. An item stays marked **Needs review** until you've made that choice.

You have three options per item.

{% stepper %}
{% step %}
**Create a new portfolio item**

Pick the portfolio item **type** from the dropdown. The standard types are **Pain point**, **Opportunity**, and **Solution**, alongside any custom types your account has added. To set the same type for every item in one go, click **Apply to all**.

<figure><img src="/files/R1IGNiX2t33wpSgOKroR" alt="Portfolio item type dropdown open, showing Opportunity, Pain point, Solution, and the custom types Goals and Risk."><figcaption><p>The type picker, with this account's custom types below the standard three</p></figcaption></figure>

The **Portfolio item preview** shows the new item's name and description and how many quotes come with it ("Adding N quotes"). Those quotes land on the item as evidence.

<figure><img src="/files/L2xMhlkfgp83va5FXyd7" alt="Add-to-portfolio flow with the Items list on the left and three options on the right. Create a new portfolio item is selected with the type set to Pain point, and a portfolio item preview shows the item name, description, and quote count."><figcaption><p>Creating a new portfolio item from an insight</p></figcaption></figure>
{% endstep %}

{% step %}
**Add to an existing portfolio item**

Smaply suggests existing items that match the insight, tagged **MOST RELEVANT**. Pick one, or click **Search portfolio** to find any item yourself. The insight's name and summary are appended to that item's description, and its quotes are added to the item's **Evidence** tab.

<figure><img src="/files/srK5Md7Dfa9QS69mE94Z" alt="Add to an existing portfolio item selected, listing three suggested items each tagged MOST RELEVANT, with a Search portfolio link and a preview of the chosen item."><figcaption><p>Suggested matches for an insight, tagged MOST RELEVANT</p></figcaption></figure>
{% endstep %}

{% step %}
**Don't add to portfolio**

Choose this to skip the insight and leave it in the investigation only. It won't create or change any portfolio item.
{% endstep %}

{% step %}
**Confirm**

Once every item is placed, click **Add \[N] items to portfolio** in the header. Smaply confirms with "N items successfully added to your portfolio." From there, **Manage items in portfolio** opens the portfolio in a new tab, filtered to this investigation, or **Continue research** returns you to the session.

<figure><img src="/files/2xQP4RZa3L6DRJI60XTj" alt="Completion dialog reading 2 items successfully added to your portfolio, with Manage items in portfolio and Continue research buttons."><figcaption><p>Confirmation after promoting insights</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: A portfolio item type is not the same as an insight category**

The **Pain point / Opportunity / Solution** types you pick here are portfolio item types. They're separate from the insight categories (Pain, Emotion, Gain, and so on) that the AI assigns during analysis.
{% endhint %}

You don't need a research investigation to build evidence. To add a quote, piece of feedback, or source link to a portfolio item by hand, see [How to add evidence to a portfolio item](/portfolio/how-to-add-evidence).

***

#### How to trace a finding back to its source

Every promoted quote stays linked to the transcript it came from. Open the portfolio item, go to its **Evidence** tab, and select a quote. Its source transcript opens on the right with the quote highlighted in place and a link back to the investigation.

<figure><img src="/files/MxBnJctia0DMd506W04E" alt="Portfolio item editor on the Evidence tab, listing four quotes on the left and the full source transcript on the right with a link to the investigation."><figcaption><p>The Evidence tab of a promoted portfolio item</p></figcaption></figure>

To remove a quote from the item, click **Unlink quote** in the source preview. This detaches it from the portfolio item without touching the original quote in the investigation.

<figure><img src="/files/aYuomSlCAr63wLjS7Cez" alt="A selected evidence quote highlighted within its source transcript, with an Unlink quote action and a link back to the source investigation."><figcaption><p>A quote highlighted in its source, with the Unlink quote action</p></figcaption></figure>

***

#### How to filter the portfolio by investigation

To see which portfolio items came from a given investigation, filter the **Portfolio** by research. Opening **Manage items in portfolio** from the completion dialog does this for you: the **Table** view loads with a **Research is \[investigation name]** filter chip and a count of matching items. You can also apply the **Research** filter yourself from any portfolio view.

<figure><img src="/files/uraVmazWryJkwevl0yPF" alt="Portfolio Table view filtered by Research is the investigation name, showing two matching portfolio items with a result count."><figcaption><p>The portfolio filtered to one investigation</p></figcaption></figure>

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to review insights and quotes</strong></td><td>Refine insights and quotes before you promote them.</td><td><a href="/pages/YT2UFNzR9ohQUKQsKECn">/pages/YT2UFNzR9ohQUKQsKECn</a></td></tr><tr><td><strong>How to add evidence to a portfolio item</strong></td><td>Add evidence by hand, including quotes, feedback, and source links.</td><td><a href="/pages/M7pLmvLqe5OLNTD1V9B1">/pages/M7pLmvLqe5OLNTD1V9B1</a></td></tr><tr><td><strong>How to create a portfolio item</strong></td><td>Create pain points, opportunities, solutions, and custom-typed items directly.</td><td><a href="/pages/ccKByq3EkMP6r9UQIneW">/pages/ccKByq3EkMP6r9UQIneW</a></td></tr><tr><td><strong>How to use portfolio item cards</strong></td><td>Place promoted items as cards on a journey map.</td><td><a href="/pages/7otLTFAejxDBK1QT5H5e">/pages/7otLTFAejxDBK1QT5H5e</a></td></tr></tbody></table>


# Metrics overview

Quantitative data on journey maps from integrations or manual CSV upload

Metrics bring quantitative data (usage stats, satisfaction scores, drop-off rates) onto journey maps. Connect a data source once, then reuse the metric across multiple maps.

### Create metrics

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Create and configure a metric</h4></td><td>The generic flow: choose a source and type, and set how it appears on cards.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td><td><a href="/files/RbS900fZgIeFwkxE0AgH">/files/RbS900fZgIeFwkxE0AgH</a></td></tr><tr><td><h4>Choose a metric type</h4></td><td>Decide between Series, Number, and Comparison.</td><td><a href="/pages/exJ4wHPtNqRHjfhSG9Y1">/pages/exJ4wHPtNqRHjfhSG9Y1</a></td><td><a href="/files/WfCufvEmIjpoWAjUOJpD">/files/WfCufvEmIjpoWAjUOJpD</a></td></tr><tr><td><h4>Manual metrics with CSV</h4></td><td>Create a metric from an uploaded CSV when no integration is connected.</td><td><a href="/pages/S51TFnU5zyHLVAwsRNUD">/pages/S51TFnU5zyHLVAwsRNUD</a></td><td><a href="/files/SCbEE63YEsuJEvHD5FMr">/files/SCbEE63YEsuJEvHD5FMr</a></td></tr></tbody></table>

<br>

***

### Connect and place

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Metrics tool integrations</h4></td><td>Connect Google Analytics, Power BI, Qualtrics, Excel, or Google Sheets as a source.</td><td><a href="/pages/Kf9X1ug2MQ8PofLSSbUl">/pages/Kf9X1ug2MQ8PofLSSbUl</a></td><td><a href="/files/YYH4pzsTpa12finsghAq">/files/YYH4pzsTpa12finsghAq</a></td></tr><tr><td><h4>Metric cards</h4></td><td>Add a metric to a journey map and customise how it displays.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td><td><a href="/files/oWFRfSjbUPDGKBJZEBgb">/files/oWFRfSjbUPDGKBJZEBgb</a></td></tr></tbody></table>


# How to create and configure a metric

Build a metric from manual data or a connected tool, preview it, and set how it appears on journey map cards.

A metric turns a number, a trend, or a before-and-after comparison into something you can drop onto a journey map. Create one from manual data you enter yourself, or from a tool you've connected at the account level, then preview it and save.

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

#### Prerequisites

* Editor role at the workspace level
* A data source. Manual data needs no setup. To pull from Google Analytics, Power BI, Excel (Office 365), Google Sheet, or Qualtrics, that tool must be connected first. See [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).
  {% endhint %}

#### Add a metric

You can start a metric from two places. Both open the same full-page **Add metric** builder.

* **From the workspace Metrics tab** - Click **Metrics** in the workspace sidebar, then **+ Create metric** in the top right.
* **From a journey map** - Hover in a lane, click **+ Add card**, and pick **Metric**. You can choose an existing metric or type a name to build a new one.

<figure><img src="/files/rbQks9UgPpJlBqP2xgGh" alt="The workspace Metrics tab listing saved metrics in a table with Name, Source, Type, Created, Updated, Used in, and Tags columns. A Create metric button sits in the top right."><figcaption><p>The workspace Metrics tab, with Create metric top right</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: fields unlock in order, and Save stays disabled until you preview**

The builder reveals fields one at a time: **Name** unlocks **Source**, **Source** unlocks **Type**, and **Type** reveals the data section and the **Show Preview** button. **Save** stays greyed out until you click **Show Preview**. If Save looks disabled, you haven't previewed yet.
{% endhint %}

{% stepper %}
{% step %}
**Open the metric builder**

Use either entry point above. The **Add metric** page opens with the **Metric data source** fields on the left and a **Default card preview** on the right.

<figure><img src="/files/4tyGi4FhXkzKOmNqKiwh" alt="The Add metric page. The left column shows the Metric data source section with empty Name, Source, Type, and Metric tags fields. The right column shows the Default card preview panel with a Show Preview button over a sample chart."><figcaption><p>Add metric, empty</p></figcaption></figure>
{% endstep %}

{% step %}
**Enter a Name**

Type a name in the **Name** field, such as `Website signups`. This is how the metric appears in the Metrics list and in the metric picker when you add it to a map.
{% endstep %}

{% step %}
**Pick a Source**

Open the **Source** dropdown and choose where the data comes from.

<figure><img src="/files/dWYPzquO1YWgtr2YD7hQ" alt="The Source dropdown open, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source options</p></figcaption></figure>

* **Manual (includes CSV upload)** - Enter values yourself, paste a table, or upload a CSV. No connection needed. See [How to use manual metrics with CSV](/metrics/how-to-use-manual-metrics-with-csv).
* **A connected tool** - Google Analytics, Power BI, Excel (Office 365), Google Sheet, or Qualtrics. These appear only after an Admin connects them. See the tool's setup guide, for example [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration), and [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).
  {% endstep %}

{% step %}
**Pick a Type**

Open the **Type** dropdown and choose **Series**, **Number**, or **Comparison**. The type sets what the metric measures and how it renders, and it determines the data fields shown in the next step.

<figure><img src="/files/lJKk4YOlBsdeSw1xW5pa" alt="The Type dropdown open, showing Series, Number, and Comparison options, each with a small leading icon."><figcaption><p>Metric types</p></figcaption></figure>

For help deciding, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type).
{% endstep %}

{% step %}
**Enter or configure the data**

The data section matches your type. **Series** gives you a Label and Value table you can fill in, paste into, or populate from a CSV. **Number** takes a single value with optional prefix and suffix. **Comparison** takes a current and previous value. For a connected tool, this section is where you map the source fields instead.
{% endstep %}

{% step %}
**Click Show Preview**

Click **Show Preview** in the **Default card preview** panel. The sample chart renders with your data and the full **Options** panel appears below it. This step also enables **Save**.

<figure><img src="/files/TlFhbsiuEEdexwL9GAVB" alt="The Default card preview showing a rendered Series bar chart titled Website signups, with four ascending blue bars and a vertical axis running from 0 to 350."><figcaption><p>Preview of a Series metric</p></figcaption></figure>
{% endstep %}

{% step %}
**Adjust the chart and display options**

Set how the card looks in the **Options** panel. Pick a chart type, add an optional heading and subheading, and adjust display details like decimal places and axis bounds.

<figure><img src="/files/wEfjfALiso4Stv3mUCJ8" alt="The Options panel for a Series metric. A Chart type row offers Bar chart, Horizontal bar, Pie chart, Line chart, and Table. Below are Chart heading and Chart subheading fields, then options for showing values, decimal places, and axis bounds."><figcaption><p>Chart and display options</p></figcaption></figure>
{% endstep %}

{% step %}
**Save**

Click **Save**. The metric joins the Metrics list and is ready to add to any journey map in the workspace.
{% endstep %}
{% endstepper %}

For worked examples, here's building a Number metric and a Comparison metric:

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FVpLMhO1wopakt9zvo42U%2Fcreate_number.mp4?alt=media&token=9c277dab-6c33-44aa-9939-9e8a217c382f>" %}

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FdqSIEMjUp8krhnv6utZE%2Fcreate_comparison.mp4?alt=media&token=c75f240f-2a67-41ab-bff6-e22a56bb9028>" %}

#### Configure the card display

The **Default card preview** panel on the right sets how a new card looks by default. Pick the chart type and fill in the heading and subheading, and the preview updates in real time.

Defaults set here apply only to new cards. Editing them later does not change cards already placed on a map. To change how a single card looks on a specific map, edit that card directly. See [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).

#### Troubleshooting

<details>

<summary><strong>The Save button is greyed out</strong> - Preview not generated</summary>

Save stays disabled until the metric has been previewed. Click **Show Preview** in the **Default card preview** panel. Once the chart renders, Save becomes active.

</details>

<details>

<summary><strong>The Source or Type dropdown is greyed out</strong> - Earlier field not set</summary>

The fields unlock in order. **Source** stays locked until the **Name** field has a value, and **Type** stays locked until a **Source** is selected. Fill in each field from the top down.

</details>

<details>

<summary><strong>The preview shows no data</strong> - Data not entered or source not returning values</summary>

For a Manual metric, check that you've entered values in the data section before previewing. For a connected tool, confirm the source fields are mapped and the integration is still connected. If a tool that worked before has stopped returning data, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

</details>

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to choose a metric type</strong></td><td>Decide between Series, Number, and Comparison.</td><td><a href="/pages/exJ4wHPtNqRHjfhSG9Y1">/pages/exJ4wHPtNqRHjfhSG9Y1</a></td></tr><tr><td><strong>How to use manual metrics with CSV</strong></td><td>Enter, paste, or upload your own data without an integration.</td><td><a href="/pages/S51TFnU5zyHLVAwsRNUD">/pages/S51TFnU5zyHLVAwsRNUD</a></td></tr><tr><td><strong>How to use metric cards</strong></td><td>Add a metric to a journey map and adjust how it displays per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>How to manage integrations</strong></td><td>Connect, disconnect, and switch the tools that feed your metrics.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# How to choose a metric type

Pick Series, Number, or Comparison so your data lands on the card in the shape that tells your story.

The type you pick decides how a metric's data is shaped and how it renders on a card. You choose it from the **Type** dropdown in the metric builder, after you name the metric and pick a source. For the full build flow, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

<figure><img src="/files/lJKk4YOlBsdeSw1xW5pa" alt="The Type dropdown in the metric builder, open to show three options: Series, Number, and Comparison, each with an icon."><figcaption><p>The Type dropdown in the metric builder</p></figcaption></figure>

There are three types. Match the type to the question your data answers.

#### Series

A sequence of data points, such as monthly signups or responses broken down by category. Pick Series when you have many values to plot and you want to show a trend over time or a breakdown across categories.

Series data renders as a **Bar**, **Horizontal bar**, **Pie**, **Line**, or **Table** chart, chosen in the card options. A line chart suits a trend over time; bars and pie suit category breakdowns; a table suits exact figures.

<figure><img src="/files/ijXPgXMxxj9YVms7XehV" alt="A metric card rendering Series data as a line chart, showing a monthly trend with a data-point tooltip."><figcaption><p>Series rendered as a line chart</p></figcaption></figure>

#### Number

A single standalone value, such as current CSAT or total revenue. Pick Number when you want to spotlight one headline figure.

A Number renders either as the value on its own, or as a semi-circular gauge that shows the value against an optional target. Use the gauge when the figure is most meaningful relative to a goal.

<figure><img src="/files/t5bzb1TVmj9ZSiNyCV0J" alt="A metric card showing a single value on a semi-circular gauge, with the value positioned against a target range."><figcaption><p>Number rendered as a gauge against a target</p></figcaption></figure>

#### Comparison

Two values contrasted, such as this quarter against last. Pick Comparison when the story is the change between exactly two figures.

A Comparison renders as a value with a percentage-change line below it, or as two bars side by side. The percentage line shows the direction and size of the change at a glance.

<figure><img src="/files/1NAtMf1qAsLHqJ3k749V" alt="A metric card showing a single value with a percentage-change line below it, indicating a decrease."><figcaption><p>Comparison rendered with a percentage-change line</p></figcaption></figure>

#### Which type should I use?

|                | **Series**                               | **Number**                          | **Comparison**                                   |
| -------------- | ---------------------------------------- | ----------------------------------- | ------------------------------------------------ |
| **Best for**   | Trends over time or category breakdowns  | One headline figure                 | The change between two values                    |
| **Data shape** | Many data points                         | A single value                      | Exactly two values                               |
| **Renders as** | Bar, horizontal bar, pie, line, or table | A value or a gauge against a target | A value with a percentage change, or paired bars |

The type also sets which render options are available: Series gives you the five chart types, Number gives you the value or gauge, and Comparison gives you the percentage line or paired bars. You can change the render in the card options at any time. Once a type fits, build the metric in [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

<figure><img src="/files/TlFhbsiuEEdexwL9GAVB" alt="A metric card on a journey map rendering Series data as a vertical bar chart titled Website signups."><figcaption><p>A Series metric on a card</p></figcaption></figure>

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to create and configure a metric</strong></td><td>Build a metric from name to saved card, for any source and type.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>How to use manual metrics with CSV</strong></td><td>Enter Series data by hand, paste from a spreadsheet, or upload a CSV.</td><td><a href="/pages/S51TFnU5zyHLVAwsRNUD">/pages/S51TFnU5zyHLVAwsRNUD</a></td></tr><tr><td><strong>How to use metric cards</strong></td><td>Display a metric on a journey map and switch its chart type per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr></tbody></table>


# How to use manual metrics with CSV

Build a metric from your own data when it isn't in a connected tool, by CSV upload, paste, or hand-typed values.

Manual is the source to reach for when your data isn't in a connected tool. It needs no integration setup, supports all three metric types, and lets you bring data in by CSV upload, by pasting from a spreadsheet, or by typing values directly. In the **Source** dropdown it's labelled **Manual (includes CSV upload)**.

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

#### Prerequisites

You need an Editor role at the workspace level. No integration setup is required.
{% endhint %}

#### Add a manual metric

The full builder flow (both entry points, the preview, and the card options) is covered in [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric). The steps below focus on what's specific to the Manual source: choosing it and getting your data in.

{% stepper %}
{% step %}
**Open the metric builder and enter a Name**

Start a new metric and give it a **Name**. The **Name** unlocks the **Source** field. See [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric) for the two ways to open the builder.
{% endstep %}

{% step %}
**Pick Source = Manual (includes CSV upload)**

In the **Source** dropdown, select **Manual (includes CSV upload)**. It's the first option and the only source that needs no connection.

<figure><img src="/files/dWYPzquO1YWgtr2YD7hQ" alt="The Source dropdown open in the metric builder, listing Manual (includes CSV upload) first, followed by Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, Manual selected</p></figcaption></figure>
{% endstep %}

{% step %}
**Pick a Type**

Choose **Series**, **Number**, or **Comparison**. The type decides how you enter the data: Series uses a table you can fill by CSV, paste, or by hand; Number and Comparison take values you type inline. For help deciding, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type).
{% endstep %}

{% step %}
**Enter your data**

Fill in the data for the type you picked. See [Enter your data](#enter-your-data) below for the per-type detail.
{% endstep %}

{% step %}
**Click Show Preview**

Click **Show Preview** to render the chart and reveal the full options panel.
{% endstep %}

{% step %}
**Adjust the options and Save**

Set the chart heading, decimals, and any other display options, then click **Save**. The metric appears in the workspace **Metrics** list.
{% endstep %}
{% endstepper %}

***

#### Enter your data

How you enter data depends on the metric type.

For a **Series** metric, the **Series data** section gives you three interchangeable ways to fill the **Label** / **Value** table. Use whichever fits the data you have.

<figure><img src="/files/aKPIAUAtJyJ6AdFhVFjW" alt="The Series data section of the metric builder with Source set to Manual. An Upload CSV button sits top-right, a green tip explains pasting from a spreadsheet, and helper text links a downloadable example above an empty Label and Value table with an Add row link."><figcaption><p>Series data: Upload CSV, paste, or the Label / Value table</p></figcaption></figure>

* **Upload CSV** - Click **Upload CSV** and choose your file. The CSV has two columns, **Label** and **Value** (for example, `Jan,120`). The **download example** link in the helper text gives you a template to fill in.
* **Paste from a spreadsheet** - Copy a two-column range from Excel or Google Sheets, click into the table, and paste. The rows fill in automatically.
* **Type rows by hand** - Enter a **Label** and **Value**, then click **+ Add row** for each data point. Drag the handle to reorder rows, or use the per-row delete to remove one.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Paste straight from a spreadsheet**

Copy a two-column range from Excel or Google Sheets, select a cell in the table, and paste. There's no need to format the data first or save it as a file.
{% endhint %}

{% hint style="warning" %}

#### **Important: The CSV needs exactly two columns**

Use one column for the **Label** and one for the **Value** (`Jan,120`). The same two-column shape applies whether you upload a file or paste from a spreadsheet.
{% endhint %}

For a **Number** or **Comparison** metric, there's no table or CSV. You type the values directly into the builder:

* **Number** - Enter a **Prefix**, **Value**, and **Suffix** (for example, `$` `1,200` or `85` `%`).
* **Comparison** - Enter a **Prefix**, **Current** value, **Previous** value, and **Suffix**. The metric renders the two values with the percentage change between them.

***

#### Preview and save

Once your data is in, click **Show Preview** to render the card and open the display options. For a Series metric, the preview shows the chart you've built.

<figure><img src="/files/TlFhbsiuEEdexwL9GAVB" alt="A rendered metric card titled Website signups showing a bar chart of four increasing bars on a 0 to 350 axis."><figcaption><p>Series card preview</p></figcaption></figure>

After you click **Save**, the metric appears in the workspace **Metrics** list with its source shown as **Manual**, ready to add to a journey map.

<figure><img src="/files/uuC0UWhFHNNwUvik0nBs" alt="The workspace Metrics list with a saved metric named Website signups at the top, its Source column reading Manual and its Type column reading Series."><figcaption><p>The saved metric in the Metrics list</p></figcaption></figure>

To put the metric on a journey map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).

***

#### Troubleshooting

<details>

<summary><strong>CSV won't import</strong> - File shape issue</summary>

The file needs exactly two columns, **Label** and **Value**, with one data point per row (`Jan,120`). If your export has extra columns, header rows the builder doesn't expect, or merged cells, trim it down to two columns first. Use the **download example** link as a reference for the expected shape.

</details>

<details>

<summary><strong>Values aren't charting</strong> - Missing Label or Value</summary>

A Series chart needs a **Label** and a **Value** in each row. Rows with one cell filled and the other blank won't plot. Check that every row has both, then click **Show Preview** again to re-render.

</details>

<details>

<summary><strong>Save is greyed out</strong> - Preview not generated yet</summary>

**Save** stays disabled until you click **Show Preview**. Generating the preview renders the chart and unlocks the rest of the options, including **Save**.

</details>

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to create and configure a metric</strong></td><td>The full builder flow, both entry points, preview, and card options.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>How to choose a metric type</strong></td><td>When to use Series, Number, or Comparison, and how each one renders.</td><td><a href="/pages/exJ4wHPtNqRHjfhSG9Y1">/pages/exJ4wHPtNqRHjfhSG9Y1</a></td></tr><tr><td><strong>How to use metric cards</strong></td><td>Add a saved metric to a journey map and choose how it displays.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr></tbody></table>


# Sharing and exporting overview

Share journey maps via link, share specific saved views, and export to PDF.

Share journey maps outside the workspace with public links, share specific saved views, and export to PDF for offline use.

### Share and export

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>HTML share link</h4></td><td>Create a read-only public link anyone can open without a Smaply account.</td><td><a href="/pages/pIllWy9tostqqZvqoymz">/pages/pIllWy9tostqqZvqoymz</a></td><td><a href="/files/5LgUo4pRtnN3o8AkTt8d">/files/5LgUo4pRtnN3o8AkTt8d</a></td></tr><tr><td><h4>Share a saved view</h4></td><td>Share a single filtered view through its own dedicated link.</td><td><a href="/pages/EzewsMl4q3GLzrR9AXm0">/pages/EzewsMl4q3GLzrR9AXm0</a></td><td><a href="/files/FzBhmYPitBXU7EkYjeTI">/files/FzBhmYPitBXU7EkYjeTI</a></td></tr><tr><td><h4>Export as PDF</h4></td><td>Export a journey map as a PDF, with optional inclusions like the description.</td><td><a href="/pages/bFw8ZAfXKB40zpzNx0GL">/pages/bFw8ZAfXKB40zpzNx0GL</a></td><td><a href="/files/82nZYwlTWASRkqvvHR7I">/files/82nZYwlTWASRkqvvHR7I</a></td></tr><tr><td><h4>Share or export a persona</h4></td><td>Share a persona as a read-only public link, or export it as a PDF.</td><td><a href="/pages/FJ6yN3C95BvKbdxz2fx1">/pages/FJ6yN3C95BvKbdxz2fx1</a></td><td><a href="/files/xikr2dXZFXYIH6xdvAGT">/files/xikr2dXZFXYIH6xdvAGT</a></td></tr></tbody></table>

<br>

***

### Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Invite users</h4></td><td>Give collaborators edit, comment, or view-only access instead of a public link.</td><td><a href="/pages/F1Nzd1jlynqOnRaG0WSM">/pages/F1Nzd1jlynqOnRaG0WSM</a></td><td><a href="/files/1TuZbdvr3NEsYrV6Pdqd">/files/1TuZbdvr3NEsYrV6Pdqd</a></td></tr><tr><td><h4>Custom branding</h4></td><td>Put your logo and colours on shared views and PDF exports.</td><td><a href="/pages/EKjozESfgG8Y8qnOvKPa">/pages/EKjozESfgG8Y8qnOvKPa</a></td><td><a href="/files/16dm6nqEJw3Im5UuyEal">/files/16dm6nqEJw3Im5UuyEal</a></td></tr></tbody></table>


# How to share a journey map via HTML link

Create a read-only public link to a journey map and control who can open it and what they see.

Generate a read-only link to a journey map so anyone can open it in their browser, without a Smaply account. Open the Share dialog, turn on the **Share link (view only)**, and copy the URL.

{% hint style="info" icon="compass" %}
Want teammates to edit or comment instead? See [How to invite users](/account-and-team/users-and-roles/how-to-invite-users). This article covers public, read-only sharing only.
{% endhint %}

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

#### Prerequisites

Only an Admin can generate or manage the public link. Editors and Viewers can open a journey map but can't create, change, or disable its Share link.
{% endhint %}

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

#### Quick links

1. [How to create a Share link for a journey map](#how-to-create-a-share-link-for-a-journey-map)
2. [Share link vs map access](#share-link-vs-map-access)
3. [What people see when they open a Share link](#what-people-see-when-they-open-a-share-link)
4. [How to share a filtered view instead of the whole map](#how-to-share-a-filtered-view-instead-of-the-whole-map)
5. [How to disable the link](#how-to-disable-the-link)
   {% endhint %}

#### How to create a Share link for a journey map

{% stepper %}
{% step %}
**Open the Share dialog**

Open the Share dialog from either entry point: click the **Share** icon in the top bar of the journey map editor, or, from the journey map list, open a map's three-dot menu and select **Share**.
{% endstep %}

{% step %}
**Find the Share link (view only) panel**

<figure><img src="/files/td28kaV7KXikiRWgJlTJ" alt="The Share dialog showing the Share link (view only) panel with a read-only URL field, a Copy Link button, a Disable link action, and a warning that anyone with the link can view the journey map."><figcaption><p>The Share dialog, with the Share link (view only) panel at the bottom</p></figcaption></figure>

The Share dialog handles both sharing methods. **Manage user access** at the top invites people to the map; the **Share link (view only)** panel below it generates the public link.
{% endstep %}

{% step %}
**Turn on the link**

Enable the **Share link (view only)** panel. Smaply generates a unique URL for this map.

{% hint style="warning" %}

#### **Important: Anyone with this link can view the journey map**

Treat the URL like a password. Share it only through channels you trust, and disable the link when you no longer need it.
{% endhint %}
{% endstep %}

{% step %}
**Copy the link**

Click **Copy Link** and paste the URL wherever you're sharing it.
{% endstep %}

{% step %}
**Optional: add password protection**

{% hint style="info" icon="tag" %}
Password protection is available on the **Framework** plan and above.
{% endhint %}

<figure><img src="/files/I0TkwGtvZN5S6faer2W0" alt="The Share link panel with Password required enabled, showing a Generate action, the masked password field with reveal and copy icons, the eight-character-minimum rule, and a Save button."><figcaption><p>Password required, with the Generate and Save controls</p></figcaption></figure>

Tick **Password required** to make viewers enter a password before the map loads. Click **Generate** for a compliant password or type your own, then click **Save**. Passwords need 8 characters minimum and a combination of letters, numbers, and symbols.

{% hint style="warning" %}

#### **Important: Copy the password before you close the dialog**

Store it somewhere safe and share it separately from the link. If you lose it, generate a new one and save again.
{% endhint %}
{% endstep %}
{% endstepper %}

#### Share link vs map access

These are two different ways to share a journey map. Pick the one that fits your audience.

|                            | Share link (HTML)                        | Map access                                             |
| -------------------------- | ---------------------------------------- | ------------------------------------------------------ |
| **Best for**               | Quick external viewing                   | Team collaboration and feedback                        |
| **Smaply account needed?** | <i class="fa-xmark">:xmark:</i> No       | <i class="fa-check">:check:</i> Yes                    |
| **Who can open?**          | Anyone with the link (password optional) | People invited at Admin, Editor, or Viewer level       |
| **Read-only?**             | <i class="fa-check">:check:</i> Yes      | Viewers yes (can comment); Editors and Admins can edit |
| **Can comment?**           | <i class="fa-xmark">:xmark:</i> No       | <i class="fa-check">:check:</i> Yes                    |

If you need feedback or edits from the person you're sharing with, invite them to the map instead of sending a Share link.

#### What people see when they open a Share link

The shared page renders read-only and closely mirrors the editor. It shows all visible lanes, cards, stages, and steps. Your account logo appears in the top-left and a "powered by Smaply" badge in the top-right.

A collapsible journey information panel at the top displays the map name, description, performance indicator, coordinator, tags, and a portfolio items summary.

Viewers can't edit or comment. If you need comments, invite them to the map instead.

#### How to share a filtered view instead of the whole map

If you apply a filter or open a saved view on the map before you generate the Share link, that filter state persists on the shared page. Useful for sharing a focused cut with specific stakeholders.

For a dedicated URL per audience, share saved views directly. See [How to share a saved view](/sharing-and-exporting/how-to-share-a-saved-view).

#### How to disable the link

To revoke access, open the Share dialog, find the **Share link (view only)** panel, and click **Disable link**. Access is revoked immediately, and anyone who still has the URL sees an error instead of the map.

{% hint style="warning" %}

#### **Important: Re-enabling the link creates a new URL**

When you enable a disabled link again, Smaply mints a new URL and the old one stays dead. A link can't be paused and resumed at the same address, so copy and share the new URL after you re-enable.
{% endhint %}

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to invite users</strong></td><td>Invite users at account, workspace, or journey-map level so collaborators can comment or edit</td><td><a href="/pages/F1Nzd1jlynqOnRaG0WSM">/pages/F1Nzd1jlynqOnRaG0WSM</a></td></tr><tr><td><strong>How to share a saved view</strong></td><td>Share a filtered perspective via its own HTML link</td><td><a href="/pages/EzewsMl4q3GLzrR9AXm0">/pages/EzewsMl4q3GLzrR9AXm0</a></td></tr><tr><td><strong>How to export a journey map as PDF</strong></td><td>Produce a static file for offline sharing or print</td><td><a href="/pages/bFw8ZAfXKB40zpzNx0GL">/pages/bFw8ZAfXKB40zpzNx0GL</a></td></tr><tr><td><strong>How to save and apply a view</strong></td><td>Save filter and display settings as a named view for reuse</td><td><a href="/pages/0biJxUYNUHzaN0wxgwEg">/pages/0biJxUYNUHzaN0wxgwEg</a></td></tr></tbody></table>


# How to share a saved view

Share one filtered perspective of a journey map as a view-only link, without giving people access to the full map.

Each saved view gets its own view-only link, separate from the full-map link. Turn on the link for a single filtered perspective, copy it, and send it to anyone, no Smaply account needed on their end.

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

#### Prerequisites

You have a saved view on the map. If you haven't created one yet, see [How to save and apply a view](/journey-maps/filtering-and-views/how-to-save-and-apply-a-view).
{% endhint %}

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

#### Plan availability

Saved views are available on the **Repository** plan and above, so per-view sharing is too. The view-only link itself works on every plan.
{% endhint %}

#### How to create a share link for a saved view

Apply the view first so the Share panel knows which perspective to link. The panel title names the active view, which is how you confirm you're sharing the right one.

{% stepper %}
{% step %}
**Apply the saved view**

Open the **Views** menu above the map and select the view you want to share. The map filters to that view and the **Views** toggle relabels to the view's name.
{% endstep %}

{% step %}
**Open the Share menu**

Click **Share** in the top-right corner of the editor, then select **Share link (view-only)**.

<figure><img src="/files/0qOytX4cnPewN2j2qEPE" alt="The Share dropdown in the top-right of the journey map editor, showing Manage access and Share link (view-only)."><figcaption><p>Share > Share link (view-only)</p></figcaption></figure>
{% endstep %}

{% step %}
**Enable the link**

The panel opens titled **Share this journey view '\[view name]'**. Click **Enable** next to **Create share link (view-only)** to generate the link.

<figure><img src="/files/DAkBGVRBCS7ahLrZ4cJI" alt="The share panel for a saved view, titled Share this journey view, with a Create share link (view-only) row and an Enable action."><figcaption><p>The per-view share panel, before enabling</p></figcaption></figure>
{% endstep %}

{% step %}
**Copy the link**

Click **Copy Link** to copy the generated URL, which sits on `https://www.smaply.app/sharing/`. Anyone who opens it sees a read-only version of the map with this view's filter already applied. They don't need a Smaply account.

<figure><img src="/files/denKPf8HKjbxzfXh4u4y" alt="The enabled per-view share panel showing a smaply.app/sharing link, a Copy Link button, a Disable link toggle, a Password required checkbox, and a Generate button."><figcaption><p>The link is live and ready to copy</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The shared page mirrors the editor and updates live as you change the map. It is not a snapshot, so viewers always see the current state. No view counts or visitor data are tracked on the link.

***

#### How to add a password to the link

In the share panel, tick **Password required**, then click **Generate** for a password or type your own. A password needs at least 8 characters using a mix of letters, numbers, and symbols. Use the copy icon to save it, and send it to viewers separately from the link.

{% hint style="info" icon="tag" %}
Password protection is available on the **Framework** plan and above.
{% endhint %}

{% hint style="warning" %}

#### **Important: Copy the password before you close the panel**

The password is shown once. If you lose it, generate a new one and re-share it.
{% endhint %}

#### How to disable the link

Click **Disable link** in the share panel. Access is revoked immediately. The toggle is independent per view, so disabling one view's link leaves the full-map link and any other views' links untouched.

{% hint style="warning" %}

#### **Important: Re-enabling creates a new URL**

A disabled link can't be resumed at the same address. Turning it back on generates a fresh URL, and the old one stays invalid. Anyone you want to keep sharing with needs the new link.
{% endhint %}

***

#### How sharing a view differs from sharing the full map

The **Share** dropdown is the same with or without a view applied. What changes is the result: with a view applied, **Share link (view-only)** produces a link scoped to that view's filter; with no view applied, it shares the whole map. Each link is a separate URL with its own on/off toggle.

For a link to the complete, unfiltered map, see [How to share a journey map via HTML link](/sharing-and-exporting/how-to-share-a-journey-map-via-html-link).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to save and apply a view</strong></td><td>Create the saved view you want to share, and switch between views on a map.</td><td><a href="/pages/0biJxUYNUHzaN0wxgwEg">/pages/0biJxUYNUHzaN0wxgwEg</a></td></tr><tr><td><strong>How to share a journey map via HTML link</strong></td><td>Generate a view-only link to the full, unfiltered journey map.</td><td><a href="/pages/pIllWy9tostqqZvqoymz">/pages/pIllWy9tostqqZvqoymz</a></td></tr><tr><td><strong>How to filter a journey map</strong></td><td>Filter by persona, tag, or portfolio item to build the perspective you save as a view.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr></tbody></table>


# How to export a journey map as PDF

Export a journey map to PDF, choosing which extras to include and letting the layout fit to one page automatically.

To export a journey map, open it in the editor, click the **download** icon in the top-right corner, choose which features to include, and click **Export to PDF**. The file downloads automatically once it's ready. PDF is the only export format for journey maps.

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

#### Prerequisites

Clear any active filters first. While a filter is applied, the **download** icon is greyed out and export is unavailable. See [How to filter a journey map](/journey-maps/filtering-and-views/how-to-filter-a-journey-map) for the **Clear** and **Clear all** controls.
{% endhint %}

#### How to export the journey map

{% stepper %}
{% step %}
**Open the export options**

In the journey map editor, click the **download** icon in the top-right corner, near the version history and favourite icons. The **Export journey map** modal opens.
{% endstep %}

{% step %}
**Choose what to include**

Tick the features you want in the export. All six are off by default, so an export with nothing ticked gives you the map on its own.

<figure><img src="/files/cMWjVksBTRrarAdFAlPJ" alt="The Export journey map modal with the subtitle Select features to include in your export, six unchecked checkboxes labelled Journey description, Persona legend, Performance indicator, Coordinator, Tags, and Portfolio items, and Cancel and Export to PDF buttons."><figcaption><p>Export journey map, all features unchecked</p></figcaption></figure>

Each option adds one element to a header section above the map:

* **Journey description** - the description from the journey information panel
* **Persona legend** - the personas used on the map and their colours
* **Performance indicator** - the map's status (Healthy, Monitored, or Attn needed)
* **Coordinator** - the assigned coordinator
* **Tags** - the tags applied to the map
* **Portfolio items** - the summary of portfolio items, with counts and progress per type
  {% endstep %}

{% step %}
**Export and wait for the download**

Click **Export to PDF**. An **Export complete** dialog with **Your export is ready** appears when the file is done, and the PDF downloads automatically. Click **Close** to dismiss the dialog.

<figure><img src="/files/cVobPxaIqY0vYTcseb0y" alt="The Export complete dialog showing a green checkmark, the text Your export is ready, and a Close button."><figcaption><p>The PDF downloads on its own once it's ready</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="warning" %}

#### **Important: Don't edit the map while it's exporting**

Changes you make during export may end up in the file. Wait for the **Export complete** dialog before touching the map again.
{% endhint %}

#### What the PDF includes

The PDF shows the full journey map exactly as it appears in the editor: every visible lane, card, stage, and step, plus any features you ticked in the export options. The journey information section is always included.

The layout fits automatically, so there are no page-size, orientation, or scale settings to choose:

* The full width of the map always fits on a single page.
* Very large maps (around 50 columns or more) scale down to fit that width.
* Spanned cards are never split across a page break.

If your account has a branding logo configured, it appears on the PDF. To set or change it, see [How to set up custom branding](/account-and-team/customization/how-to-set-up-custom-branding).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to set up custom branding</strong></td><td>Add the logo that appears on PDF exports and shared maps.</td><td><a href="/pages/EKjozESfgG8Y8qnOvKPa">/pages/EKjozESfgG8Y8qnOvKPa</a></td></tr><tr><td><strong>How to share a journey map via HTML link</strong></td><td>Create a read-only public link instead of a downloadable file.</td><td><a href="/pages/pIllWy9tostqqZvqoymz">/pages/pIllWy9tostqqZvqoymz</a></td></tr><tr><td><strong>How to filter a journey map</strong></td><td>Apply and clear filters, including the filters you clear before exporting.</td><td><a href="/pages/TvWyNP7bpL7PzUBbgLJ2">/pages/TvWyNP7bpL7PzUBbgLJ2</a></td></tr><tr><td><strong>How to export portfolio to CSV</strong></td><td>Export portfolio items as a spreadsheet, the other export path in Smaply.</td><td><a href="/pages/EWpdFIYYJJJqGy3W0gDt">/pages/EWpdFIYYJJJqGy3W0gDt</a></td></tr></tbody></table>


# How to share or export a persona

Create a read-only public link to a persona or export it as a PDF to share outside Smaply.

Share a persona two ways: generate a read-only public link anyone can open in their browser, or export the persona as a PDF. Both start from the persona editor.

{% hint style="info" icon="compass" %}
Want a teammate to edit or comment instead? Invite them. See [How to invite users](/account-and-team/users-and-roles/how-to-invite-users).
{% endhint %}

#### How to share a persona with a public link

Open the persona, then use the blue **Share** button in the editor's top bar. You can also start sharing from the **Personas** list by opening a persona's three-dot menu and selecting **Share link (view-only)**, but the full controls (the URL, copy, password, and disable) live in the editor's Share dialog.

{% stepper %}
{% step %}
**Open the persona and click Share**

Open the persona, then click the blue **Share** button in the top bar. The download icon to its left is for PDF export.

<figure><img src="/files/qp6pMz0BAqzUfXXh53WM" alt="The top bar of the persona editor showing a download icon on the left and a blue Share button on the right."><figcaption><p>Persona editor top bar: export (left), Share (right)</p></figcaption></figure>
{% endstep %}

{% step %}
**Enable the link**

In the **Share link** dialog, click **Enable** on the **Create share link (view-only)** panel. Smaply generates a unique URL for this persona.

{% hint style="warning" %}

#### **Important: Anyone with this link can view the persona**

Treat the URL like a password. Share it only through channels you trust, and disable the link when you no longer need it.
{% endhint %}
{% endstep %}

{% step %}
**Copy the link**

<figure><img src="/files/27Mf1Oe6JSIoock6A5on" alt="The Share link dialog with the link enabled, showing a warning that anyone with the link can view the persona, a read-only URL field, a Copy Link button, a Disable link action, and an unchecked Password required checkbox."><figcaption><p>The Share link dialog once the link is enabled</p></figcaption></figure>

Click **Copy Link** and paste the URL wherever you're sharing it.
{% endstep %}

{% step %}
**Optional: add password protection**

{% hint style="info" icon="tag" %}
Password protection is available on the **Framework** plan and above.
{% endhint %}

<figure><img src="/files/cVMyEuC6Fd0yAoEhTnmB" alt="The Share link dialog with Password required ticked, showing a generated password, a Generate action, a Copy password button, the eight-character-minimum rule, a Save button, and a note that the password is only visible once."><figcaption><p>Password required, with the Generate and Save controls</p></figcaption></figure>

Tick **Password required** so viewers must enter a password before the persona loads. Click **Generate** for a compliant password or type your own, then click **Save**. Passwords need 8 characters minimum and a combination of letters, numbers, and symbols.

{% hint style="warning" %}

#### **Important: Copy the password before you close the dialog**

The password is only visible once. Click **Copy password**, store it somewhere safe, and share it separately from the link. If you lose it, generate a new one and save again.
{% endhint %}
{% endstep %}

{% step %}
**How to disable the link**

To revoke access, click **Disable link** in the **Share link** dialog. Access stops immediately, and anyone who still has the URL sees an error instead of the persona.

{% hint style="warning" %}

#### **Important: Re-enabling the link creates a new URL**

When you enable a disabled link again, Smaply mints a new URL and the old one stays dead. A link can't be paused and resumed at the same address, so copy and share the new URL after you re-enable.
{% endhint %}
{% endstep %}
{% endstepper %}

#### What people see when they open the link

The link opens a read-only version of the persona. Viewers don't need a Smaply account, and they can't edit anything.

The shared page is live, not a snapshot: viewers always see the persona's current state, so any edits you make show up the next time they open the link. There are no view analytics, so view counts and visitor details aren't tracked.

#### How to export a persona as a PDF

To export, open the persona, click the **download** icon in the editor's top bar, choose what to include, and click **Export to PDF**. PDF is the only export format.

{% stepper %}
{% step %}
**Open the persona and click the download icon**

Open the persona, then click the **download** icon in the top bar, to the left of **Share**. The **Export persona** modal opens.
{% endstep %}

{% step %}
**Choose what to include**

<figure><img src="/files/6Kk8gTtF9VxSK694qm6u" alt="The Export persona modal with the subtitle Select what to include in your export and three unchecked checkboxes labelled Description, Tags, and Linked journey, each with a one-line explanation, plus Cancel and Export to PDF buttons."><figcaption><p>Export persona, all options unchecked</p></figcaption></figure>

Tick the extras you want. All three are off by default, so an export with nothing ticked gives you the persona on its own:

* **Description** - the persona description
* **Tags** - the tags linked to this persona
* **Linked journey** - the names of the journey maps this persona is used on
  {% endstep %}

{% step %}
**Export and wait for the download**

Click **Export to PDF**. The modal shows **Your export is being processed** with a progress bar while Smaply builds the file.

<figure><img src="/files/mYC1MZW1ysflQLZI4ea5" alt="The Export persona modal showing a download icon, the text Your export is being processed, a message to please wait, and a progress bar."><figcaption><p>Stay on the page until the export finishes</p></figcaption></figure>

When the file is ready, the PDF downloads automatically and an **Export complete** dialog appears. Click **Close** to dismiss it.

<figure><img src="/files/vnrkeGJEf2zgJCZBmDWD" alt="The Export complete dialog showing a green checkmark, the text Your export is ready, and a Close button."><figcaption><p>The PDF downloads on its own once it's ready</p></figcaption></figure>
{% endstep %}
{% endstepper %}

If your account has a branding logo configured, it appears on the PDF. To set or change it, see [How to set up custom branding](/account-and-team/customization/how-to-set-up-custom-branding).

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to share a journey map via HTML link</strong></td><td>Create a read-only public link to a journey map instead of a persona</td><td><a href="/pages/pIllWy9tostqqZvqoymz">/pages/pIllWy9tostqqZvqoymz</a></td></tr><tr><td><strong>How to export a journey map as PDF</strong></td><td>Produce a static journey map file for offline sharing or print</td><td><a href="/pages/bFw8ZAfXKB40zpzNx0GL">/pages/bFw8ZAfXKB40zpzNx0GL</a></td></tr><tr><td><strong>How to manage personas</strong></td><td>Sort, copy, tag, archive, and delete personas from the Personas list</td><td><a href="/pages/oScEAxHrtqqY2twvz5kM">/pages/oScEAxHrtqqY2twvz5kM</a></td></tr><tr><td><strong>How to set up custom branding</strong></td><td>Add the logo that appears on PDF exports and shared views</td><td><a href="/pages/EKjozESfgG8Y8qnOvKPa">/pages/EKjozESfgG8Y8qnOvKPa</a></td></tr></tbody></table>


# Integrations overview

Connect Smaply to external metrics, planning tools, and embed sources

Integrations connect Smaply to your data and work management tools. Metrics and planning integrations are configured once at the account level and reused across every workspace. Embed integrations are added per-card directly on journey maps.

### Connect a tool

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4>Set up your first integration</h4></td><td>A guided walkthrough for connecting and using your first integration.</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td><td><a href="/files/09nDMLVyIwLjsGiJtPPZ">/files/09nDMLVyIwLjsGiJtPPZ</a></td></tr><tr><td><h4>Metrics tools</h4></td><td>Pull data from Google Analytics, Power BI, Excel 365, Google Sheets, and Qualtrics.</td><td><a href="/pages/Kf9X1ug2MQ8PofLSSbUl">/pages/Kf9X1ug2MQ8PofLSSbUl</a></td><td><a href="/files/YYH4pzsTpa12finsghAq">/files/YYH4pzsTpa12finsghAq</a></td></tr><tr><td><h4>Planning tools</h4></td><td>Link work items from Jira, Asana, Azure DevOps, Linear, Monday.com, and Trello.</td><td><a href="/pages/1UFmZNSO8c4cjWEYlFUe">/pages/1UFmZNSO8c4cjWEYlFUe</a></td><td><a href="/files/QzzpoZ39TYa5pmWNrWA6">/files/QzzpoZ39TYa5pmWNrWA6</a></td></tr><tr><td><h4>Embed integrations</h4></td><td>Embed Figma, Miro, Google Docs, YouTube, and other sources on a card.</td><td><a href="/pages/xEXHdynnj0g2GXg8mY4m">/pages/xEXHdynnj0g2GXg8mY4m</a></td><td><a href="/files/2JQ7lOqx2TSb6xE7Xwje">/files/2JQ7lOqx2TSb6xE7Xwje</a></td></tr><tr><td><h4>Manage integrations</h4></td><td>Check connection states, disconnect, switch auth, and handle refresh.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td><td><a href="/files/tYyftY7d2fchyQFS1gQQ">/files/tYyftY7d2fchyQFS1gQQ</a></td></tr></tbody></table>


# Set up your first integration

Connect Jira, Google Sheets, Qualtrics, Power BI, or any supported tool so your journey maps show live data from the systems your team already uses.

Plug Jira tickets, Google Sheets numbers, Qualtrics survey results, or any supported tool into Smaply once. Then pull their live data into any journey map in your account.

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

#### Prerequisites

You need Admin permissions at the account level. Integrations are configured once for the whole account, not per workspace, and only Admins can set them up.
{% endhint %}

***

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

#### In this guide

1. [Choose the type of integration you need](#choose-the-type-of-integration-you-need)
2. [Find the setup guide for your tool](#find-the-setup-guide-for-your-tool)
3. [Connect the integration in Account Settings](#connect-the-integration-in-account-settings)
4. [Use your integration on a journey map](#use-your-integration-on-a-journey-map)
5. [Verify the integration is working](#verify-the-integration-is-working)
   {% endhint %}

***

#### Choose the type of integration you need

Smaply integrations fall into three types. Match your goal to the right one before you go further:

|                                  | Metrics                                                            | Planning                                                            | Embed                                                                    |
| -------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Best for                         | Showing quantitative data (KPIs, survey results, traffic) on a map | Linking delivery work (tickets, tasks) to the journey it relates to | Pulling in live external content like Figma frames, YouTube, Google Docs |
| What you see on a journey map    | A chart or number card pulling from an external data source        | A card showing a live ticket or task from your planning tool        | An interactive preview of the external content inside a card             |
| Where you set it up              | Account Settings, Integrations tab                                 | Account Settings, Integrations tab                                  | Directly on a card, by pasting a URL                                     |
| Account-level setup, Admin only? | Yes                                                                | Yes                                                                 | No, any Editor adds one per card                                         |

This guide covers the **Metrics** and **Planning** integrations you set up in Account Settings. If you want to embed external content, there's nothing to set up at the account level: see [How to use embed integrations](/integrations/how-to-use-embed-integrations) instead.

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

#### Plan availability

On the Free plan, metric, planning, and embed cards are each limited to 3 per map. The Framework plan unlocks unlimited use. Service account authentication for Power BI, Google Analytics, and Excel 365 is a Governance plan feature.
{% endhint %}

***

#### Find the setup guide for your tool

Each tool has its own setup article with the exact fields and credentials it needs. Pick yours from the matching section below.

<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>Metrics tools</strong></td><td>Google Analytics, Power BI, Excel 365, Google Sheets, Qualtrics</td><td><a href="/pages/Kf9X1ug2MQ8PofLSSbUl">/pages/Kf9X1ug2MQ8PofLSSbUl</a></td></tr><tr><td><strong>Planning tools</strong></td><td>Jira, Asana, Azure DevOps, Linear, Monday.com, Trello</td><td><a href="/pages/1UFmZNSO8c4cjWEYlFUe">/pages/1UFmZNSO8c4cjWEYlFUe</a></td></tr></tbody></table>

***

#### Connect the integration in Account Settings

Every integration connects in the same place: **Account Settings**, on the **Integrations** tab. The connection applies across every workspace in your account, and you only set it up once.

<figure><img src="/files/eB6zAk4d86spcjHZVwE1" alt="Account settings page with the Integrations tab open. A Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button. A Planning integrations section below lists Jira, Azure DevOps, Asana, and Linear, also each with a Set up button."><figcaption><p>Account Settings > Integrations</p></figcaption></figure>

Each tool shows a **Set up** button when it isn't connected yet, or an **Edit** button once it is. Most tools need something prepared in the external service first, either an API token (for tools like Jira, Asana, Linear, and Qualtrics) or sign-in to an account with the right access (for the OAuth-based tools). Your tool's setup article lists the exact steps.

For the OAuth-based tools (Google Analytics, Power BI, Google Sheets), you also choose an authentication method when you connect:

{% columns %}
{% column %}
**Login with your account (OAuth)**

Tied to one person and their access to the data. Best for individual connections or quick testing.
{% endcolumn %}

{% column %}
**Service account**

A server-to-server connection, not tied to a specific person. Best for team-wide integrations that shouldn't break when someone leaves.
{% endcolumn %}
{% endcolumns %}

{% hint style="info" icon="tag" %}
Service account authentication is available on the **Governance** plan.
{% endhint %}

Only one method can be active per integration at a time. After you connect, the tool shows one of these states on the Integrations tab:

* **Connected**, a green banner: the connection is working.
* **Connection Error**, a red banner: the connection failed and needs reconfiguring, usually because credentials are wrong or have expired.
* **Connection Failed**, a red banner: failure caused by something on the external service, for example a plan upgrade required on that tool.
* **Not configured**: the setup form is shown with empty fields.

For switching auth methods, refresh frequency, and what happens on disconnect, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

***

#### Use your integration on a journey map

How the connected data lands on a map depends on the integration type.

{% tabs %}
{% tab title="Metrics" %}
Using a metrics integration is a two-step flow: create a metric, then place it on a map as a metric card. A single metric can be reused across multiple journey maps, and data refreshes on a roughly hourly cycle.

In the metric builder, your connected tool appears in the **Source** dropdown alongside the other metrics tools.

<figure><img src="/files/zHTxnP28I3A8h62aEjUt" alt="The Source dropdown in the metric builder, expanded. The options read Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Metric builder, Source dropdown</p></figcaption></figure>

For the full flow, see:

* [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric)
* [How to choose a metric type](/metrics/how-to-choose-a-metric-type)
* [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards)
  {% endtab %}

{% tab title="Planning" %}
Planning items live in the connected tool (Jira, Asana, Linear, and so on), not in Smaply. On a journey map, open the Add card menu, choose a planning card, and search for the item you want to link. The card then reflects status changes from the source tool automatically.

For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).
{% endtab %}
{% endtabs %}

***

#### Verify the integration is working

A quick end-to-end check confirms the whole pipeline, from credentials to card display.

* **For a metrics integration:** create a small test metric (for example, a single Number pulling a value you can recognise), add it as a metric card on any journey map, and confirm the card renders with real data. If the card is empty or shows an error, open **Account Settings** and check that the integration shows as **Connected** on the Integrations tab.
* **For a planning integration:** add a planning card to a test map, search for a known item in your tool, and confirm the card populates with the expected fields. If the search returns nothing, confirm the integration is still **Connected** and that the credentials reach the projects you're searching.

If the Integrations tab shows **Connection Error** or **Connection Failed**, the credentials have expired or lack the access they need. Re-enter them from your tool's setup article, or check the inline troubleshooting at the bottom of that article.

***

#### What's next

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to use metric cards</strong></td><td>Place and customise metric cards on a journey map</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and add planning items from connected tools</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>First steps for admins</strong></td><td>Broader admin onboarding beyond integrations</td><td><a href="/pages/lfeGHTTNt6pNYxV044Ne">/pages/lfeGHTTNt6pNYxV044Ne</a></td></tr></tbody></table>


# Metrics tools

Connect external metrics data sources to Smaply

Connect a metrics tool once at the account level, and every journey map in your account can show live values from it. Use these integrations to surface KPIs, survey results, and dashboard data on the journey moments where they actually matter.

#### Why connect a metrics tool

* Tie experience moments to real numbers (conversion, CSAT, NPS, churn) without leaving Smaply
* Metrics refresh on a roughly hourly cycle, so journey maps reflect current data
* One connection serves every workspace and every journey map in your account

{% hint style="info" icon="tag" %}
Service account authentication is available on the **Governance** plan for tools that support it. OAuth is available on all plans with metrics integrations.
{% endhint %}

#### In this section

* [**Google Analytics**](/integrations/metrics-tools/google-analytics) - Web traffic, conversion, and user behaviour metrics.
* [**Power BI**](/integrations/metrics-tools/power-bi) - Dashboards, datasets, and tables from your Power BI workspaces.
* [**Excel 365**](/integrations/metrics-tools/excel-365) - Any Office 365 spreadsheet as a metric source.
* [**Google Sheets**](/integrations/metrics-tools/google-sheets) - Flexible connector for any structured spreadsheet data.
* [**Qualtrics**](/integrations/metrics-tools/qualtrics) - Survey responses, experience scores, and feedback metrics.


# Google Analytics

Pull web analytics from Google Analytics into Smaply journey maps

Connect Google Analytics to surface web traffic, conversion, and user behaviour data on the journey moments where they matter, like landing-page bounce rate next to the awareness stage of an e-commerce journey.

#### Why connect Google Analytics

* Ground awareness, consideration, and conversion stages in actual web data
* Update once in GA; see it everywhere in your journey maps

{% hint style="info" icon="tag" %}
Service account auth (recommended for teams) is available on the Governance plan. OAuth is available on all plans with metrics integrations.
{% endhint %}

#### In this section

* [**Set up Google Analytics**](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration) - Connect at the account level using service account or OAuth.
* [**Use Google Analytics in a metric**](/integrations/metrics-tools/google-analytics/how-to-use-google-analytics-in-a-metric) - Add GA data to journey-map metric cards.


# How to set up the Google Analytics integration

Connect Google Analytics so your web traffic data flows into journey map metric cards.

An Admin connects Google Analytics once at the account level. After that, anyone in the workspace can build metrics from your GA properties.

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

#### In this guide

1. [Set up the Google Analytics integration](#set-up-the-google-analytics-integration)
2. [Configure Google Analytics in Smaply](#configure-google-analytics-in-smaply)
3. [Verify the setup](#verify-the-setup)
4. [Use Google Analytics in a metric](#use-google-analytics-in-a-metric)
5. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Google Analytics integration

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FAtfXz6ZuLY4oLHMBYOxK%2Fsetup_google_analytics.mp4?alt=media&token=6d479bc8-4f66-4615-bd28-95ee929878e1>" %}

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

#### Prerequisites

* Admin role at the account level
* A Google account with access to the Google Analytics 4 property you want to connect
* For service account auth: access to a Google Cloud project (you can create one as part of setup)
  {% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Google Analytics**.

<figure><img src="/files/WGPVzrjjsG4FOQfxa3g1" alt="Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right."><figcaption><p>Account settings > Integrations</p></figcaption></figure>

The **Configure Google Analytics** page opens with two options under **Select integration type**: **Service account** (selected by default and marked **Recommended**) and **Login with your Google account (oAuth)**.

<figure><img src="/files/sB8gEkRxIrbIiIdtjtc2" alt="Configure Google Analytics page in the unconfigured state. The left pane shows Select integration type with Service account selected (marked Recommended) and Login with your Google account (oAuth) below it. The right pane shows Configure service account with a Service account file label, the instruction Upload your Google Analytics service account JSON file, a No file uploaded yet empty state, and an Upload File button."><figcaption><p>Configure Google Analytics, unconfigured</p></figcaption></figure>

Pick the authentication method that fits:

* **Service account (recommended)** - Server-to-server, so the connection isn't tied to one person's login. Best when your team works on the same Smaply account.
* **OAuth** - Signs Smaply in as you. Simpler when only one person needs the data.

{% tabs %}
{% tab title="Service account (recommended)" %}
{% hint style="info" icon="tag" %}

#### Plan availability

Service account auth is available on the **Governance** plan only. OAuth auth (the other tab) is available on all plans.
{% endhint %}

A service account is a Google identity that connects Smaply to Google Analytics without being tied to a single person's login. You create the account in Google Cloud, give its email Viewer access to each GA property, download its key file, and upload that file in Smaply.

Keep the **Configure Google Analytics** page open in another tab. You'll come back to it at the end of this flow to upload the key file.

{% stepper %}
{% step %}
**Create a Google Cloud project**

In the [Google Cloud Console](https://console.cloud.google.com), create a new project for the integration. We recommend naming it `Smaply-GA` so the purpose is obvious if you audit projects later.

{% hint style="info" %}
A dedicated project keeps API access organised so you can see at a glance which credentials belong to Smaply.
{% endhint %}
{% endstep %}

{% step %}
**Enable the Google Analytics APIs**

Inside the project, open **APIs & Services > Library** and enable both:

* **Google Analytics Data API**
* **Google Analytics Admin API**

The Data API reads your metric data; the Admin API is what populates the property list in Smaply. Both must be enabled.

{% hint style="warning" %}
These APIs are not enabled by default in new Google Cloud projects. Missing the Admin API is the most common cause of a connection that authenticates but returns an empty property list.
{% endhint %}
{% endstep %}

{% step %}
**Create a service account**

Open **IAM & Admin > Service Accounts** and click **Create Service Account**. Give it a recognisable name (for example, `smaply-ga-reader`) and an optional description.
{% endstep %}

{% step %}
**Grant the service account a role**

When prompted to assign a role, choose **Viewer**. Viewer is enough for Smaply to read GA data and follows the principle of least privilege. Use **Editor** only if you have a specific reason to give the service account write access in Google Cloud.
{% endstep %}

{% step %}
**Create and download a JSON key**

On the service account's detail page, open the **Keys** tab, click **Add key > Create new key**, choose **JSON**, and download the file.

<figure><img src="/files/YLW5enxwReQuKuXnUjTK" alt="Google Cloud Console Service Accounts page with the Keys tab selected, where you create a new JSON key. The page shows an existing key row with creation and expiration dates, alongside Google&#x27;s security-warning banners about downloading service account keys."><figcaption><p>Google Cloud Console > Service Accounts > Keys</p></figcaption></figure>

Google shows a security warning when you download a key. That warning is expected, and the JSON download is the intended path here.

{% hint style="danger" %}

#### **Warning: The JSON key cannot be re-downloaded**

Save the file somewhere secure. If you lose it, you'll need to generate a new key and grant it access in Google Analytics again.
{% endhint %}
{% endstep %}

{% step %}
**Grant the service account access in each GA property**

Copy the service account's email from the same page (it ends in `@<project>.iam.gserviceaccount.com`). In Google Analytics, open **Admin > Property Access Management** for the property you want to connect, add the email, and assign the **Viewer** role.

<figure><img src="/files/f69MCTvaw1C2lqZpwIeY" alt="Google Analytics Property access management showing a service-account email added with the Viewer role, alongside the + button to add access permissions to new users."><figcaption><p>Admin > Property Access Management, service account added as Viewer</p></figcaption></figure>

Repeat for every GA4 property you want available in Smaply. The service account can read a property only after its email is granted access there, so skipping a property leaves it out of the list.

{% hint style="warning" %}

#### **Important: The service account starts with zero visibility into your data**

Granting the project-level Viewer role in step 4 does not give the service account access to any Analytics property. Until you add its email here, the property list in Smaply comes back empty. This is the step users most often miss.
{% endhint %}
{% endstep %}

{% step %}
**Upload the key in Smaply**

Back on the **Configure Google Analytics** page in Smaply, with **Service account** selected, click **Upload File** under **Service account file** and select the JSON key you downloaded.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth" %}
OAuth signs Smaply in as you. The connection inherits whatever GA properties your Google account already has access to, and tokens are tied to your individual permissions in Google.

{% stepper %}
{% step %}
**Choose Login with your Google account (oAuth)**

On the **Configure Google Analytics** page, select **Login with your Google account (oAuth)**. The right pane changes to **Configure oAuth** with a **Connect Google Analytics** heading and button.

<figure><img src="/files/gHFkSELwDYQI2iKZyTwF" alt="Configure Google Analytics page with Login with your Google account (oAuth) selected. The right pane shows Configure oAuth with a Connect Google Analytics heading, the helper text Grant permission for Smaply to access your Google Analytics account, and a Connect Google Analytics button."><figcaption><p>Configure Google Analytics, OAuth selected</p></figcaption></figure>

Click **Connect Google Analytics**. Smaply redirects you to Google.
{% endstep %}

{% step %}
**Sign in and grant access in Google**

Pick the Google account that has access to the GA properties you want to use, then review the permissions on Google's consent screen and click **Allow**. Smaply only needs read-only access to your Google Analytics data (the `https://www.googleapis.com/auth/analytics.readonly` scope).
{% endstep %}

{% step %}
**Verify the connection**

Google sends you back to Smaply. The **Configure Google Analytics** page shows the connected state, with the date the connection was added and a **Disconnect account** option, alongside the properties your account can read.

{% hint style="warning" %}
Smaply refreshes OAuth tokens automatically, so you don't need to sign in again under normal use. If you sign out of Google, revoke Smaply's access in your Google account, or lose access to a GA property, the connection drops and metrics that depend on it stop pulling data. Click **Connect Google Analytics** again from the same page to restore it. For team-wide use, switch to a service account so the connection isn't tied to one person's login.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### Configure Google Analytics in Smaply

Once the connection is established, the **Configure Google Analytics** page lists the GA properties it can read under **Select properties & apps**. For each property you pick which dimensions and metrics to expose, which shapes the choices Editors see when they build a metric.

<figure><img src="/files/q6QxVgPHakMGmH6CYG8T" alt="Connected Configure Google Analytics page. The Select properties &#x26; apps section lists a connected property with a green check, a Configure button, and a delete icon, plus an Add property link below it."><figcaption><p>Configure Google Analytics, connected</p></figcaption></figure>

{% stepper %}
{% step %}
**Add the properties you want**

Each connected property appears with a green check. Click **Add property** to include another property the connection can read. You can come back and add more at any time.
{% endstep %}

{% step %}
**Pick the dimensions to expose**

Click **Configure** next to a property to open the **Configure Google Analytics property** dialog, then open the **Dimensions** tab. Tick the dimensions Editors should be able to group data by (for example, **Country**, **Device model**, **Page title**). Use the search box or category filters to find them. Selected dimensions collect in the **Selected** panel on the right.

<figure><img src="/files/GDf8CrQZf56WELB9vqwd" alt="Configure Google Analytics property dialog on the Dimensions tab. A searchable, category-filtered list of GA dimensions sits on the left, each with a checkbox and description, and a Selected panel on the right lists the chosen dimensions such as Country, Device model, and Page title."><figcaption><p>Configure Google Analytics property, Dimensions tab</p></figcaption></figure>

{% hint style="success" icon="lightbulb" %}

#### **Tip: Keep it lean**

Only enable the dimensions and metrics you actually plan to use. A focused list is easier for Editors to scan when they build a metric.
{% endhint %}
{% endstep %}

{% step %}
**Pick the metrics to expose**

Switch to the **Metrics** tab and tick the metrics to make available (for example, **Active users**, **Sessions**, **Bounce rate**, **Total revenue**). Editors can then build metrics from any combination of the dimensions and metrics you enable here.

<figure><img src="/files/53NBVyEAP38gXRk4NAtT" alt="Configure Google Analytics property dialog on the Metrics tab. A searchable, category-filtered list of GA metrics sits on the left, and the Selected panel on the right lists chosen metrics such as Active users, Bounce rate, Sessions, and Total revenue."><figcaption><p>Configure Google Analytics property, Metrics tab</p></figcaption></figure>
{% endstep %}

{% step %}
**Apply your selections**

Click **Close** at the bottom of the dialog. Smaply applies your selections immediately, so any new metric using this property sees the dimensions and metrics you enabled. Repeat for each property you want to make available.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Open the **Configure Google Analytics** page. If your GA properties appear under **Select properties & apps**, the connection is working. If the list is empty or any check fails, see Troubleshooting below.

***

#### Use Google Analytics in a metric

With the connection verified, anyone in your account with an Editor role can add Google Analytics data to a metric card on any journey map. See [How to use Google Analytics in a metric](/integrations/metrics-tools/google-analytics/how-to-use-google-analytics-in-a-metric) for the field mapping, and [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric) for the full metric flow, including types, charts, and filters.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FySp6MfGck4NB6DeEF2IR%2FConfiguring%20GA%20dimensions%20(2).mp4?alt=media&token=ccce7369-1266-4963-8f4b-65633b55475d>" %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the GA dimension to the journey stage**

If a journey is structured around device type, group by **Device**. If it's regional, group by **Country**. Picking the dimension that matches how the journey is read makes the metric card immediately legible.
{% endhint %}

Google Analytics metrics refresh on an hourly cycle, in line with all Smaply metric integrations. There's no continuous or streaming pull.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Google Analytics** page means Smaply cannot reach GA with the stored credentials.

* For service account: confirm the **Google Analytics Data API** and **Google Analytics Admin API** are both enabled in the Google Cloud project. Check that the service account email is still listed under **Property Access Management** in GA with at least Viewer access.
* For OAuth: click **Connect Google Analytics** again from the Configure page. The token may have expired or been revoked.

</details>

<details>

<summary><strong>The Select properties list is empty</strong> - Properties issue</summary>

The connection succeeds but no properties appear.

* For service account: the service account email hasn't been added to any GA property, or the **Google Analytics Admin API** isn't enabled. Open each GA property's **Admin > Property Access Management**, add the service account email with Viewer access, and confirm the Admin API is on.
* For OAuth: the Google account you signed in with doesn't have access to any GA4 property. Sign in with an account that does, or have the GA owner grant access first.

</details>

<details>

<summary><strong>Smaply finds properties but can't read data</strong> - Permissions issue</summary>

* Check the role granted to the service account or user in **Property Access Management**. Viewer is the minimum. (Older Google Analytics phrases this permission as "Read & Analyze".)
* Confirm the connection points at the GA4 property you expect. Smaply reads through the GA4 Data API.

</details>

<details>

<summary><strong>Can't create a JSON key in Google Cloud</strong> - Org policy issue</summary>

The **Add key** option is disabled, or key creation fails outright.

* Some Google Cloud organisations block service-account key creation through an org policy. Work with your Google Cloud admin to allow key creation for the project, or use the OAuth method instead.

</details>

<details>

<summary><strong>Token expired and metrics stopped pulling</strong> - OAuth issue</summary>

Metrics that worked previously have stopped pulling data and the OAuth connection shows an error.

* Open the **Configure Google Analytics** page and click **Connect Google Analytics** to refresh the token.
* If you regularly hit token expiry, consider switching to a service account. Switching disconnects the current connection, so existing metrics stop pulling until you reconnect.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

* Verify the **Date range** in the metric covers a window where the GA property actually has data.
* Check **Include filters** and **Exclude filters** for conditions that may be filtering everything out.
* Confirm the dimension and metric combination is supported in GA itself. Some GA dimensions can't be combined with some metrics; if GA's own Explore view returns nothing, Smaply will too.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Use Google Analytics in a metric</strong></td><td>Add Google Analytics data to a metric card, including properties, dimensions, and metrics.</td><td><a href="/pages/pE9TkrsSoEgjD48nZSQ3">/pages/pE9TkrsSoEgjD48nZSQ3</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr></tbody></table>


# How to use Google Analytics in a metric

Add Google Analytics data to journey-map metric cards, including properties, dimensions, and metrics field mapping.

Turn a number from Google Analytics, like sessions or page views, into a live chart on any journey map.

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

#### Prerequisites

* The Google Analytics integration is set up at the account level. See [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Google Analytics metric

You can create a Google Analytics metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Name the metric and pick Google Analytics as the source**

In the **Add metric** form, type a name that describes what the metric shows (for example, `Website signups`). In **Source**, pick **Google Analytics**.

<figure><img src="/files/zHTxnP28I3A8h62aEjUt" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, Google Analytics selected</p></figcaption></figure>

If you see a red **Google Analytics setup required** error below the Source field, the integration isn't connected for this account yet. Follow [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration) before continuing.
{% endstep %}

{% step %}
**Pick the metric type**

Open the **Type** dropdown and pick **Series**, **Number**, or **Comparison**. The fields below the Type dropdown depend on this choice, so set it before mapping the Google Analytics fields.

<figure><img src="/files/GArvZmyIYjtTQQy9lc4B" alt="Type dropdown open on the Add metric form, showing Series, Number, and Comparison options, each with a small icon to the left of the label."><figcaption><p>Type dropdown, three metric types</p></figcaption></figure>

For which type fits which question, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).
{% endstep %}

{% step %}
**Map the Google Analytics fields**

With **Series** selected, the form shows a **Date range** field, a **Google analytics metric** selector, and a **Google Analytics dimension** selector. The metric is the number you're plotting; the dimension groups it.

<figure><img src="/files/KNaqHVN11TveI7rnKUYT" alt="Add metric form with Source set to Google Analytics and Type set to Series. The left column shows Name, Source, Type, a Date range dropdown, a Google analytics metric dropdown, a Google Analytics dimension dropdown, and Filters sections for AND and NOT conditions. The right column shows the Default card preview with a chart-type strip and Chart heading and subheading fields."><figcaption><p>Add metric, Google Analytics fields for a Series metric</p></figcaption></figure>

* Pick the number to plot under **Google analytics metric** (for example, **Sessions**, **Page views**, or **Active users**).
* Pick how to group it under **Google Analytics dimension** (for example, **Country**, **Device**, or **Page title**).
* Set a window under **Date range**.

Both selectors list only the metrics and dimensions an Admin chose when connecting the property, so the lists are deliberately short. If the value you need isn't there, ask whoever set up the connection to add it. For what each field means, see [Field mapping](#field-mapping) below.

{% hint style="info" %}

#### **Important: Number and Comparison metrics show different fields**

A **Number** metric drops the series-specific options and may ask for an aggregation, since it resolves to one value rather than a sequence. A **Comparison** metric collects two values to compare. The Google analytics metric and dimension selectors work the same way across all three types.
{% endhint %}
{% endstep %}

{% step %}
**Set the chart options**

In the **Default card preview** panel on the right, pick a default chart type from the strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Number**). Add an optional **Chart heading** and **Chart subheading** for labels above the chart. These settings are the defaults for new metric cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).
{% endstep %}
{% endstepper %}

***

#### Field mapping

Google Analytics organises data as a **Property** that holds **Dimensions** and **Metrics**. The example below walks a **Series** metric, the most common type, showing sessions grouped by country.

* **Property** - A website, mobile application, or device; a container for the data Google Analytics collects. The property is chosen once when the integration is connected, so it isn't a field on the metric form. Every metric you build pulls from a property an Admin already connected.
* **Dimensions** - Attributes used to filter and group your data, such as **Country**, **Device**, or **Page title**. The **Google Analytics dimension** selector lists the dimensions curated at connection time. Picking **Country**, for example, gives one data point per country.
* **Metrics** - Quantitative measurements of activity on your site or app, such as **Sessions**, **Page views**, or **Goal completions**. The **Google analytics metric** selector is the number that gets plotted.

You can narrow the data further with **Filters (items to include)** for AND conditions and **Filters (items to exclude)** for NOT conditions, each pairing a dimension with a value.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the dimension to the journey stage**

Pick the **Google Analytics dimension** that matches what the journey stage is about. A regional journey reads cleanly with the **Country** or **City** dimension; a journey about a specific flow reads better grouped by **Page title** or **Page path**. The metric renders one data point per dimension value, so a focused dimension keeps the chart legible.
{% endhint %}

***

#### Refresh behaviour

Google Analytics metrics refresh on access, not on a timer. When you open the **Metrics** section or load a journey map with a Google Analytics metric, Smaply checks the data and pulls fresh values from Google Analytics only if what it has is more than about an hour old. There's no manual refresh button and no constant background sync.

Because of that hour-long window, events that just happened in Google Analytics may not appear in Smaply immediately. The next time the metric or map loads after the window passes, the values catch up.

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>The metric or dimension dropdown is empty or missing a value you need</strong> - Curated at connection time</summary>

The **Google analytics metric** and **Google Analytics dimension** selectors only list the metrics and dimensions chosen when the property was connected. The list is kept short on purpose, so a value you expect may simply not have been added.

Ask whoever set up the Google Analytics integration to add the metric or dimension you need on the **Configure Google Analytics** page, then reopen the metric form.

</details>

<details>

<summary><strong>No property's data is selectable, or the metric returns nothing</strong> - Access or API issue</summary>

The metric builds but comes back blank, or no Google Analytics data is available to pick from.

* The connection identity may not have access to the property. For service-account auth, the service account email must be granted on the property in Google Analytics under **Admin > Property Access Management**. For OAuth, the signed-in Google account must have that access itself.
* The property may be listing fine but returning no numbers because the **Google Analytics Data API** is disabled in the Google Cloud project. The Admin API populates the property and field lists; the Data API serves the actual values, so one can work while the other doesn't.

Both are connection-side fixes. See [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration).

</details>

<details>

<summary><strong>A metric returns no data despite a valid metric and dimension</strong> - Incompatible pairing (Google Analytics behaviour)</summary>

Some Google Analytics metric and dimension combinations aren't compatible and return nothing, even when each is valid on its own. This is a Google Analytics platform constraint, not a Smaply one.

Edit the metric and try a more standard pairing (for example, **Sessions** by **Country**) to confirm the connection works, then narrow from there.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Set up Google Analytics</strong></td><td>Connect Google Analytics at the account level using service account or OAuth.</td><td><a href="/pages/qVm6oVefSmnvkYdAi5u6">/pages/qVm6oVefSmnvkYdAi5u6</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# Power BI

Pull metrics from your Power BI workspaces into Smaply journey maps

Connect Power BI to surface KPIs from your existing dashboards directly on relevant journey-map stages, like weekly conversion rate on a retail onboarding journey.

#### Why connect Power BI

* Tie experience moments to business metrics (conversion, NPS, churn) without leaving Smaply
* Update once in Power BI; see it everywhere in your journey maps

{% hint style="info" icon="tag" %}
Service account auth (recommended for teams) is available on the Governance plan. OAuth is available on all plans with metrics integrations.
{% endhint %}

#### In this section

* [**Set up Power BI**](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration) - Connect at the account level using service account or OAuth.
* [**Use Power BI in a metric**](/integrations/metrics-tools/power-bi/how-to-use-power-bi-in-a-metric) - Add Power BI data to journey-map metric cards.


# How to set up the Power BI integration

Connect Power BI to bring report and dataset values into journey map metric cards.

An Admin connects Power BI once at the account level. After that, anyone in the workspace can build metrics from your datasets.

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

#### In this guide

1. [Set up the Power BI integration](#set-up-the-power-bi-integration)
2. [Use Power BI in a metric](#use-power-bi-in-a-metric)
3. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Power BI integration

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

#### Prerequisites

* Admin role at the Smaply account level
* A Microsoft Entra ID tenant and a Power BI workspace your organisation uses
* Permission to register an app in Microsoft Entra ID, edit Power BI tenant settings, and add members to your Power BI workspaces
  {% endhint %}

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

#### Plan availability

Connecting Power BI is available on the **Governance** plan.
{% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Power BI**. The **Configure Power BI** page opens, connecting via a service account: a Microsoft Entra ID app registration acting as a non-user identity, so the connection isn't tied to one person's login.

<figure><img src="/files/arNLrGcCPuEXmsHO3mcL" alt="Configure Power BI page in the unconfigured state, headed Power BI Service Account, with a How to setup Power BI service account info panel above empty Tenant ID, Client ID, and Client Secret fields and a Save Service Account button."><figcaption><p>Configure Power BI, unconfigured</p></figcaption></figure>

You register the app, grant it the right Power BI permissions, add it to a security group, give the group access to your workspaces, and enter the three credentials in Smaply. Keep the **Configure Power BI** page open in another tab. You'll come back to it at the end of this flow to enter the credentials.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FFKNTmR4avuV0LF7WVvKy%2FPowerBI_API_Permissions.mp4?alt=media&token=efe55dbe-b132-4dda-ac3a-2e158c7663eb>" %}

{% stepper %}
{% step %}
**Register an app in Microsoft Entra ID**

In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID** and click **+ Add > App registration**.

<figure><img src="/files/TEqzGjcNSAswajCalp6Y" alt="Microsoft Entra ID Add menu with the App registration option highlighted."><figcaption><p>Microsoft Entra ID > + Add > App registration</p></figcaption></figure>

On the **Register an application** page, give the app a recognisable name (for example, `Smaply Power BI connector`), choose **Accounts in this organizational directory only (Single tenant)**, leave the **Redirect URI** blank, and click **Register**.

<figure><img src="/files/LZTPKC1s6ycn2jvjy8fH" alt="Azure Register an application form with a Name field, Supported account types set to single tenant, and an empty Redirect URI section."><figcaption><p>Register an application</p></figcaption></figure>

For full background on app registrations, see [Microsoft's quickstart on registering an application](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app).
{% endstep %}

{% step %}
**Assign API permissions**

On the registered app, open **API permissions** and click **+ Add a permission**. Choose **Power BI Service**, then **Application permissions**, tick **Tenant.Read.All**, and click **Add permissions**.

<figure><img src="/files/ctdXDSqorUftqFvFopS2" alt="Azure API permissions pane with the Request API permissions side panel open. Power BI Service is selected, the Application permissions tab is active, and Tenant.Read.All is shown alongside Tenant.ReadWrite.All under the Tenant group."><figcaption><p>Power BI Service > Application permissions > Tenant.Read.All</p></figcaption></figure>

Back on the **API permissions** page, click **Grant admin consent for \[your tenant]** and confirm. Smaply only needs **Tenant.Read.All**. You can ignore **Tenant.ReadWrite.All**, which the screenshot above also shows ticked.

{% hint style="warning" %}

#### **Important: Without admin consent the connection looks fine but workspaces stay empty**

If the **Admin consent required** column says **Yes** but the **Status** isn't **Granted**, Smaply will authenticate successfully and then return an empty workspace list. The grant button only appears for a tenant admin.
{% endhint %}
{% endstep %}

{% step %}
**Generate a client secret**

In the same app, open **Certificates & secrets** and create a new client secret. Copy the secret **Value** immediately.

{% hint style="danger" %}

#### **Warning: The client secret value cannot be re-shown**

Azure displays the secret value only at creation time. Once you navigate away, only the secret ID stays visible. If you lose the value, generate a new secret.
{% endhint %}
{% endstep %}

{% step %}
**Create a security group and add the service principal**

In Microsoft Entra ID, open **Groups > All groups** and click **New group**. Set **Group type** to **Security**, give the group a recognisable name (for example, `smaply-powerbi`), and add the registered app to the group as a member.

<figure><img src="/files/Xe1nCo7fzkFAMKCoSj9F" alt="Azure New Group form with Group type Security selected, alongside an Add members pane searching for power. The PowerBI Service Account enterprise application is ticked in the results list."><figcaption><p>New security group with the service principal added as a member</p></figcaption></figure>

To find the app in the **Add members** picker, search by the app name you used in step 1.

{% hint style="warning" %}

#### **Important: The group name has to match exactly across three places**

You'll reference this group name again in the Power BI tenant setting (step 5) and on each workspace (step 6). A mismatched character or different casing in any of the three places breaks the connection silently. Pick a name and reuse it verbatim.
{% endhint %}
{% endstep %}

{% step %}
**Enable the Power BI tenant setting for the group**

In the [Power BI Admin Portal](https://app.powerbi.com/admin-portal), open **Tenant settings > Developer settings > Service principals can call Fabric public APIs**. Microsoft previously called this setting **Allow service principals to use Power BI APIs**, so older guides and screenshots may use that name.

Switch the setting to **Enabled**, set **Apply to** to **Specific security groups**, type in the name of the security group you just created (for example, `smaply-powerbi`), and click **Apply**.

{% hint style="warning" %}

#### **Important: This step is the most common reason a setup looks correct but no workspaces appear**

Without this tenant setting enabled for the group, Smaply authenticates but every workspace and dataset list comes back empty. If you're not a Power BI tenant admin, ask whoever is to enable it before continuing. For the authoritative reference, see [Microsoft's documentation on enabling the Power BI service principal](https://learn.microsoft.com/power-bi/enterprise/service-premium-service-principal).
{% endhint %}
{% endstep %}

{% step %}
**Assign the security group to each Power BI workspace**

In Power BI, open each workspace you want Smaply to read. Click **Manage access**, then **+ Add people or groups**, search for the security group by name (for example, `smaply-powerbi`), set the role to **Member**, and click **Add**.

<figure><img src="/files/fxQBV8jobpyZ5zUnqc2r" alt="Power BI workspace Manage access flow shown as a three-step composite: the Manage access tab in workspace settings, the Manage access panel with an Add people or groups button, and an Add people search that returns the smaply-powerbi group with the Member role highlighted in the role dropdown."><figcaption><p>Manage access > + Add people or groups > pick the security group and assign Member</p></figcaption></figure>

The group appears in the **Manage access** list with **Member** next to it.

<figure><img src="/files/bvyMQ8YJQkcLdbudLvz2" alt="Tight crop of the smaply-powerbi entry in the Manage access list with its role set to Member."><figcaption><p>Security group assigned as Member</p></figcaption></figure>

**Admin** also works, but **Member** is the minimum role Smaply needs to read datasets.

{% hint style="warning" %}

#### **Important: Wait 30 to 60 minutes for the assignment to propagate**

Power BI takes 30 to 60 minutes to propagate new workspace access for a service principal. Until propagation finishes, Smaply may show an empty workspace list or **Connection Error** even though the setup is correct. If everything looks right and the integration still doesn't work, wait out the full 30 to 60 minute window before re-checking.
{% endhint %}

Repeat for every workspace you plan to use.

{% hint style="warning" %}

#### **Important: Personal workspaces aren't supported**

A Power BI workspace marked as **My workspace** can't have a security group assigned to it, so Smaply can't read from it. Move the dataset into a shared workspace to connect it.
{% endhint %}
{% endstep %}

{% step %}
**Enter the credentials in Smaply**

Back in Microsoft Entra ID, open the registered app's **Overview** page. Copy the **Application (client) ID** and the **Directory (tenant) ID**.

<figure><img src="/files/ylpwincOCmHLbBDzlY7N" alt="Microsoft Entra ID navigation with Manage > App registrations highlighted alongside the registered app&#x27;s Overview page. The Application (client) ID and Directory (tenant) ID values are highlighted."><figcaption><p>App registrations > Overview, with the two IDs Smaply needs</p></figcaption></figure>

Return to the **Configure Power BI** page in Smaply and paste the values into the three fields:

* **Tenant ID** - The **Directory (tenant) ID** from the app overview.
* **Client ID** - The **Application (client) ID** from the same page.
* **Client Secret** - The secret **Value** you copied when you generated the client secret.

Click **Save Service Account**.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

After saving credentials, open the Configure Power BI page. If your workspaces appear in the picker, the connection is working.

<details>

<summary><strong>Verify end-to-end with the verification tool (<code>powerbi_troubleshooting.zip</code>, Python 3.6+)</strong></summary>

`powerbi_troubleshooting.zip` is a Python 3.6+ script that checks the three exact-match conditions the integration depends on: workspace name, table name, and security group name.

You need Python 3.6 or higher installed:

* **Windows** - [download Python](https://www.python.org/downloads/) and run the installer.
* **Mac** - `brew install python3`
* **Linux** - `sudo apt-get install python3`

Download the tool below, unzip it, and follow the instructions in `test_scripts/README` inside the archive. Run the script after setup completes, read the output carefully, and share it with Smaply support if you escalate.

{% file src="/files/sf0X4h4e5EnEB4mmejI1" %}

</details>

If workspaces don't appear or any check fails, see Troubleshooting below.

***

#### Use Power BI in a metric

With the connection verified, anyone in your account can add Power BI data to a metric card on any journey map. See [How to use Power BI in a metric](/integrations/metrics-tools/power-bi/how-to-use-power-bi-in-a-metric) for the field mapping and dataset selection.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FH3LVqfTRJJxtLWX6U3sQ%2FConnecting%20Power%20BI%20to%20Smaply%20Metrics.mp4?alt=media&token=8c9136b6-c3f1-4bdd-a4e1-548f1ce0bc77>" %}

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Power BI** page means Smaply cannot reach Power BI with the stored credentials. Re-check the **Tenant ID**, **Client ID**, and **Client Secret** values for typos or trailing whitespace, and confirm the client secret hasn't expired in Microsoft Entra ID. If you're inside the propagation window (the first 30 to 60 minutes after assigning workspace access), wait until it elapses before troubleshooting further.

</details>

<details>

<summary><strong>The workspace picker is empty or shows "no workspaces"</strong> - Configuration issue</summary>

The connection succeeds but no workspaces appear in the metric builder. The fix depends on which exact-match constraint slipped:

* **Tenant setting not enabled for the group.** Open the Power BI Admin Portal, **Tenant settings > Service principals can call Fabric public APIs**, and confirm it's enabled and applied to the security group your service principal belongs to.
* **Security group name mismatched across surfaces.** The group's exact name (case included) has to match in three places: the Microsoft Entra ID group itself, the Power BI tenant setting's **Specific security groups** entry, and the **Manage access** assignment on each workspace. A single character off in any of the three breaks workspace listing silently.
* **Propagation wait not elapsed.** Power BI takes 30 to 60 minutes to propagate a new workspace assignment. If you've assigned access in the last 30 to 60 minutes, wait and try again.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

The connection works but the metric returns nothing or values that don't look right.

* Confirm the service principal has been added to the source workspace with at least **Member** access. The workspace can be visible in the picker without the dataset being readable.
* Open the dataset in Power BI and confirm it has been refreshed recently. Smaply reads whatever Power BI has cached, so a failed dataset refresh shows as stale or empty data on the Smaply side.
* Verify the **Workspace**, **Dataset**, and the table or column the metric points at still exist with the same names. Renaming or moving any of them in Power BI breaks the metric until it's re-pointed.

</details>

<details>

<summary><strong>Personal workspaces don't connect</strong> - Edge case</summary>

A Power BI workspace marked as **My workspace** can't have a security group assigned to it, so the service principal can't be granted access.

* Move the dataset into a shared workspace and assign the security group there.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Embed cards</strong></td><td>Embed a Power BI report as live content on a journey map instead of pulling values as a metric.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td></tr></tbody></table>


# How to use Power BI in a metric

Add Power BI data to journey-map metric cards by picking a workspace, dataset, table, and columns to plot.

Turn a Power BI table into a live chart on any journey map.

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

#### Prerequisites

* The Power BI integration is set up at the account level. See [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Power BI metric

You can create a Power BI metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

<figure><img src="/files/5hgIFupRgFtQo65HaIUp" alt="Journey map Add card picker open on a card slot, showing the Basic Cards group (Image, Stage, Icons, Slider) and the Advanced Cards group (Embed, Planning, Metric, Link journey map) plus a Text quick-select row at the top."><figcaption><p>Add card picker on a journey map, Metric under Advanced cards</p></figcaption></figure>

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Open the Add metric form**

In the workspace sidebar, click **Metrics**, then **+ Create metric**. The **Add metric** form opens with the two-column layout: **Metric data source** on the left and **Default card preview** on the right.

<figure><img src="/files/N28ic7pURq7vkaC1Wpp7" alt="Add metric page in the empty state. Left column shows Metric data source heading with Name, Source, Type, and Metric tags fields. Right column shows Default card preview heading with a Preview tile, chart-type chip strip, Chart heading and Chart subheading inputs."><figcaption><p>Add metric, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the metric and pick Power BI as the source**

Type a name that describes what the metric shows (for example, `Employee count by city`). In **Source**, pick **Power BI**.

<figure><img src="/files/cyUl4czvjSuRxKtjkt62" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, all sources listed</p></figcaption></figure>

If you see a pink **Power BI setup required** block below the Source field, the integration isn't connected for this account yet. Click **Setup Power BI** in the block and follow [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration) before continuing.
{% endstep %}

{% step %}
**Set Type to Series**

Open the **Type** dropdown and pick **Series**. Power BI metrics are series only, so this is the only option.

<figure><img src="/files/8D4JLFcrPhyapyxuLpzv" alt="Type dropdown open on the Add metric form with Source set to Power BI. The dropdown shows Series as the only selectable option, with a small line-chart icon to the left of the label."><figcaption><p>Type dropdown, Series only for Power BI</p></figcaption></figure>

If you need a single value or a side-by-side comparison instead of a series, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type) for which sources support which types.
{% endstep %}

{% step %}
**Map the Power BI fields**

Five Power BI fields drive what the metric pulls: **Workspace**, **Dataset**, **Table**, **Data label**, and **Data value**. The screenshots below walk one concrete example: workspace `Smaply Workspace`, dataset `Employee_Sample_Data`, table `EmployeeCountByCityTable`, label column `City`, value column `Value`.

* Pick the Power BI workspace under **Workspace**. Only workspaces the connection has access to appear in the list.
* Pick the dataset inside that workspace under **Dataset**.
* Type the table name into **Table** and click **Enter** next to the field. This is a text field, not a dropdown, and pressing Enter is what loads the table's columns into the next two selectors.
* Pick the column for the chart's categories under **Data label** (for example, `City`).
* Pick the column for the numerical value under **Data value** (for example, `Value`).

<figure><img src="/files/dfIalIIB8oZSxsQYutyo" alt="Smaply Add metric form on the left fully filled in with Name Employee count by city, Source Power BI, Type Series, Workspace Smaply Workspace, Dataset Employee_Sample_Data, Table EmployeeCountByCityTable, Data label City, Data value Value, and a chart preview rendering a bar chart. The right side shows the matching Power BI workspace in app.powerbi.com with the EmployeeCountByCityTable previewed and the City and Value columns visible."><figcaption><p>Add metric form with Power BI fields populated, alongside the source table in Power BI</p></figcaption></figure>

For a deeper reference of how each field maps to objects in Power BI, see [Field mapping](#field-mapping) below.
{% endstep %}

{% step %}
**Set the row cap and chart options**

Under **Number of rows**, set how many rows from the table to pull into the chart. The maximum is 50.

In the **Default card preview** panel on the right, pick a default chart type from the chip strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Table**). Add an optional **Chart heading** and **Chart subheading** if you want labels above the chart. The preview updates as you change the selections. These settings are the defaults for new metric cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

<figure><img src="/files/UGUjfYmud74rA7xlqLxn" alt="Workspace Metrics tab with a populated list showing one metric. Columns are NAME, SOURCE, TYPE, CREATED, UPDATED, USED IN, and TAGS. Search, filter, and + Create metric buttons sit above the table."><figcaption><p>Workspace Metrics tab with a saved metric</p></figcaption></figure>

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).
{% endstep %}
{% endstepper %}

***

#### Field mapping

Each Power BI field in the **Add metric** form points at a specific object in Power BI. The selectors only populate once the field above them is filled in, so work down the form in order.

* **Workspace** - The Power BI workspace that holds the dataset. Smaply lists only workspaces the connection identity can read. Equivalent to a workspace in app.powerbi.com.
* **Dataset** - The dataset inside the chosen workspace. Drives what loads when the table name is entered.
* **Table** - The table inside the dataset. Free-text field, not a dropdown. Type the table name exactly as it appears in Power BI and click **Enter** to load its columns into the next two selectors.
* **Data label** - The column whose values become categories on the chart (the x-axis on a bar or line chart, the slice labels on a pie chart). Example: a `City` column with values like Austin, Beijing, Chengdu.
* **Data value** - The column whose values become the numbers plotted on the chart. Example: a `Value` column with the employee count per city.
* **Number of rows** - Caps how many rows the metric pulls from the table. Maximum 50.

<figure><img src="/files/HZWoNZq0Nr7d84W3GNoq" alt="Diagram with the Add metric form in Smaply on the left and a Power BI table view on the right. Arrows connect the Workspace, Dataset, Data label, and Data value fields in Smaply to a workspace, a dataset, and the corresponding column ticks in Power BI."><figcaption><p>How each Smaply field maps to a workspace, dataset, table, and column in Power BI</p></figcaption></figure>

***

#### Refresh behaviour

Power BI metrics refresh on a rough hourly cycle. When a journey map containing a Power BI metric loads, Smaply pulls fresh values if the last update was more than about an hour ago. There's no manual refresh button. The next on-load check brings the values up to date.

The metric shows whatever the underlying Power BI dataset has cached, so a stalled dataset refresh in Power BI itself appears as stale or empty values in Smaply.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the dataset shape to the journey context**

Pick a dataset shape that matches the journey context. If the journey is regional, a table with one row per region usually reads more cleanly than raw event rows. If the journey is weekly, weekly cohorts read more cleanly than daily values. The metric pulls and renders whatever shape Power BI gives it, so a pre-aggregated table in Power BI usually beats a raw fact table.
{% endhint %}

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>"Power BI setup required" error in the metric form</strong> - Connection not configured</summary>

Picking **Source** = **Power BI** shows a pink block reading "You need to set up the Power BI connection in this workspace before you can use it in metrics."

The connection hasn't been configured for this account, or it was disconnected. Click **Setup Power BI** in the block to jump to the integrations page, then follow [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration).

</details>

<details>

<summary><strong>Workspace, Dataset, or Table dropdowns are empty</strong> - Connection identity lacks access</summary>

The Source dropdown shows Power BI is connected, but the **Workspace**, **Dataset**, or **Data label / Data value** dropdowns come back empty.

* For service-account auth, the connection's service principal hasn't been granted access to the workspace. Check that the security group is assigned the **Member** role on the Power BI workspace, and that the tenant setting **Service principals can call Fabric public APIs** is enabled for the group. If the access was assigned in the last 30 to 60 minutes, give the change time to propagate before re-testing.
* For OAuth auth, the connecting user account doesn't have access to the workspace in Power BI. Sign in to app.powerbi.com as that user and confirm the workspace appears under **Workspaces**.
* The workspace may genuinely have no datasets, or the dataset may have no tables exposed to the connection identity. Open it in Power BI to confirm.

</details>

<details>

<summary><strong>Pressed Enter on Table but Data label and Data value stayed empty</strong> - Table not found</summary>

The **Table** field accepted text and **Enter** was clicked, but the **Data label** and **Data value** dropdowns didn't populate.

* The table name might be off by a character or different in casing. Open the dataset in Power BI and copy the table name exactly as it appears, including any underscores or capitalisation.
* The table might not exist in the chosen dataset. Confirm both the dataset and the table in Power BI before re-entering.
* The connection identity might not have access to that specific table inside the dataset. Confirm dataset-level read access for the service principal or OAuth account in Power BI.

</details>

<details>

<summary><strong>Metric returns no data or unexpected values</strong> - Data mapping or row cap</summary>

The metric saves and shows on a journey map, but the values are blank, wrong, or surprising.

* Confirm **Data label** and **Data value** are pointing at the columns you meant. It's easy to swap a label column for a value column, especially when both are numeric.
* The **Number of rows** cap is 50. If the underlying table has more rows than that, pre-aggregate the data in Power BI so the rows you care about fit within the cap.
* Open the dataset in Power BI and check its last refresh. Smaply reads whatever Power BI has cached, so a failed dataset refresh in Power BI shows as stale or empty values here.

</details>

<details>

<summary><strong>Dataset, Table, or Column renamed in Power BI</strong> - References broken</summary>

A metric that previously worked starts returning errors or no data.

If the dataset, table, **Data label** column, or **Data value** column was renamed or moved in Power BI, the metric's references break until they're re-pointed. Edit the metric, re-pick the renamed objects, and save. The same applies if a workspace was renamed or the dataset was migrated to a different workspace.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Set up Power BI</strong></td><td>Connect Power BI at the account level using service account or OAuth.</td><td><a href="/pages/f9sIHKFz3MDellnzuV0j">/pages/f9sIHKFz3MDellnzuV0j</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# Excel 365

Pull data from Excel 365 workbooks into Smaply journey maps

Connect Excel 365 to bring any spreadsheet data onto your journey maps, like quarterly revenue from a finance workbook next to the purchase stage of a customer journey.

#### Why connect Excel 365

* Reuse your team's existing Excel reports without duplicating data into Smaply
* Update once in Excel; see it everywhere in your journey maps

{% hint style="info" icon="tag" %}
Service account auth (recommended for teams) is available on the Governance plan. OAuth is available on all plans with metrics integrations.
{% endhint %}

#### In this section

* [**Set up Excel 365**](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration) - Connect at the account level using service account or OAuth.
* [**Use Excel 365 in a metric**](/integrations/metrics-tools/excel-365/how-to-use-excel-365-in-a-metric) - Add Excel 365 data to journey-map metric cards.


# How to set up the Excel 365 integration

Connect Excel 365 so values from your workbooks flow into journey map metric cards.

An Admin connects Excel 365 once at the account level. After that, anyone in the workspace can build metrics from the workbooks in your OneDrive or SharePoint.

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

#### In this guide

1. [Set up the Excel 365 integration](#set-up-the-excel-365-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Excel 365 in a metric](#use-excel-365-in-a-metric)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Excel 365 integration

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

#### Prerequisites

* Admin role at the account level
* A Microsoft 365 account with the Excel workbooks you want to use stored in OneDrive or SharePoint
* For service account auth: permission to register an app in Microsoft Entra ID (Azure AD) and grant admin consent for Microsoft Graph permissions
  {% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Office 365 Excel**.

<figure><img src="/files/NwQpxY4swwf92APx6NVB" alt="Configure Excel page in the unconfigured state. The left pane shows Select integration type with Service account selected and marked Recommended, and Login with your Office 365 account (oAuth) below it. The right pane shows Office 365 Service Account with a How to setup Office 365 Excel service account info panel and empty Tenant ID, Client ID, and Client Secret fields above a Save Service Account button."><figcaption><p>Configure Excel, unconfigured</p></figcaption></figure>

The **Configure Excel** page opens with two options under **Select integration type**: **Service account** (selected by default and marked **Recommended**) and **Login with your Office 365 account (oAuth)**. Switching the method later disconnects the current one, so pick the one that fits before you save:

* [**Service account (recommended)**](#service-account-recommended) - Server-to-server access through a Microsoft Entra ID app, so the connection isn't tied to one person's login. Best when your team shares the Smaply account.
* [**OAuth**](#oauth) - Signs Smaply in as one person and reads the Excel files that account can already open. Simpler when only one person needs the data.

{% tabs %}
{% tab title="Service account (recommended)" %}
{% hint style="info" icon="tag" %}

#### Plan availability

Service account auth is available on the **Governance** plan. OAuth auth (the other tab) is available on all plans that include metrics integrations.
{% endhint %}

The service account is a Microsoft Entra ID app registration that connects to your files through Microsoft Graph. You register the app, grant it one Graph permission with admin consent, create a client secret, and enter three credentials in Smaply.

Keep the **Configure Excel** page open in another tab. You'll come back to it at the end to enter the credentials.

{% stepper %}
{% step %}
**Register an app in Microsoft Entra ID**

In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID > App registrations** and click **+ New registration**.

On the **Register an application** page, give the app a recognisable name (for example, `Smaply Office 365 connector`), choose **Accounts in this organizational directory only (Single tenant)**, leave the **Redirect URI** blank, and click **Register**.

<figure><img src="/files/MSc8dSMyyqb6Egk4hDjm" alt="Azure Register an application form with a Name field, Supported account types set to single tenant, and an empty Redirect URI section."><figcaption><p>Register an application</p></figcaption></figure>

For full background on app registrations, see [Microsoft's quickstart on registering an application](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app).
{% endstep %}

{% step %}
**Assign the Microsoft Graph permission**

On the registered app, open **API permissions** and click **+ Add a permission**. Choose **Microsoft Graph**, then **Application permissions**, tick **Files.Read.All**, and click **Add permissions**.

<figure><img src="/files/hGpvff8ECjhRo0kktT8P" alt="Azure Configured permissions table for Microsoft Graph showing Files.Read.All as an application permission that reads files in all site collections, with admin consent required."><figcaption><p>API permissions > Microsoft Graph > Files.Read.All</p></figcaption></figure>

Smaply only needs **Files.Read.All**. The screenshot above also lists **User.Read** (added automatically by Azure) and **User.Read.All**; you don't need to add **User.Read.All** for this integration.

Back on the **API permissions** page, click **Grant admin consent for \[your directory]** and confirm in the dialog.

<figure><img src="/files/R8jGsOom8O03nszmDMjH" alt="Azure Grant admin consent confirmation dialog asking whether to grant consent for the requested permissions for all accounts in the directory, with Yes and No buttons."><figcaption><p>Grant admin consent confirmation</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: Without admin consent the connection authenticates but reads no files**

The grant button only appears for a directory admin. If the **Admin consent required** column says **Yes** but consent isn't granted, Smaply connects and then returns an empty workbook list. Grant consent before relying on the integration.
{% endhint %}
{% endstep %}

{% step %}
**Create a client secret**

In the same app, open **Certificates & secrets**, and on the **Client secrets** tab click **+ New client secret**. Give it a description and an expiry, then click **Add**.

<figure><img src="/files/cBKWNxZW57sB7dhshijo" alt="Azure Certificates and secrets page with the Add a client secret panel open, showing a Description field and a 365 days (12 months) expiry."><figcaption><p>Certificates &#x26; secrets > + New client secret</p></figcaption></figure>

Copy the secret **Value** immediately.

<figure><img src="/files/yoIStmdIZX5CMOCGBcwd" alt="Azure client secrets table after creation, showing the new secret with its Value partly hidden and a copy-to-clipboard control next to it."><figcaption><p>Copy the secret Value before leaving the page</p></figcaption></figure>

{% hint style="danger" %}

#### **Warning: The client secret value cannot be re-shown**

Azure displays the secret value only at creation time. Once you navigate away, only the secret ID stays visible. If you lose the value, generate a new secret.
{% endhint %}
{% endstep %}

{% step %}
**Enter the credentials in Smaply**

Open the registered app's **Overview** page and copy the **Application (client) ID** and the **Directory (tenant) ID**.

Return to the **Configure Excel** page in Smaply and paste the values into the three fields:

* **Tenant ID** - The **Directory (tenant) ID** from the app overview.
* **Client ID** - The **Application (client) ID** from the same page.
* **Client Secret** - The secret **Value** you copied when you created the client secret.

<figure><img src="/files/eJdSuh5Ut1Co67lrKWDt" alt="Configure Excel page with the Service account integration type selected. The right pane shows Office 365 Service Account with empty Tenant ID, Client ID, and Client Secret fields above a Save Service Account button, and a How to setup Office 365 Excel service account info panel above the form."><figcaption><p>Configure Excel, Service account selected</p></figcaption></figure>

Click **Save Service Account**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth" %}
OAuth signs Smaply in as you. The connection reads the Excel files your Microsoft account can already open in OneDrive or SharePoint, and tokens are tied to your individual access.

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

#### Prerequisites

* A Microsoft 365 account with access to at least one Excel file in OneDrive or SharePoint
* If your organisation requires admin approval for third-party app consent, a Microsoft admin available to approve the grant
  {% endhint %}

{% stepper %}
{% step %}
**Choose Login with your Office 365 account (oAuth)**

On the **Configure Excel** page, select **Login with your Office 365 account (oAuth)**. The right pane changes to **Connect Office 365 Excel** with a three-step info panel and the **Connect Office 365 Excel** button.

<figure><img src="/files/qqz3N5gOT7uCWUQPlu4k" alt="Configure Excel page with Login with your Office 365 account (oAuth) selected. The right pane shows Connect Office 365 Excel with a How to setup Office 365 Excel info panel listing three numbered steps and a Connect Office 365 Excel button below."><figcaption><p>Configure Excel, OAuth selected</p></figcaption></figure>

Click **Connect Office 365 Excel**. Smaply redirects you to Microsoft.
{% endstep %}

{% step %}
**Sign in and grant permissions**

Sign in with the Microsoft account that can open the Excel files you want to use in Smaply. On Microsoft's consent screen, review the permissions Smaply requests:

* **Read all files that you have access to**
* **Sign you in and read your profile**
* Optionally, **Consent on behalf of your organisation** (only available to admins)

<figure><img src="/files/kqXnmKHbzo1II3fbvgV8" alt="Microsoft Permissions requested consent screen for the Smaply Office 365 app from More than Metrics GmbH, requesting access to read all files you have access to and to sign you in and read your profile, with Cancel and Accept buttons."><figcaption><p>Microsoft permissions screen for Smaply</p></figcaption></figure>

Click **Accept**. If your organisation requires admin approval for third-party apps, the consent screen tells you to ask an admin instead, and the connection completes once an admin approves it.
{% endstep %}

{% step %}
**Authorise the connection**

Microsoft sends you back to Smaply and the **Configure Excel** page shows the connected state. Smaply refreshes OAuth tokens automatically, so you don't need to sign in again unless the token is revoked.

{% hint style="warning" %}
If you revoke Smaply's access in your Microsoft account or lose access to a file, the connection drops and metrics that depend on it stop pulling data. For team-wide use, switch to a Service account so the connection isn't tied to one person's login.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### Verify the setup

Open the **Configure Excel** page and confirm it shows the connected state. Then create a test metric with **Source** set to **Excel (Office 365)**: if the **Spreadsheet** picker lists your workbooks, the connection is working.

If the picker stays empty or you see a connection error, see Troubleshooting below.

***

#### Use Excel 365 in a metric

With the connection in place, anyone in your account can add Excel 365 data to a metric card on any journey map. See [How to use Excel 365 in a metric](/integrations/metrics-tools/excel-365/how-to-use-excel-365-in-a-metric) for the field mapping and how to pick a workbook and sheet.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Excel** page means Smaply cannot reach Office 365 with the stored credentials.

* For service account: re-check the **Tenant ID**, **Client ID**, and **Client Secret** values for typos or trailing whitespace, and confirm the client secret hasn't expired in Microsoft Entra ID.
* For OAuth: click **Connect Office 365 Excel** again from the Configure page. The token may have expired or been revoked.

</details>

<details>

<summary><strong>The Spreadsheet picker is empty or shows no workbooks</strong> - Permissions issue</summary>

The connection succeeds but no workbooks appear when you build a metric.

* For service account: confirm you granted admin consent for the **Files.Read.All** Microsoft Graph permission. Without the grant, Smaply authenticates but can't read any files.
* For OAuth: confirm the signed-in Microsoft account has access to at least one Excel file in OneDrive or SharePoint.

</details>

<details>

<summary><strong>Microsoft asked for admin approval during OAuth</strong> - Consent issue</summary>

The Microsoft consent screen tells you the app needs admin approval before you can complete the connection.

* Some organisations require an admin to pre-approve third-party app grants. Ask your Microsoft admin to approve Smaply, then return to the **Configure Excel** page and click **Connect Office 365 Excel** again.
* If admin approval isn't an option for your org, use the Service account method instead.

</details>

<details>

<summary><strong>Metrics that worked previously have stopped pulling</strong> - Token revoked</summary>

Metrics that worked before now show errors and stop pulling data.

* For OAuth, the usual cause is the grant being revoked, either by signing out of Microsoft everywhere or by an admin removing the Smaply app. Open the **Configure Excel** page and click **Connect Office 365 Excel** to re-establish the grant.
* If the same person keeps losing the connection, switch to a Service account so it isn't tied to one Microsoft session.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

The connection works but the metric returns nothing or values that don't look right.

* Confirm the workbook and sheet the metric points at still exist with the same names. Renaming or moving a file in OneDrive or SharePoint breaks the metric until it's re-pointed.
* Confirm the data values you mapped still sit in the same columns in the source workbook.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Embed cards</strong></td><td>Embed live external content on a journey map instead of pulling values as a metric.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td></tr></tbody></table>


# How to use Excel 365 in a metric

Add Excel 365 spreadsheet data to journey-map metric cards by picking a workbook, sheet, and the columns to plot.

Turn a column of Excel 365 data into a live chart on any journey map.

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

#### Prerequisites

* The Excel 365 integration is set up at the account level. See [How to set up the Excel 365 integration](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration).
* Editor role at the workspace level.
  {% endhint %}

#### Add an Excel 365 metric

You can create an Excel 365 metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Name the metric and pick Excel 365 as the source**

In the workspace sidebar, click **Metrics**, then **+ Create metric**. Type a name that describes what the metric shows (for example, `Annual salary by employee`), then open the **Source** dropdown and pick **Excel (Office 365)**.

<figure><img src="/files/zHTxnP28I3A8h62aEjUt" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, Excel (Office 365) selected</p></figcaption></figure>

{% hint style="info" %}
The source is labelled **Excel (Office 365)** in this dropdown, even though the integration is listed as **Office 365 Excel** on the account settings page. They are the same connection.
{% endhint %}
{% endstep %}

{% step %}
**Connect Excel 365 first if you see the setup gate**

If a pink **Office365 setup required** block appears below the Source field, the integration isn't connected for this account yet. The metric fields stay hidden until it is.

<figure><img src="/files/moLUd8K6k1aEcB0mUODP" alt="Add metric form with Source set to Excel (Office 365). A pink Office365 setup required block sits below the Source field, reading that you need to set up the Office365 connection in this workspace before you can use it in metrics, with a Setup Office365 link. The right column shows a greyed-out card preview."><figcaption><p>Setup-required gate when Excel 365 isn't connected</p></figcaption></figure>

Click **Setup Office365** in the block and follow [How to set up the Excel 365 integration](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration). Once connected, return here and the spreadsheet fields appear.
{% endstep %}

{% step %}
**Set the metric type**

Open the **Type** dropdown and pick the type that fits what you're showing: **Series** for a column of values plotted as a chart, **Number** for a single headline figure, or **Comparison** for two values side by side. The fields below depend on the type you pick; this guide walks **Series**, the typical choice for charting a column from a sheet.
{% endstep %}

{% step %}
**Pick the workbook and sheet**

Next to **Spreadsheet**, click **Change** to choose an Excel file from your connected Office 365 account. Then pick the relevant tab from the **Sheet** dropdown.

If your data has labelled columns in the first row, check **Make top row headers**. This treats the first row as column names, which is what populates the **Data label** and **Data values** pickers in the next step.
{% endstep %}

{% step %}
**Map the label and value columns**

Two columns drive the chart:

* **Data label** - The column holding the categories or labels for the metric (for example, a `Full Name` column).
* **Data values** - The numeric column to plot (for example, an `Annual Salary` column).

{% hint style="warning" %}

#### **Important: Data values must be numeric to chart**

Only numeric columns render as a chart. If you map a text column to **Data values**, the metric can only be shown as a table, not a bar, line, or pie chart.
{% endhint %}
{% endstep %}

{% step %}
**Set how many rows to pull**

Under **Number of rows**, set how many rows to include. The maximum is 50, so a larger sheet is truncated to the first 50 rows. Check **Select bottom rows** to take the last rows instead of the first, which is useful when the most recent entries are appended at the bottom of the sheet.
{% endstep %}

{% step %}
**Pick chart options and save**

In the **Default card preview** panel on the right, pick a default chart type (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Table**) and add an optional **Chart heading** and **Chart subheading**. The preview updates as you change selections. These are the defaults for new cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card. For placing and customising the card per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).
{% endstep %}
{% endstepper %}

***

#### Field mapping

Excel 365 metrics are column-based: you pick the columns to chart, not a cell range like `A1:B10`. Each field in the **Add metric** form maps to part of your workbook.

* **Spreadsheet** - The Excel workbook, chosen with the **Change** button from your connected Office 365 account. This is a file picker, not a typed path.
* **Sheet** - The tab within that workbook, picked from a dropdown of the file's sheets.
* **Make top row headers** - Treats the first row as column names. Check this when your sheet has a header row so the label and value pickers show meaningful column names.
* **Data label** - The column whose values become the categories on the chart (the x-axis on a bar or line chart, the slice labels on a pie chart). Example: a `Full Name` column.
* **Data values** - The numeric column whose values are plotted. Must be numeric to render as a chart; a text column can only display as a table. Example: an `Annual Salary` column.
* **Number of rows** - Caps how many rows the metric pulls. Maximum 50, taken from the top of the sheet, or from the bottom if **Select bottom rows** is checked.

There is no aggregation step: the metric plots the rows as they are, up to the row cap. To show a summarised figure, pre-summarise the data in Excel and point the metric at the summary column.

***

#### Refresh behaviour

Excel 365 metrics refresh periodically, on the same rough hourly cycle as other metrics integrations rather than streaming live. When a journey map containing the metric loads, Smaply pulls fresh values if the last update was more than about an hour old. There's no manual refresh button.

For how integrations behave across tools, including disconnecting and switching auth, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Excel 365 integration](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>"Office365 setup required" block in the metric form</strong> - Connection not configured</summary>

Picking **Source** = **Excel (Office 365)** shows a pink block reading "You need to set up the Office365 connection in this workspace before you can use it in metrics."

The connection hasn't been configured for this account, or it was disconnected. Click **Setup Office365** in the block to jump to the integrations page, then follow [How to set up the Excel 365 integration](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration).

</details>

<details>

<summary><strong>The chart is empty or shows a table instead of bars</strong> - Data values column isn't numeric</summary>

A chart needs a numeric column under **Data values**. If you mapped a text column there, the metric can only render as a table.

Edit the metric and confirm **Data values** points at a numeric column. If the column looks numeric in Excel but doesn't chart, check it isn't stored as text in the source sheet (a common cause is numbers formatted as text or with stray characters).

</details>

<details>

<summary><strong>Some rows are missing from the chart</strong> - Row cap or row direction</summary>

A metric pulls at most 50 rows. If your sheet has more, only the first 50 are included, or the last 50 if **Select bottom rows** is checked.

For larger sheets, narrow the data in Excel to the rows you care about, or pre-summarise so the meaningful rows fit within the 50-row cap. Use **Select bottom rows** when the most recent entries sit at the bottom of the sheet.

</details>

<details>

<summary><strong>A metric that worked before stopped pulling data</strong> - Workbook or sheet changed</summary>

If the workbook was renamed, moved, or deleted in Office 365, or the sheet or header columns were renamed, the metric's references break.

Edit the metric, click **Change** to re-select the workbook, re-pick the **Sheet**, and re-map **Data label** and **Data values**, then save. If the file is no longer reachable from your connected account, confirm Office 365 access in [How to set up the Excel 365 integration](/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration).

</details>

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Set up Excel 365</strong></td><td>Connect Excel 365 at the account level using service account or OAuth.</td><td><a href="/pages/Ji772sVbgOV8Jn7nlL1N">/pages/Ji772sVbgOV8Jn7nlL1N</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# Google Sheets

Pull data from Google Sheets spreadsheets into Smaply journey maps

Connect Google Sheets to bring any tabular data onto your journey maps, from manual survey results to event attendance numbers, with no transformation needed.

#### Why connect Google Sheets

* Flexible connector for any structured data your team already tracks in Sheets
* Update once in Sheets; see it everywhere in your journey maps

{% hint style="info" icon="tag" %}
Google Sheets is available on all plans, for both service account and OAuth authentication.
{% endhint %}

#### In this section

* [**Set up Google Sheets**](/integrations/metrics-tools/google-sheets/how-to-set-up-the-google-sheets-integration) - Connect at the account level using service account or OAuth.
* [**Use Google Sheets in a metric**](/integrations/metrics-tools/google-sheets/how-to-use-google-sheets-in-a-metric) - Add Sheets data to journey-map metric cards.


# How to set up the Google Sheets integration

Connect Google Sheets so spreadsheet data flows into journey map metric cards.

An Admin connects Google Sheets once at the account level. After that, anyone in the workspace can build metrics from your sheets.

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

#### In this guide

1. [Set up the Google Sheets integration](#set-up-the-google-sheets-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Google Sheets in a metric](#use-google-sheets-in-a-metric)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Google Sheets integration

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

#### Prerequisites

* Admin role at the account level
* A Google account with access to the spreadsheets you want to read
* For service account auth: access to a Google Cloud project (you can create one as part of setup)
  {% endhint %}

{% hint style="info" icon="tag" %}
Available on all plans, for both authentication methods.
{% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Google Sheets**.

<figure><img src="/files/eB6zAk4d86spcjHZVwE1" alt="Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right."><figcaption><p>Account settings > Integrations</p></figcaption></figure>

The **Configure Google Sheets** page opens with two authentication options under **Select integration type**.

<figure><img src="/files/CS2BygXpA5D9CTrsy3Ui" alt="Configure Google Sheets page in the unconfigured state. The left pane shows two integration types: Login with your Google Sheets service account (selected by default) and Login with your Google Sheets account (oAuth). The right pane shows the Configure service account section with a Service account file upload area."><figcaption><p>Configure Google Sheets, unconfigured</p></figcaption></figure>

Pick the authentication method that fits:

* **Service account (recommended)** - Server-to-server, so the connection isn't tied to one person's login. Best when your team works on the same Smaply account.
* **OAuth** - Signs Smaply in as you. Simpler when only one person needs the data.

{% tabs %}
{% tab title="Service account (recommended)" %}
A service account is a Google identity that connects Smaply to Google Sheets without being tied to a single person's login. You create the account in Google Cloud, share each source spreadsheet with its email address, and upload its key file in Smaply.

Keep the **Configure Google Sheets** page open in another tab. You'll come back to it at the end of this flow to upload the key file.

{% stepper %}
{% step %}
**Choose Login with your Google Sheets service account**

<figure><img src="/files/qzQPaaXM2mgujZOMgaCy" alt="Configure Google Sheets page with Login with your Google Sheets service account selected. The right pane shows Configure service account with a Service account file label, the instruction Upload your Google Sheets service account JSON file, and an empty state reading No file uploaded yet. with a + Upload File button."><figcaption><p>Configure Google Sheets, service account selected</p></figcaption></figure>

On the **Configure Google Sheets** page, the **Login with your Google Sheets service account** option is selected by default. The right pane shows the **Configure service account** form where you'll upload the JSON key.
{% endstep %}

{% step %}
**Create a Google Cloud project**

In the [Google Cloud Console](https://console.cloud.google.com), create a new project for the integration. We recommend naming it something like `Smaply-Sheets` so the purpose is obvious if you audit projects later.

{% hint style="info" %}
A dedicated project keeps API access organised so you can see at a glance which credentials belong to Smaply.
{% endhint %}
{% endstep %}

{% step %}
**Enable the Google Sheets API**

Inside the project, open **APIs & Services > Library**, search for **Google Sheets API**, and click **Enable**. Smaply needs this API to read data from any sheet the service account has access to.

{% hint style="warning" %}
The Google Sheets API is not enabled by default in new Google Cloud projects. Skipping this step is the most common cause of "no spreadsheets available" later.
{% endhint %}
{% endstep %}

{% step %}
**Create a service account**

Open **IAM & Admin > Service Accounts** and click **Create Service Account**. Give it a recognisable name (for example, `smaply-sheets-reader`) and an optional description. You don't need to grant the service account any project-level roles, since access is granted per spreadsheet in Google Sheets itself. For full background on service accounts, see [Google's Service Account documentation](https://cloud.google.com/iam/docs/service-account-overview).
{% endstep %}

{% step %}
**Create and download a JSON key**

On the service account's detail page, open the **Keys** tab, click **Add Key > Create new key**, choose **JSON**, and download the file. Note the service account's email address from the same page (it ends in `@<project>.iam.gserviceaccount.com`). You'll need it in the next step.

{% hint style="danger" %}

#### **Warning: The JSON key cannot be re-downloaded**

Save the file somewhere secure. If you lose it, you will need to generate a new key and share spreadsheets with the new email address.
{% endhint %}
{% endstep %}

{% step %}
**Share each source spreadsheet with the service account**

In Google Sheets, open every spreadsheet you want Smaply to read. Click **Share** in the top-right corner of the sheet, paste the service account's email address into the people field, set the access level to **Viewer**, and click **Send** (or **Share**). Repeat for every spreadsheet you plan to use.

{% hint style="info" %}
Sharing a spreadsheet with the service account works the same way as sharing it with any colleague. The service account email just looks like a long email address. If you skip this step, the spreadsheet won't appear in the picker when you build a metric.
{% endhint %}
{% endstep %}

{% step %}
**Upload the key in Smaply**

Back on the **Configure Google Sheets** page in Smaply, click **+ Upload File** under **Service account file** and select the JSON key you downloaded.
{% endstep %}

{% step %}
**Verify the connection**

<figure><img src="/files/e4I5msVJLBvVfzCCqLMM" alt="Configure Google Sheets page in the connected state. A details panel on the right shows Added on with a relative time, Added by with the connecting account name, and a red Disconnect account button. Below the panel a green Success banner reads The Integration has been configured successfully."><figcaption><p>Configure Google Sheets, connected</p></figcaption></figure>

A green **Success** banner confirms the connection. The right pane now shows **Added on** and **Added by** (the service account email for service-account connections), plus a red **Disconnect account** button you can use later if you need to remove the connection.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth" %}
OAuth signs Smaply in as you. The connection inherits whatever spreadsheets your Google account already has access to, and tokens are tied to your individual permissions in Google.

{% stepper %}
{% step %}
**Choose Login with your Google Sheets account (oAuth)**

<figure><img src="/files/GVmAy1gbywqSWpJKCyVP" alt="Configure Google Sheets page with Login with your Google Sheets account (oAuth) selected. The right pane shows Connect Google Sheets with an info panel titled How to setup Google Sheets OAuth listing three numbered steps (Sign in with Google, Grant permissions, Authorize the connection) and a blue Connect Google Sheets button below."><figcaption><p>Configure Google Sheets, OAuth selected</p></figcaption></figure>

On the **Configure Google Sheets** page, choose **Login with your Google Sheets account (oAuth)**. The right pane shows a **Connect Google Sheets** section with a three-step info panel and the **Connect Google Sheets** button.
{% endstep %}

{% step %}
**Click Connect Google Sheets**

Click **Connect Google Sheets**. Smaply redirects you to Google.
{% endstep %}

{% step %}
**Sign in with Google**

Pick the Google account that has access to the spreadsheets you want to use in Smaply. If you're already signed in to multiple Google accounts, choose the one with the right spreadsheet access.
{% endstep %}

{% step %}
**Grant Smaply read access**

On Google's consent screen, review the permissions Smaply is requesting and click **Allow**. Smaply only needs read access to your Google Sheets data.
{% endstep %}

{% step %}
**Verify the connection**

<figure><img src="/files/e4I5msVJLBvVfzCCqLMM" alt="Configure Google Sheets page in the connected state via OAuth. A details panel shows Added on with a relative time, Added by with the connecting user&#x27;s name, and a red Disconnect account button. Below the panel a green Success banner reads The Integration has been configured successfully."><figcaption><p>Configure Google Sheets, connected</p></figcaption></figure>

Google sends you back to Smaply. A green **Success** banner confirms the connection, and the right pane now shows **Added on**, **Added by**, and a red **Disconnect account** button.

{% hint style="warning" %}
OAuth tokens expire periodically. If you sign out of Google, revoke Smaply's access in your Google account, or lose access to a spreadsheet, the connection drops and metrics that depend on it stop pulling data. Click **Connect Google Sheets** again from the same page to restore it.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### Verify the setup

Reopen the **Configure Google Sheets** page from **Account Settings > Integrations**. A green **Success** banner and the **Added on** and **Added by** details confirm the connection is live. To check that your data is reachable, start a new Google Sheets metric and confirm a spreadsheet you shared (service account) or have access to (OAuth) appears when you click **Select file**.

If the connection shows an error or no spreadsheets resolve, see [Troubleshooting](#troubleshooting) below.

***

#### Use Google Sheets in a metric

After the integration is connected, Editors create Google Sheets metrics like any other Smaply metric. In the metric configuration modal, set **Source** to **Google Sheet** and then pick the spreadsheet, sheet, and column layout.

<figure><img src="/files/dJdjBB5qSnZxvUU07nRl" alt="Add metric page with Source set to Google Sheet and Type set to Series. The Source step shows the Google Sheets specific fields: Spreadsheet with a Select file button, Sheet combobox, a Make top row headers checkbox under Header (checked), Data label and Data values dropdowns, a Select bottom rows checkbox under Row selection (unchecked), and Number of rows (max 50) defaulting to 50. The right pane shows a muted default card preview."><figcaption><p>Add metric, Source = Google Sheet, Type = Series</p></figcaption></figure>

For Series and Comparison metrics, the Source step exposes these Google-Sheets-specific fields:

* **Spreadsheet** - Click **Select file** to open Google's spreadsheet picker and pick a sheet you've shared with the connected account.
* **Sheet** - Pick the tab inside the spreadsheet. Disabled until a spreadsheet is selected.
* **Make top row headers** - Treats the first row as column names. Checked by default.
* **Data label** - The column that supplies labels (for example, dates or category names).
* **Data values** - The column that supplies numeric values.
* **Select bottom rows** and **Number of rows (max 50)** - Limit the metric to the most recent rows. Smaply reads up to 50 rows per metric.

For **Number** metrics, the Source step is simpler: pick the spreadsheet and sheet, then enter a single cell reference (for example, `A2`) and optional prefix and suffix (for example, `$` and `%`).

The **Save** button stays disabled until **Spreadsheet**, **Sheet**, and the data fields for your chosen type are all set.

For the full metric flow, including chart types, filters, and how the card behaves on a journey map, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the sheet to the journey context**

If a journey is structured around weekly cohorts, point the metric at a sheet whose rows are weeks. If it's structured around regions, use a sheet with one row per region. Smaply renders what's in the sheet, so the cleaner the sheet's shape matches the journey, the more legible the metric card.
{% endhint %}

Google Sheets metrics refresh on an hourly cycle, in line with all Smaply metric integrations. There's no continuous or streaming pull.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Google Sheets** page means Smaply cannot reach Google Sheets with the stored credentials.

* For service account: confirm the **Google Sheets API** is enabled in the Google Cloud project. Re-upload the JSON key if the file may have been corrupted or replaced.
* For OAuth: click **Connect Google Sheets** again from the Configure page. The token may have expired or been revoked.

</details>

<details>

<summary><strong>The spreadsheet picker is empty or my sheet isn't listed</strong> - Access issue</summary>

The connection succeeds, but Smaply doesn't show the spreadsheet you expected when you click **Select file** during metric setup.

* For service account: the spreadsheet hasn't been shared with the service account email address. Open the spreadsheet in Google Sheets, click **Share**, paste the service account email, set access to **Viewer**, and click **Send**. The sheet appears in Smaply's picker once sharing is in place.
* For OAuth: the Google account you signed in with doesn't have access to that spreadsheet. Make sure the sheet is shared with that account in Google Sheets, or sign in with the account that does have access.

</details>

<details>

<summary><strong>Token expired and metrics stopped pulling</strong> - OAuth issue</summary>

Metrics that worked previously have stopped pulling data and the OAuth connection shows an error.

* Open the **Configure Google Sheets** page and click **Connect Google Sheets** to refresh the token.
* If you regularly hit token expiry, consider switching to a service account. Switching disconnects the current OAuth connection, so existing metrics stop pulling until you reconnect.

</details>

<details>

<summary><strong>Service account lost access to a sheet</strong> - Permissions issue</summary>

A metric that previously worked starts returning no data, even though the connection still looks active.

* The service account was probably removed from the spreadsheet in Google Sheets. Open the sheet, click **Share**, confirm the service account email is still listed with **Viewer** access, and re-add it if missing.
* If the spreadsheet itself was deleted or moved out of a shared drive, Smaply can't reach it. Move the file back or point the metric at a replacement sheet.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

* Check the **Data label** and **Data values** columns in the metric. If headers shifted or columns were reordered in the source sheet, the metric may be reading the wrong column.
* If **Make top row headers** is unchecked but the sheet does have a header row, that row gets read as data. Re-check the box, or remove the header from the sheet.
* If **Select bottom rows** is enabled, confirm **Number of rows (max 50)** is high enough to cover the data range you expect to see.
* Confirm the values in the **Data values** column are numeric. Cells containing text, formulas that return text, or `#REF!` errors won't render as numbers.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Embed cards</strong></td><td>Embed a Google Sheet as live content on a journey map instead of pulling values as a metric.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td></tr></tbody></table>


# How to use Google Sheets in a metric

Add Google Sheets data to journey-map metric cards by picking a spreadsheet, sheet, and the columns to plot.

Turn a column of values in a Google Sheet into a live chart or number on any journey map.

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

#### Prerequisites

* The Google Sheets integration is set up at the account level. See [How to set up the Google Sheets integration](/integrations/metrics-tools/google-sheets/how-to-set-up-the-google-sheets-integration).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Google Sheets metric

You can create a Google Sheets metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Name the metric and pick Google Sheet as the source**

Type a name that describes what the metric shows (for example, `New users by week`). In **Source**, pick **Google Sheet**. The source list labels this option in the singular, **Google Sheet**, even though the integration itself is Google Sheets.

<figure><img src="/files/zHTxnP28I3A8h62aEjUt" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, Google Sheet selected</p></figcaption></figure>

If you see a setup-required block below the Source field instead of the Sheets fields, the integration isn't connected for this account yet. Follow [How to set up the Google Sheets integration](/integrations/metrics-tools/google-sheets/how-to-set-up-the-google-sheets-integration) before continuing.
{% endstep %}

{% step %}
**Pick the metric type**

Open the **Type** dropdown and pick **Series**, **Number**, or **Comparison**. The fields below depend on this choice. A **Series** plots a column of values as a chart, a **Number** shows a single headline value, and a **Comparison** sets two values against each other. The steps below walk a **Series**, the most common choice for sheet data.
{% endstep %}

{% step %}
**Choose the spreadsheet and sheet**

Click **Select file** under **Spreadsheet** and choose the Google Sheet to pull from. Then open the **Sheet** dropdown and pick which tab inside that file to read.

<figure><img src="/files/dJdjBB5qSnZxvUU07nRl" alt="Add metric form with Source set to Google Sheet and Type set to Series. The left column shows Name, Source, Type, a Spreadsheet field with a Select file button, a Sheet dropdown, a Make top row headers checkbox under Header, Data label and Data values column dropdowns, a Select bottom rows checkbox under Row selection, and a Number of rows (max 50) field. The right column shows the Default card preview."><figcaption><p>Add metric, Google Sheet fields</p></figcaption></figure>
{% endstep %}

{% step %}
**Map the columns to the chart**

Turn on **Make top row headers** if the first row of the sheet holds column names, so Smaply reads row 1 as headers rather than data. The **Data label** and **Data values** dropdowns then list columns by name.

* Pick the column for the chart's categories under **Data label** (for example, a `Week` column).
* Pick the numeric column to plot under **Data values** (for example, a `Users` column).

For a field-by-field reference, see [Field mapping](#field-mapping) below.
{% endstep %}

{% step %}
**Set which rows to pull**

Under **Number of rows**, set how many rows to read from the sheet. The maximum is 50.

Leave **Select bottom rows** off to read from the top of the sheet down. Turn it on to read the last rows instead, which is how you grab the most recent entries when new data is appended to the end of a long sheet.
{% endstep %}

{% step %}
**Pick chart options and save**

In the **Default card preview** panel on the right, pick a default chart type from the chip strip and add an optional **Chart heading** and **Chart subheading**. The preview updates as you change the selections. These are the defaults for new cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.
{% endstep %}
{% endstepper %}

***

#### Field mapping

Each field in the **Add metric** form points at part of your sheet. Work down the form in order, since the column dropdowns only list names once the spreadsheet, sheet, and header setting above them are set.

* **Spreadsheet** - The Google Sheet file to pull from. Click **Select file** to choose it.
* **Sheet** - The tab inside that file to read. A spreadsheet can hold several sheets, so pick the one with your data.
* **Make top row headers** - Turn on when the first row holds column names. Smaply then treats row 1 as headers and lists your columns by name in the two fields below, rather than reading row 1 as data.
* **Data label** - The column whose values become the categories on the chart (the x-axis on a bar or line chart, the slice labels on a pie chart). Example: a `Week` column with values like Week 1, Week 2, Week 3.
* **Data values** - The numeric column whose values get plotted. Example: a `Users` column with the count per week.
* **Select bottom rows** - Off reads rows from the top of the sheet; on reads them from the bottom. Use it with **Number of rows** to grab the most recent entries when new data is added to the end of the sheet.
* **Number of rows** - Caps how many rows the metric pulls. Maximum 50.

***

#### Refresh behaviour

Google Sheets metrics refresh on access. When you open the workspace **Metrics** section or a journey map containing the metric, Smaply pulls fresh values if the last update was more than about an hour ago. Data under an hour old isn't re-pulled, and there's no manual refresh button. The next time you open the metric or its map brings the values up to date.

The metric reflects whatever the sheet held at the last pull, so an edit you just made in Google Sheets shows up on the next on-access refresh once the hour window has passed.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Shape the sheet to match the journey**

A sheet with one row per category (one row per week, region, or stage) reads more cleanly than raw event rows. Since the row cap is 50, pre-summarising in the sheet keeps the most meaningful values inside the limit.
{% endhint %}

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Google Sheets integration](/integrations/metrics-tools/google-sheets/how-to-set-up-the-google-sheets-integration) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>Metric shows no data or the columns are empty</strong> - Header or column mapping</summary>

The metric saves but the chart is blank, or the **Data label** and **Data values** dropdowns have nothing to pick.

* Check that **Make top row headers** matches the sheet. If the first row holds column names but the toggle is off (or the reverse), Smaply reads the columns wrong and the value column won't map.
* Confirm **Data values** points at a clean numeric column. Text, blanks, or mixed values in that column show as no data.
* Confirm the chosen **Sheet** is the tab that actually holds the data, not an empty or summary tab in the same file.

</details>

<details>

<summary><strong>Only part of the data shows, or the wrong rows show</strong> - Row cap or row direction</summary>

The chart renders but is missing rows you expected, or shows older entries instead of recent ones.

* The **Number of rows** cap is 50. If the sheet has more rows than that, only the first (or last) 50 are pulled.
* If the newest entries are at the bottom of the sheet and you want those, turn on **Select bottom rows** so the metric reads from the end rather than the top.

</details>

<details>

<summary><strong>A metric that worked before stopped pulling</strong> - Spreadsheet or column changed</summary>

A metric that previously rendered starts returning errors or no data.

If the spreadsheet was renamed, moved, a sheet tab was renamed, or the **Data label** or **Data values** column was removed or reordered, the metric's references break until they're re-pointed. Edit the metric, re-pick the spreadsheet, sheet, and columns, and save. For service-account connections, also confirm the spreadsheet is still shared with the service-account email.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Set up Google Sheets</strong></td><td>Connect Google Sheets at the account level using service account or OAuth.</td><td><a href="/pages/Mo2R4ZAAcgPFfbx1u02N">/pages/Mo2R4ZAAcgPFfbx1u02N</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# Qualtrics

Pull survey and experience data from Qualtrics into Smaply journey maps

Connect Qualtrics to surface survey responses and experience scores directly on journey-map stages, like CSAT next to a support touchpoint or NPS at the end of an onboarding journey.

#### Why connect Qualtrics

* Ground experience moments in real customer feedback
* Single API-token auth means no admin approval flow

{% hint style="info" icon="tag" %}
The Qualtrics integration is available on the **Governance** plan.
{% endhint %}

#### In this section

* [**Set up Qualtrics**](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration) - Connect at the account level using your Qualtrics API token and base URL.
* [**Use Qualtrics in a metric**](/integrations/metrics-tools/qualtrics/how-to-use-qualtrics-in-a-metric) - Add survey data to journey-map metric cards.


# How to set up the Qualtrics integration

Connect Qualtrics so survey response data flows into your journey-map metric cards.

An Admin connects Qualtrics once at the account level. After that, anyone in the workspace can build metrics from your surveys.

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

#### In this guide

1. [Set up the Qualtrics integration](#set-up-the-qualtrics-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Qualtrics in a metric](#use-qualtrics-in-a-metric)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Qualtrics integration

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

#### Plan availability

The Qualtrics integration is available on the **Governance** plan.
{% endhint %}

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

#### Prerequisites

* Admin role at the Smaply account level
* A Qualtrics account with API access
* A Qualtrics API token
* Your Qualtrics base URL (the datacenter host only, for example `iad1.qualtrics.com`)
  {% endhint %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Use a dedicated connector account**

Create a separate Qualtrics user (for example, `smaply-qualtrics@yourcompany.com`) and give it access only to the surveys you want to surface in Smaply. Generating the API token from this account keeps the connection scoped to a known set of surveys and avoids tying it to an individual employee's login.
{% endhint %}

{% stepper %}
{% step %}
**Open the Qualtrics integration in Smaply**

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Qualtrics**.

<figure><img src="/files/41AOLLxk95TgSiwBMZVp" alt="Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right."><figcaption><p>Account settings > Integrations</p></figcaption></figure>

The **Configure Qualtrics** page opens with empty fields for your API token and base URL, plus an inline help block.
{% endstep %}

{% step %}
**Get your Qualtrics credentials**

You need two values from Qualtrics: an API token and your datacenter base URL.

<figure><img src="/files/lf7mqiK8HJLPoKXrx8s9" alt="Configure Qualtrics page in Smaply with empty Qualtrics API token and Qualtrics base URL fields, plus a how-to setup info block above the form."><figcaption><p>Configure Qualtrics, empty form</p></figcaption></figure>

In Qualtrics:

* Log in and navigate to **Account Settings > Qualtrics IDs**. Under **API**, click **Generate Token** and copy the token immediately.
* Take your datacenter base URL from the host part of your Qualtrics web address, for example `iad1.qualtrics.com`, `fra1.qualtrics.com`, or `syd1.qualtrics.com`. Enter the host only, with no `https://` and no path after it.

{% hint style="warning" %}

#### **Important: Save the token before leaving the page**

Qualtrics shows the API token only once. If you navigate away without copying it, you will need to generate a new one.
{% endhint %}
{% endstep %}

{% step %}
**Enter your credentials and save**

Back in Smaply, paste the API token into the **Qualtrics API token** field and the datacenter URL into the **Qualtrics base URL** field, then click **Save Configuration**. Smaply validates the credentials against Qualtrics before storing them.

The token is encrypted at rest and masked in the UI after save. You can edit or delete the configuration later from the same page.
{% endstep %}

{% step %}
**Verify the connection**

A green **Connection established** banner confirms Smaply can reach Qualtrics. The page now shows a **Qualtrics integration details** card with the masked token and base URL, plus **Edit Configuration** and **Delete Configuration** buttons.

<figure><img src="/files/B5TF9gCdRsVf4EEiKLFi" alt="Configure Qualtrics page after a successful connection, showing a green Connection established banner above a Qualtrics integration details card with the base URL and a masked API token, Edit Configuration and Delete Configuration buttons, and a Debug Configuration section below."><figcaption><p>Connection established</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### Verify the setup

To confirm the connection before anyone builds a metric on it, reopen **Account Settings > Integrations** and click **Edit** next to **Qualtrics**. On the **Configure Qualtrics** page, a green **Connection established** banner ("Successfully connected to Qualtrics") means Smaply can reach Qualtrics with the stored credentials.

If you see a red **Connection Failed** or **Connection Error** banner instead, see [Troubleshooting](#troubleshooting) below.

***

#### Use Qualtrics in a metric

Once the integration is connected, Editors create Qualtrics metrics like any other Smaply metric. The metric configuration modal exposes the Qualtrics-specific fields below the standard **Name**, **Source**, and **Type** fields:

* **Survey**: which Qualtrics survey to pull responses from
* **Question**: the survey question whose responses drive the metric
* **Group by**: an option to break the metric down (for example, by response category)
* **Calculation**: how individual responses are aggregated into the displayed value

For the full metric flow, including Number, Series, and Comparison types, chart options, and how the card behaves on a journey map, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the survey question to the journey moment**

Pick the question that maps to the stage you want the metric to sit on. A post-purchase NPS question reads differently on the "Onboarding" stage than on the "Renewal" stage, even when the underlying numbers are the same.
{% endhint %}

Qualtrics metrics refresh on load when the previous update attempt is older than one hour. There is no continuous or streaming pull.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Qualtrics** page means Smaply cannot reach Qualtrics with the stored credentials.

* Confirm the **Qualtrics base URL** is the datacenter host only, with no `https://` and no path (for example `iad1.qualtrics.com`). Pasting the full browser address is the most common cause.
* Re-check the **Qualtrics API token**. Leading or trailing whitespace pasted from a clipboard is a common cause.
* If the Qualtrics user that generated the token has been deactivated, the token stops working. Generate a new token from an active account.

</details>

<details>

<summary><strong>Token rejected during Save</strong> - Authentication issue</summary>

The credentials fail validation when you click **Save Configuration**.

* The token may have been revoked in Qualtrics. Open Qualtrics, generate a new token under **Account Settings > Qualtrics IDs**, and paste the new value into Smaply.
* The Qualtrics account that generated the token may not have **API access** enabled. A Qualtrics Brand Administrator can confirm and enable it.

</details>

<details>

<summary><strong>No surveys appear when configuring a metric</strong> - Surveys issue</summary>

The connection succeeds but the **Survey** dropdown in the metric configuration is empty.

* The Qualtrics user behind the token does not have access to any surveys. Share the surveys with that user in Qualtrics, or generate the token from a user that already has access.
* If you are using a dedicated connector account, confirm that the surveys you expect have been explicitly shared with that account in Qualtrics.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

The metric loads but the values look wrong, empty, or stale.

* Open the metric and check the **Survey**, **Question**, and **Calculation** are still pointing at the right Qualtrics objects. Question IDs change if a question is deleted and re-added in Qualtrics.
* Confirm the survey actually has new responses since the last refresh. Metrics refresh on load when the previous update is older than one hour, so freshly-added responses can take up to an hour to appear.
* If the values are still unexpected, use **Debug Configuration** on the **Configure Qualtrics** page. Pick the affected survey, click **Download survey data**, and send the file to <code class="expression">space.vars.supportEmail</code> for diagnosis.

{% hint style="warning" %}

#### **Important: The debug download contains sensitive data**

The Debug Configuration export includes the raw survey list, survey details, and response JSON for the selected survey. Treat the file as sensitive, share it only with Smaply support, and only download it when support has asked for it.
{% endhint %}

</details>

<details>

<summary><strong>Metrics that worked previously have stopped pulling</strong> - Token revoked</summary>

A previously working integration shows an error and metrics stop updating.

* The most common cause is a revoked or rotated API token in Qualtrics. Generate a new token, open the **Configure Qualtrics** page in Smaply, click **Edit Configuration**, paste in the new token, and save.
* If the Qualtrics account itself has been deactivated, generate the token from a different active account (a dedicated connector account is the most resilient option).

</details>

For wider questions about how integrations behave across tools (refresh frequency, plan availability, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Manage integrations</strong></td><td>Disconnect, edit credentials, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Use Qualtrics in a metric</strong></td><td>Build a metric card from a survey question once the integration is connected.</td><td><a href="/pages/YlBBu3nrg4BHYJ9YcmGk">/pages/YlBBu3nrg4BHYJ9YcmGk</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr></tbody></table>


# How to use Qualtrics in a metric

Add Qualtrics survey responses to journey-map metric cards by picking a survey, question, breakdown, and calculation.

Turn the responses to a Qualtrics survey question into a live card on any journey map.

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

#### Prerequisites

* The Qualtrics integration is set up at the account level. See [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Qualtrics metric

You can create a Qualtrics metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

<figure><img src="/files/gy58S461JBtzpnJ7PEM6" alt="Journey map Add card picker open on a card slot, showing a Text quick-select row, the Basic Cards group (Image, Stage, Icons, Slider), and the Advanced Cards group (Embed, Planning, Metric, Link journey map)."><figcaption><p>Add card picker on a journey map, Metric under Advanced cards</p></figcaption></figure>

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Open the Add metric form**

In the workspace sidebar, click **Metrics**, then **+ Create metric**. The **Add metric** form opens with the two-column layout: **Metric data source** on the left and **Default card preview** on the right.

<figure><img src="/files/9gBD6PbP1ZTxOK0LDhlh" alt="Add metric page in the empty state. Left column shows the Metric data source heading with Name, Source, Type, and Metric tags fields. Right column shows the Default card preview with a Show Preview tile, a chart-type chip strip, and Chart heading and Chart subheading inputs."><figcaption><p>Add metric, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the metric and pick Qualtrics as the source**

Type a name that describes what the metric shows (for example, `Customer satisfaction score`). In **Source**, pick **Qualtrics**.

<figure><img src="/files/jvZaTDGW6c2tmuvhM5ju" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, all sources listed</p></figcaption></figure>

If you see a pink **Qualtrics setup required** block instead of the survey fields, the integration isn't connected for this account yet. Click **Setup Qualtrics** in the block and follow [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration) before continuing.
{% endstep %}

{% step %}
**Pick a metric type**

Open the **Type** dropdown and pick a type. Qualtrics supports **Series**, **Number**, and **Comparison**. The four Qualtrics fields only appear after you pick a type, and they're the same set whichever type you choose.

<figure><img src="/files/Sg6SLjo8QmncCscEFlWH" alt="Type dropdown open on the Add metric form with Source set to Qualtrics. The dropdown lists Series, Number, and Comparison, each with a small icon to the left of the label."><figcaption><p>Type dropdown, Series / Number / Comparison for Qualtrics</p></figcaption></figure>

This guide uses **Series**, which plots the responses as a chart. For which type fits a single headline value or a side-by-side comparison instead, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type).
{% endstep %}

{% step %}
**Map the Qualtrics fields**

Four fields drive what the metric pulls: **Survey**, **Question**, **Group by**, and **Calculation**. Fill them top to bottom, because each one enables the next.

* Pick the survey under **Survey**. Only surveys the connected Qualtrics account can access appear in the list.
* Pick the question whose responses drive the metric under **Question**.
* Under **Group by**, choose how to break the responses down. It defaults to **Choice** (group by answer option); **Month**, **Quarter**, and **Year** group by response date instead.
* Under **Calculation**, choose how responses roll up into the value. It defaults to **Response count**; **Percentage(%) of total** shows each group's share instead.

<figure><img src="/files/M7AYTLPaqeXi6J8WeHl6" alt="Add metric form with Source Qualtrics and Type Series selected. The Qualtrics field mapping is revealed below Type: Survey (enabled), Question (greyed out), Group by (greyed out), and Calculation."><figcaption><p>Qualtrics fields appear once a type is selected</p></figcaption></figure>

For what each field maps to in Qualtrics and the full option lists, see [Field mapping](#field-mapping) below.
{% endstep %}

{% step %}
**Pick the chart options**

In the **Default card preview** panel on the right, click **Show Preview** to render the chart from live data, then pick a default chart type from the chip strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Table**). Add an optional **Chart heading** and **Chart subheading** if you want labels above the chart.

<figure><img src="/files/LlcD279iiD8MNyHGYrGU" alt="Completed Qualtrics metric. The left column shows Survey, Question, Group by Choice, and Calculation Response count filled in. The right column shows a rendered bar chart preview with the chart-type strip (Bar chart selected) and Chart heading and Chart subheading inputs below."><figcaption><p>Completed configuration with a live preview</p></figcaption></figure>

These settings are the defaults for new cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

<figure><img src="/files/OUVHL9KLRwYBUTcyqeM7" alt="Workspace Metrics tab with a populated list showing one metric. Columns are NAME, SOURCE, TYPE, CREATED, UPDATED, USED IN, and TAGS. Search, filter, and + Create metric controls sit above the table."><figcaption><p>Workspace Metrics tab with a saved metric</p></figcaption></figure>

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards).
{% endstep %}
{% endstepper %}

{% hint style="info" icon="tag" %}
On the **Free** plan, metric cards are capped at three per journey map. The **Framework** plan and above lift the cap.
{% endhint %}

***

#### Field mapping

Each Qualtrics field in the **Add metric** form points at a specific object in your survey. The selectors enable in order, so work down the form: **Question** unlocks once you pick a **Survey**, and **Group by** fills in once you pick a **Question**.

* **Survey** - The Qualtrics survey to pull responses from. Smaply lists only surveys the connected Qualtrics account can access. If the list is empty, that account hasn't been given access to any surveys in Qualtrics.
* **Question** - The survey question whose responses drive the metric. The list shows every question in the chosen survey.
* **Group by** - How responses are broken down on the chart. **Choice** groups by answer option (one bar or slice per answer). **Month**, **Quarter**, and **Year** group by when the response came in, which is useful for plotting a trend over time. Defaults to **Choice**.
* **Calculation** - How responses in each group roll up into a value. **Response count** plots the raw number of responses. **Percentage(%) of total** plots each group's share of all responses. Defaults to **Response count**.

For example, to chart how a satisfaction question breaks down by answer, pick the survey, pick the question, leave **Group by** on **Choice**, and leave **Calculation** on **Response count**. The chart then shows one bar per answer option, each bar the number of people who chose it.

<figure><img src="/files/vZhReRDNEw2fVUbFM1Uf" alt="Group by dropdown open on the Add metric form, listing Choice, Month, Quarter, and Year."><figcaption><p>Group by options</p></figcaption></figure>

<figure><img src="/files/jZbrWtEe6GEU2gwqwORY" alt="Calculation dropdown open on the Add metric form, listing Response count and Percentage(%) of total."><figcaption><p>Calculation options</p></figcaption></figure>

Once a survey is selected, the form also shows **Filters (items to include)** and **Filters (items to exclude)**, where you can narrow which responses feed the metric using AND and NOT conditions. These are optional. For the full filter reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric).

***

#### Refresh behaviour

Qualtrics metrics refresh on a rough hourly cycle. When you open the **Metrics** section or a journey map that contains a Qualtrics metric, Smaply pulls fresh responses if the last update was more than about an hour ago. There's no manual refresh button and no continuous or streaming pull, so newly submitted responses can take up to an hour to appear.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the question to the journey moment**

Pick the question that maps to the stage you want the metric to sit on. A post-purchase satisfaction question reads differently on an "Onboarding" stage than on a "Renewal" stage, even when the underlying numbers are the same.
{% endhint %}

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Qualtrics integration](/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>The Survey dropdown is empty</strong> - Connection account lacks survey access</summary>

The Source shows Qualtrics is connected, but no surveys appear in the **Survey** dropdown.

The Qualtrics account behind the connection doesn't have access to any surveys. Share the surveys you want to surface with that account in Qualtrics, then reopen the metric. If you connected with a dedicated account, confirm the expected surveys have been shared with it.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Mapping points at the wrong object</summary>

The metric saves and shows on a journey map, but the values are blank, wrong, or surprising.

Open the metric and check that **Survey**, **Question**, and **Calculation** still point at the objects you meant. It's easy to land on the wrong question, or to leave **Calculation** on **Response count** when you wanted **Percentage(%) of total**.

</details>

<details>

<summary><strong>A metric that worked before has stopped pulling</strong> - Question ID changed in Qualtrics</summary>

A metric that previously returned data starts coming back empty or broken.

Editing a question's text in place is fine, but deleting a question and re-adding it in Qualtrics gives it a new underlying ID, which breaks the metric's link to it. Edit the metric, re-pick the question under **Question**, and save.

</details>

<details>

<summary><strong>New responses aren't showing yet</strong> - Refresh window or no new responses</summary>

The survey has responses in Qualtrics, but the metric looks unchanged.

* The survey may have had no new responses since the last refresh, so the value is genuinely unchanged.
* Metrics refresh on load when the previous update is older than about an hour, so responses submitted in the last hour can take that long to appear. Reopen the map after the window passes.

</details>

If the values still look wrong after checking the mapping, you can send the raw response data to support for diagnosis. In **Account Settings > Integrations > Qualtrics**, the **Debug Configuration** section lets you select the affected survey and click **Download survey data** to export it. This lives on the account-level Qualtrics page, not in the metric builder. Send the file to <code class="expression">space.vars.supportEmail</code>.

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% 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>Set up Qualtrics</strong></td><td>Connect Qualtrics at the account level using an API token and base URL.</td><td><a href="/pages/qSgT2h9D9cKZgrZCWRx3">/pages/qSgT2h9D9cKZgrZCWRx3</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


# Planning tools

Connect external planning tools to link work items in journey maps

Connect a planning tool once at the account level, then search for its work items and add them to journey maps as planning cards, like the live Jira issues for a release sitting next to the journey stage they affect.

#### Why connect a planning tool

* Bring live work items (issues, tasks, tickets) onto journey maps without copying them by hand
* Planning cards reflect the source tool's current status automatically
* One connection serves every workspace and journey map in your account

#### In this section

* [**Set up Jira**](/integrations/planning-tools/how-to-set-up-the-jira-integration) - Connect Jira issues with an Atlassian API token.
* [**Set up Asana**](/integrations/planning-tools/how-to-set-up-the-asana-integration) - Connect Asana tasks with a personal access token.
* [**Set up Azure DevOps**](/integrations/planning-tools/how-to-set-up-the-azure-devops-integration) - Connect Azure DevOps work items with a personal access token.
* [**Set up Linear**](/integrations/planning-tools/how-to-set-up-the-linear-integration) - Connect Linear issues with a personal API key.
* [**Set up Monday.com**](/integrations/planning-tools/how-to-set-up-the-monday.com-integration) - Connect Monday.com items with an API key.
* [**Set up Trello**](/integrations/planning-tools/how-to-set-up-the-trello-integration) - Connect Trello cards by authorizing the Smaply connector.


# How to set up the Jira integration

Connect Jira so your team can link issues to the journey-map steps they affect.

An Admin connects Jira once at the account level. After that, anyone in your workspace can search Jira and link issues to planning cards on any journey map.

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

#### In this guide

1. [Set up the Jira integration](#set-up-the-jira-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Jira in planning cards](#use-jira-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Jira integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A Jira Cloud account with permission to create an API token.
  {% endhint %}

Jira uses a single authentication method: a personal Atlassian API token, plus your Jira site URL and the account email the token belongs to. This works with Jira Cloud only.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FmaxGXiG2wVWx31bOou4v%2Fsetup-jira-api-key.mp4?alt=media&token=ab5f2cd0-751e-4d7b-bc7a-cfe2c23feccc>" %}

{% stepper %}
{% step %}
**Open the Jira integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Jira**. The **Configure Jira** page opens with empty fields for your base URL, account email, and API token.

<figure><img src="/files/K4Ck8GhWWnk1a8JBpmlP" alt="The Configure Jira page in Smaply. A Jira API Configuration form shows three empty required fields labelled Jira Base URL, Jira Account Email, and JIRA API TOKEN, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Jira, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create an API token in Atlassian**

In a new tab, go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and sign in. Click **Create API token**, enter a **Label** so you can recognise it later, and set an expiry date. Click **Create**.

Note your Jira site URL (the address in the form `https://your-domain.atlassian.net`) and the account email the token belongs to. You need all three to connect.

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Atlassian shows the token only once. Click **Copy** and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Jira** page, paste your site URL into **Jira Base URL**, your account email into **Jira Account Email**, and the token into the **JIRA API TOKEN** field. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved details with a green confirmation. Jira is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Jira** page from **Account Settings > Integrations**. A connected integration shows your base URL, account email, and a masked API token, with a green **Connection setup** message reading "Successfully connected to Jira as ...".

<figure><img src="/files/Jq54l8iEHalXgxg7cTxd" alt="The Configure Jira page in Smaply showing a connected integration. The saved Base URL, Email, and masked API Token are listed, with a green Connection setup callout confirming the account is connected to Jira, and Edit Configuration and Delete Configuration actions below."><figcaption><p>Connection established</p></figcaption></figure>

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Jira in planning cards

Once Jira is connected, anyone in your workspace can add a planning card to a journey map, search Jira, and link the issue it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Jira** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The base URL, email, or token is wrong, or they don't belong together. Reopen **Configure Jira**, click **Edit Configuration**, and check each value:

* **Jira Base URL** is the full Cloud address in the form `https://your-domain.atlassian.net`, with no trailing path.
* **Jira Account Email** is the email of the Atlassian account the token was created under.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Atlassian and re-enter all three values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Jira returns nothing for your search. Check that the search text matches an issue you can open in Jira, and that the token's owner has access to that project. The connection runs with that user's Jira permissions, so issues in projects they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

Atlassian API tokens expire on the date set when they were created, and a working Jira connection breaks silently once the token lapses. Tokens that were revoked in Atlassian, or that belonged to a user who lost Jira access, fail the same way.

Create a new token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens), then reopen **Configure Jira**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Issues are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Jira issues appear, the connection uses the token owner's Jira permissions. If a teammate can't find an issue you can see, the token owner may not have access to that project in Jira.

</details>

For questions about how the connection behaves across your account, such as disconnecting Jira or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


# How to set up the Asana integration

Connect Asana so your team can link tasks to the journey-map steps they affect.

An Admin connects Asana once at the account level. After that, anyone in your workspace can search Asana and link tasks to planning cards on any journey map.

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

#### In this guide

1. [Set up the Asana integration](#set-up-the-asana-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Asana in planning cards](#use-asana-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Asana integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* An Asana account you can sign in to and create a Personal access token from.
  {% endhint %}

Asana uses a single authentication method: a Personal access token, plus the Workspace ID of the Asana workspace you want to connect.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FAJYPjkyMAnqfx2Es1fm6%2Fasana_apikey_config.mp4?alt=media&token=1f0fb929-edec-4d69-84f4-1a8dc2261e74>" %}

{% stepper %}
{% step %}
**Open the Asana integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Asana**. The **Configure Asana** page opens with empty fields for your Workspace ID and Personal access token.

<figure><img src="/files/zzGpjU3gRw4yIQUKciTi" alt="The Configure Asana page in Smaply. An Asana API Configuration form shows two empty required fields labelled Workspace ID and Personal access token, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Asana, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a Personal access token in Asana and find your Workspace ID**

In a new tab, sign in to Asana at [app.asana.com](https://app.asana.com), then keep that tab open so the next two links return your data.

To get your token, open [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps). Under **Personal access tokens**, click **+ Create new token**. Enter a token name you'll recognise later, such as `smaply-connector`, tick **I agree to the Asana API Terms**, and click **Create token**.

<figure><img src="/files/Z5R6go8bk7L5KtwFk1e9" alt="The Asana developer console My apps page. The Personal access tokens section has a Create new token button, the Create new token dialog shows a token name and the Asana API Terms checkbox, and the Token details panel shows the generated token with a Copy button and a warning that it won&#x27;t be shown again."><figcaption><p>Asana developer console, creating a Personal access token</p></figcaption></figure>

To get your Workspace ID, open [app.asana.com/api/1.0/workspaces](https://app.asana.com/api/1.0/workspaces). The page returns a short list of your workspaces. Copy the `gid` value for the workspace you want to connect. That number is your Workspace ID.

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Asana shows the token only once. Click **Copy** and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Asana** page, paste the `gid` into **Workspace ID** and the token into **Personal access token**. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows a green confirmation. Asana is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Asana** page from **Account Settings > Integrations**. A connected integration shows your saved Workspace ID and a masked token, with a green **Connection setup** message confirming you're connected to your Asana workspace. From here you can also **Edit Configuration** or **Delete Configuration**.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Asana in planning cards

Once Asana is connected, anyone in your workspace can add a planning card to a journey map, search Asana, and link the task it relates to. The card shows the task's live status and updates as it changes in Asana. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Asana** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The Workspace ID or token is wrong, or the token doesn't have access to that workspace. Reopen **Configure Asana**, click **Edit Configuration**, and check each value:

* **Workspace ID** is the `gid` from [app.asana.com/api/1.0/workspaces](https://app.asana.com/api/1.0/workspaces), with no extra characters. It's a number, not the workspace name.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Asana and re-enter both values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Asana returns nothing for your search. Check that the search text matches a task you can open in Asana, and that it lives in the workspace whose ID you connected. The connection runs with the token owner's Asana access, so tasks they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token revoked</summary>

A working Asana connection breaks if the token is deleted in Asana, or if the user who created it loses access to the workspace. Asana Personal access tokens act on behalf of the person who created them, so the connection depends on that account.

Create a new token at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps), then reopen **Configure Asana**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Tasks are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Asana tasks appear, the connection uses the token owner's Asana access. If a teammate can't find a task you can see, the token owner may not have access to that project in Asana.

</details>

For questions about how the connection behaves across your account, such as disconnecting Asana or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link tasks from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


# How to set up the Azure DevOps integration

Connect Azure DevOps so your team can link work items to the journey-map steps they affect.

An Admin connects Azure DevOps once at the account level. After that, anyone in your workspace can search work items and link them to planning cards on any journey map.

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

#### In this guide

1. [Set up the Azure DevOps integration](#set-up-the-azure-devops-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Azure DevOps in planning cards](#use-azure-devops-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Azure DevOps integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* An Azure DevOps organization and project, with permission to create a personal access token.
  {% endhint %}

Azure DevOps uses a single authentication method: a personal access token, plus your organization and project names. The token carries your own Azure DevOps permissions, so it can only reach work items you can see.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FJf2veCfk8yM8aPMPjt6P%2Fconfigure-azure-devops.mp4?alt=media&token=1b4e543b-2d85-49bf-b483-f2afb9179053>" %}

{% stepper %}
{% step %}
**Open the Azure DevOps integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Azure DevOps**. The **Configure Azure DevOps** page opens with empty fields for your organization, project, and personal access token.

<figure><img src="/files/GIDic6tY0ojtehgLTNyK" alt="The Configure Azure DevOps page in Smaply. An Azure DevOps API Configuration form shows three empty required fields labelled Azure DevOps Organization, Azure DevOps Project, and Personal Access Token, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Azure DevOps, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a personal access token in Azure DevOps**

In a new tab, sign in to your organization at [dev.azure.com/{your-organization}](https://dev.azure.com). Open **User settings** (the gear icon, top right next to your profile avatar) and select **Personal access tokens**, then click **+ New Token**.

In the **Create a new personal access token** dialog, enter a **Name**, pick the **Organization** the token works against, and set an **Expiration** date. Under **Scopes**, choose **Custom defined** and select **Work Items**. **Read** is enough to import items into Smaply. Click **Create**.

<figure><img src="/files/ftHSZMRR6MTT9QkHWCND" alt="The Create a new personal access token dialog in Azure DevOps, with fields for Name, Organization, Expiration (UTC) set to a custom date, and a Scopes choice between Full access and Custom defined."><figcaption><p>Create a new personal access token</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Azure DevOps shows the token only once. Copy it and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Azure DevOps** page, type your organization name into **Azure DevOps Organization**, your project name into **Azure DevOps Project**, and paste the token into the **Personal Access Token** field. Use the organization name (the `{organization}` part of `dev.azure.com/{organization}`), not the full URL. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved details with a green confirmation. Azure DevOps is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Azure DevOps** page from **Account Settings > Integrations**. A connected integration shows your saved organization and project with a masked token, and a green **Connection setup** message confirming you're connected to Azure DevOps, alongside **Edit Configuration** and **Delete Configuration** actions.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Azure DevOps in planning cards

Once Azure DevOps is connected, anyone in your workspace can add a planning card to a journey map, search your work items, and link the one it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Azure DevOps** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The organization name, project name, or token is wrong, or they don't belong together. Reopen **Configure Azure DevOps**, click **Edit Configuration**, and check each value:

* **Azure DevOps Organization** is the organization name on its own (the `{organization}` segment of `dev.azure.com/{organization}`), not the full URL.
* **Azure DevOps Project** matches a project you can open in that organization.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Azure DevOps and re-enter all three values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Azure DevOps returns nothing for your search. Check that the search text matches a work item you can open in Azure DevOps, and that it lives in the project you connected. The connection runs with the token owner's permissions, so work items they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

Personal access tokens expire on the date set when they were created, and a working connection breaks silently once the token lapses. Tokens that were revoked in Azure DevOps, or that belonged to a user who lost access to the project, fail the same way.

Create a new token from **User settings > Personal access tokens** in Azure DevOps, then reopen **Configure Azure DevOps**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>You can't create a token or the Work Items scope is greyed out</strong> - Permission issue</summary>

Configuring the integration in Smaply needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

On the Azure DevOps side, an organization admin can restrict who creates tokens and which scopes they can select. If you can't create a token or can't pick the **Work Items** scope, ask your Azure DevOps admin to allow it for your account.

</details>

For questions about how the connection behaves across your account, such as disconnecting Azure DevOps or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


# How to set up the Linear integration

Connect Linear so your team can link issues to the journey-map steps they affect.

An Admin connects Linear once at the account level. After that, anyone in your workspace can search Linear and link issues to planning cards on any journey map.

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

#### In this guide

1. [Set up the Linear integration](#set-up-the-linear-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Linear in planning cards](#use-linear-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Linear integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A Linear account with permission to create a Personal API key.
  {% endhint %}

Linear uses a single authentication method: a Personal API key minted from your Linear account. There is no separate Connect or OAuth flow.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FKpiQR1ySAm6yZmatzlZy%2Fconfigure-linear-apikey.mp4?alt=media&token=fdb6ba3d-422d-4ae4-91cb-802546aaaced>" %}

{% stepper %}
{% step %}
**Open the Linear integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Linear**. The **Configure Linear** page opens with a single empty **Personal API key** field and a blue help block. The form's intro mentions an organization ID, but there is no organization-ID field to fill in; the Personal API key is all you need.

<figure><img src="/files/hKtcx4o6iNrdXery2lpf" alt="The Configure Linear page in Smaply. A Linear API Configuration form shows one empty required field labelled Personal API key, with a blue help block above listing two setup steps and a Save Configuration button below."><figcaption><p>Configure Linear, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a Personal API key in Linear**

In a new tab, go to [linear.app/settings/account/security](https://linear.app/settings/account/security) and sign in. Under **Personal API keys**, click **Create new API key**, give it a name you'll recognise later (for example, `smaply-connector`), and click **Create**. Copy the generated key.
{% endstep %}

{% step %}
**Enter the key and save**

Back on the **Configure Linear** page, paste the key into the **Personal API key** field and click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved key with a green confirmation. Linear is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Linear** page from **Account Settings > Integrations**. A connected integration shows a masked **Personal API key**, with a green **Connection setup** message reading "Successfully connected to Linear as ...". Because the key is personal, the connection runs as the Linear user who created it.

<figure><img src="/files/wcJuF4p9IkemtCKue60I" alt="The Configure Linear page in Smaply showing a connected integration. A masked Personal API key is listed, with a green Connection setup callout confirming the account is connected to Linear, and Edit Configuration and Delete Configuration actions below."><figcaption><p>Connection established</p></figcaption></figure>

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Linear in planning cards

Once Linear is connected, anyone in your workspace can add a planning card to a journey map, search Linear, and link the issue it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Linear** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The key is wrong, incomplete, or was never copied in full. Reopen **Configure Linear**, click **Edit Configuration**, and paste the key again with no extra spaces. If it still fails, create a fresh Personal API key at [linear.app/settings/account/security](https://linear.app/settings/account/security) and enter the new one.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Linear returns nothing for your search. Check that the search text matches an issue you can open in Linear, and that the key's owner has access to that team. The connection runs with that user's Linear permissions, so issues in teams they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Key revoked</summary>

A working Linear connection breaks if the Personal API key is deleted in Linear, or if the user who created it loses access to the relevant teams.

Create a new key at [linear.app/settings/account/security](https://linear.app/settings/account/security), then reopen **Configure Linear**, click **Edit Configuration**, and paste in the new key.

</details>

<details>

<summary><strong>Issues are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Linear issues appear, the connection uses the key owner's Linear permissions. If a teammate can't find an issue you can see, the key owner may not have access to that team in Linear.

</details>

For questions about how the connection behaves across your account, such as disconnecting Linear or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


# How to set up the Monday.com integration

Connect Monday.com so your team can link items to the journey-map steps they affect.

An Admin connects Monday.com once at the account level. After that, anyone in your workspace can search Monday.com and link items to planning cards on any journey map.

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

#### In this guide

1. [Set up the Monday.com integration](#set-up-the-monday.com-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Monday.com in planning cards](#use-monday.com-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Monday.com integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A Monday.com account with access to the boards you want to link from.
  {% endhint %}

Monday.com uses a single authentication method: a personal API token. The token carries the permissions of whoever creates it, so connect with a user who can see the boards your team needs.

{% stepper %}
{% step %}
**Open the Monday.com integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Monday.com**. The **Configure Monday.com** page opens with an empty **API Key** field and a help block summarising what you need to do next.

<figure><img src="/files/LY79LTWt5llR5TxangTO" alt="The Configure Monday.com page in Smaply. A Monday.com Configuration form shows one empty required field labelled API Key, with a blue help block above listing four setup steps and a Save Configuration button below."><figcaption><p>Configure Monday.com, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Get your personal API token from Monday.com**

In a new tab, sign in to Monday.com. Click your profile picture, choose **Developers**, then open the **Developer Center**. Under **My Access Tokens**, click **Show** to reveal your token and **Copy** it.

<figure><img src="/files/tDGb6c09YhVcZPZe0xg9" alt="The Monday.com Developer Center on the API token page. The personal API token is masked, with Regenerate, Copy, and Show buttons to its right and a note advising you to keep the token secret."><figcaption><p>Monday.com Developer Center, API token</p></figcaption></figure>

You can also go straight to `https://YOUR-TEAM.monday.com/apps/manage/tokens`, swapping in your own Monday.com subdomain for `YOUR-TEAM`. Account Admins have a second route: profile picture > **Administration** > **Connections** > **Personal API token**.
{% endstep %}

{% step %}
**Enter the API key and save**

Back on the **Configure Monday.com** page, paste the token into the **API Key** field. Monday.com calls it a token and Smaply calls it an API key, but it is the same value. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows a green confirmation. Monday.com is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Monday.com** page from **Account Settings > Integrations**. A connected integration shows a green **Connection setup** message reading "Successfully connected to Monday.com as ...", along with **Edit Configuration** and **Delete Configuration** actions.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Monday.com in planning cards

Once Monday.com is connected, anyone in your workspace can add a planning card to a journey map, search Monday.com, and link the item it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Monday.com** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The token is wrong or was pasted with extra characters. Reopen **Configure Monday.com**, click **Edit Configuration**, and paste the token again from the Monday.com Developer Center with no leading or trailing spaces. If it still fails, regenerate the token in Monday.com and enter the new one.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Monday.com returns nothing for your search. A personal token only reaches the boards its owner can open in Monday.com, so items on boards they can't see won't appear. Check that the search text matches an item the token's owner can access.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token regenerated or revoked</summary>

Regenerating a token in Monday.com issues a new one and breaks any connection still using the old token. The same happens if the token's owner loses access to the boards.

Copy the current token from the Monday.com Developer Center, then reopen **Configure Monday.com**, click **Edit Configuration**, and paste it in.

</details>

<details>

<summary><strong>Items are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Monday.com items appear, the connection uses the token owner's permissions. If a teammate can't find an item you can see, the token owner may not have access to that board in Monday.com.

</details>

For questions about how the connection behaves across your account, such as disconnecting Monday.com or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link items from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


# How to set up the Trello integration

Connect Trello so your team can link cards to the journey-map steps they affect.

An Admin connects Trello once at the account level. After that, anyone in your workspace can search Trello and link cards to planning cards on any journey map.

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

#### In this guide

1. [Set up the Trello integration](#set-up-the-trello-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Trello in planning cards](#use-trello-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Trello integration

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

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A Trello account you can sign in to.
  {% endhint %}

Trello uses a single authentication method. Rather than asking for an API key, Smaply opens Trello's own authorization page for its hosted **Smaply connector** app. You approve read-only access, Trello hands back a token, and you paste that one token into Smaply.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2F0Hz2fxmYHPzql9qe4oJG%2Ftrello-apikey-configuration.mp4?alt=media&token=65265add-2fd5-4ea4-9bca-ba1750bab510>" %}

{% stepper %}
{% step %}
**Open the Trello integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Trello**. The **Configure Trello** page opens with a single **Token** field and a help block linking to Trello's authorization page.

<figure><img src="/files/TSOxtuEcAxJGlJcNaKWd" alt="The Configure Trello page in Smaply. A Trello Configuration form shows one empty required field labelled Token, with a blue help block above explaining to generate a token by authorizing the Smaply connector app, and a Save Configuration button below."><figcaption><p>Configure Trello, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Authorize Smaply and copy your token**

In the help block, click the link in **Step 1** to open Trello's authorization page in a new tab. Sign in to Trello if prompted.

The page asks whether to give the **Smaply connector** access to your account. The connector requests read-only access: it can read your boards, Workspaces, and profile name, and it cannot post comments, see your email, or change anything in Trello. Approve the request, and Trello shows a token.

<figure><img src="/files/m2E04lt2RX3eg94ZZxN5" alt="Trello authorization screen asking whether to give the Smaply connector app access to your account. It lists the read-only permissions the connector will have, such as reading your boards and Workspaces, and the actions it will not be able to take, such as making comments or seeing your email."><figcaption><p>Trello authorization, Smaply connector</p></figcaption></figure>

Copy the token Trello displays.
{% endstep %}

{% step %}
**Paste the token and save**

Back on the **Configure Trello** page, paste the token into the **Token** field and click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved token with a green confirmation. Trello is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Trello** page from **Account Settings > Integrations**. A connected integration shows a masked **Token** with a green **Connection setup** message reading "Successfully connected to Trello as ...", plus **Edit Configuration** and **Delete Configuration** actions.

<figure><img src="/files/P55oGHCPzc62tL1Uo397" alt="The Configure Trello page in Smaply showing a connected integration. The saved Token is masked, with a green Connection setup callout confirming the account is connected to Trello, and Edit Configuration and Delete Configuration actions below."><figcaption><p>Connection established</p></figcaption></figure>

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Trello in planning cards

Once Trello is connected, anyone in your workspace can add a planning card to a journey map, search Trello, and link the card it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards).

***

#### Troubleshooting

The **Configure Trello** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The token is wrong, incomplete, or was never authorized. Reopen **Configure Trello**, click **Edit Configuration**, and paste the token again with no extra spaces. If you no longer have it, run the authorization step again to generate a fresh token, then paste the new one and save.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Trello returns nothing for your search. Check that the search text matches a card you can open in Trello, and that the account you authorized can see the board it lives on. The connection runs with that account's Trello access, so cards on boards it can't reach won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

The connector token can be revoked from your Trello account's connected-apps settings, and a working connection breaks once it's removed. Revoking the Smaply connector in Trello, or losing access to the boards it could read, fails the same way.

Run the authorization step again to generate a new token, then reopen **Configure Trello**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Cards are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Trello cards appear, the connection uses the access of the account you authorized. If a teammate can't find a card you can see, that account may not have access to the board it's on in Trello.

</details>

For questions about how the connection behaves across your account, such as disconnecting Trello or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link cards from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>




---

[Next Page](/llms-full.txt/1)