---
title: "Workspaces and navigation"
url: https://developers.dagio.ai/workspaces/
---

# Workspaces and navigation

   
                                  
                                                                     
                  
             
         
   

## Personal Spaces outside applications

Use the chevron to the right of each breadcrumb item to browse its contents without returning to
the collection. Lists load when opened and offer **Load more** when needed. Select an item to
navigate; Escape or a click outside closes the list. Active application buttons appear after
**Commands** in the compact topbar, before **Settings**.

Add **Communication** from **Portfolio → New application → Communication**. This optional
application provides the people directory, call invitations and sharing actions across Surface.
Without an active installation, its buttons are absent. Choose **⋯ → Uninstall** to deactivate it;
**Organizations** and **Members** remain managed in **Settings**. The AI chat is independent.
A system application is supplied by Surface and does not open a Model in Builder.

Data, Knowledge, Content and Worker Spaces can be created without an application. Each keeps its
own settings, namespace and versioned content in the authenticated tenant. Data Fields and views,
Knowledge/Content labels, instructions and Actions remain part of its configuration. The shared
Builder configuration interface will be connected separately; it is not available for personal
Spaces yet. Existing Surface editors, history and access checks remain shared.

In **Data**, **Knowledges**, **Contents** or **Workers**, open a Space card's **⋯** menu.
Choose **Archive** to remove it from **Active**, then **Archived → ⋯ → Unarchive** to reopen it.
**Move to trash** asks for confirmation. In **Trash**, choose **⋯ → Restore**; a previously archived
Space returns to Archived. These operations preserve contents and history. Archived and trashed
Spaces cannot be opened until restored; this menu offers no permanent deletion.

## Choose a Surface layout

When creating a Surface, choose **Page**, **Slide** or **Board** from its layout cards. This choice
cannot be changed after creation. Page grows vertically; Slide uses fixed-size slides; Board
provides a free infinite canvas. The same admitted objects and layout containers remain reusable.

In Board and Slide, the compact icon rail provides insertion tools; **+** opens Checklist and the
other tools. Tooltips identify each icon. The bottom **Board** menu controls the background, with
width and height available only in Slide. **Slides** opens the right sidebar with compact thumbnails and slide operations. Drag a thumbnail before or after another to reorder slides; the active slide stays selected. Edit **x** directly
in the bottom **x / y** counter, then press Enter or leave the field to select that slide. Page has no bottom toolbar. Reading hides the Canvas
toolbars; **History** is available from the Surface's **⋯** menu.

Page opens a white, continuous document. Its rail contains **Rich text**, **Table**, **Board**,
**Kanban**, **Calendar**, **Timeline**, **Gantt** and **Layout**. Blocks stack at the full width of
their parent. Layout offers **2 columns**, **3 columns** and **Main + right column**. Board provides
free placement inside a separate block; use its bottom handle to change its height.

The Page header offers **View**, **Edit** and **Layout**. View displays content without editing
borders or tools. Edit shows component toolbars without block borders and lets you write without moving the stack. Layout lets you
insert and move the same components in a smaller preview with gray structural borders. View/Edit
use the full available width and natural content height. A Board exposes one bottom height grip;
document and Data blocks grow automatically. Surface actions sit above the mode switcher, and
Surface tags follow the last block. Pending input is prepared before
switching modes. A Data record keeps its usual Save action.

Each Page block has an optional title and tags. Its menu offers stack ordering rather than
free-position alignment. Rich text opens the full document editor and its toolbar. An active Board
has its own contextual tools inside the Page.

An unconfigured Data view opens its existing Data Space and Field mapping controls. Configured
views retain their source and shared filters, sorting and grouping. The block saves its Query;
records remain in their source Space with its access rules. Saved [Data Views](https://developers.dagio.ai/queries/#data-sources-data-views-and-layouts)
are managed separately from collection actions; binding these saved definitions to Surface blocks
remains to connect. Export of embedded live Data views is unavailable until their full projection is supported.

In **Portfolio**, use the application’s **⋯** menu. Private applications offer **Archive** and
**Move to trash**, with **Unarchive** and **Restore** in the corresponding tabs. Installed
applications offer **Update** and **Uninstall**. Updates prepare a draft in Builder for review before
publication; they do not silently replace the active application. Uninstall affects the selected
instance and retains its data and history. **Marketplace** opens the shared catalogue of accepted applications.

## Shared Settings

Open **Settings** beside Commands, or use **Ctrl+,**. **Surface** contains **Profile**, **Plan** and
**Graph**. Profile and Plan show your current account and subscription; they are also accessible from
the avatar menu. Graph preferences save automatically to your account and reload on other devices
when Surface opens or regains focus. A save conflict remains visible; **Reload saved settings**
reloads the server values. **Applications** groups the Settings pages declared by your
active private and installed applications, even when another application is open. An application without declared pages
does not add an empty entry. Use **More applications** when more pages are available.

The shared **Upgrade plan** window is available from the account menu and **Settings → Plan**.
**Continue to account** opens the configured account website; opening this window does not change
your subscription or permissions.

The left Workspace rail has a separate settings icon. It opens **Workspace → Settings**, where you
can rename the selected Workspace and choose its icon from the Surface library or upload a private
PNG, JPEG, GIF or WebP image up to 5 MB. **Use initial** restores its first letter. The saved icon
appears in the rail. Account and device preferences remain in the global Settings
panel. On Free, **Add Workspace** explains the one-Workspace limit and opens the shared Upgrade
window. These management controls do not move applications or Spaces between Workspaces.

**Workspace → Members** lists display names, e-mail addresses, account types, roles and statuses.

With caching enabled, previously loaded Workspaces, members and icons appear from your account’s
cache on this device, then refresh in the background. Changes still require current permissions
verified by the server.
Filter the list or sort it using its headers. The menu beside a name edits the display name in
this Workspace, changes the role, or removes access. Roles are **Guest** (read-only), **Member**
(collaboration), and **Owner** (administration). Multiple equal Owners are supported; the last one
cannot be removed or demoted; **Change role** and **Remove from Workspace** are disabled for that Owner. Free and Plus invite Guests. Member and Owner roles require Teams or
higher on the participating accounts; choosing an unavailable role opens Upgrade.

Full name and e-mail remain account-owned and disabled in the member profile dialog.
**Display Name (optional)** is a Workspace alias; when empty, Workspace labels use Full name.

**Invite member → E-mail** creates a nominative Guest or Member invitation. **Invitation link**
creates a reusable Guest link with a Copy button and no e-mail field. Invitations expire after
seven days and can be revoked. Each Workspace has five Guest seats, including pending nominative
invitations; links check capacity at each acceptance. Removal triggers an e-mail; a failed send can
be retried using **Retry notification**. Roles do not change subscriptions or automatically share
applications and Spaces.

Closing Settings or changing pages with unsaved changes opens **Discard changes**. Cancel keeps
the draft; Discard changes restores the saved values before leaving. In-flight saves must finish first.

Application pages use **Save changes** and store their values in that application instance. Save or
discard unsaved changes before switching pages or closing Settings. These values do not change the
published application definition. Commands can also open a discovered Settings page directly.

## Compose your environment

A Workspace applies a Model to a work domain. Install Clients, then add Quotes when that need appears. Both apps keep their views and data; configure their relationship after installation.

In **Marketplace**, **Install application** installs the exact published version in your profile. It does not ask for a Workspace name or create a Workspace, Space or instance data. **New Workspace** is a separate action for creating an instance from an installed application.

You can leave Marketplace or close an application definition while it is loading; doing so neither
activates the application nor creates a Workspace.

In the topbar's **Commands** field, type **Marketplace** and choose **Open Marketplace**. Start typing
directly in the field, or focus it with **Ctrl+P**. Settings and your account avatar remain on its right;
the avatar opens your signed-in identity and **Sign out**.

Commands follow your current context: the open Space, its view and your selection. A selected row
can offer different operations from an open document. Unavailable commands explain why they cannot
run. While Builder is open, Commands offers Builder operations; closing it restores the current
view's commands. Choosing a command uses the same operation and confirmations as its button.
**Applications** and **Flows** separate discovery. **Manage** shows active installed items for the current
profile in a table with name, description, publisher, version and status. The installed version can
differ from the latest published version; the table lists definitions, not your Workspace instances.

In **Manage**, open the application's **⋯** menu and choose **Uninstall**. Confirm to disable new creations; existing Workspaces and their data are kept. The active list refreshes after confirmation. Only an authorized profile owner can remove a non-system application.

**Install application** activates only the application in your profile and refreshes its installation status; a Flow retains
its explicit selection journey. System Models keep their platform role and offer no
application-creation action. Check the publication and its requirements: a catalogue listing does
not grant access to another user's data.

Activating a version in the account requires an owner of that account. If your access allows
Workspace creation but not application activation, ask that owner to activate it. Reading the
definition does not expand your permissions.

If the definition cannot be loaded, **Retry** reads that exact definition again. When activation
is confirmed but its refresh fails, retrying reads the definition without repeating activation.
Before submitting creation confirmation, **Change my choices** returns to the retained name and
content selections; review them again before confirming. This change is no longer offered for a
submitted creation whose outcome is still unknown.

After creation is confirmed, Surface finishes opening the Workspace and refreshing the account.
If this step fails, **Open Workspace** resumes opening without creating another instance. Wait
for an opening already in progress to finish before starting another action.

If Marketplace or the application picker cannot load the catalogue, **Retry** repeats the same
search and requested page. This read does not activate a Model or create a Workspace. An unavailable
catalogue is not an empty catalogue.

When preparing a new application's Flow knowledge, explicitly choose an activated Flow definition
and one compatible new Work Space offered by that application. Surface proposes the Flow's current
knowledge references; select the ones to retain, or explicitly retain none. Review the destination,
source versions and confirmation before creating the Workspace. This adds reference Links, not
copies of the notes or new access permissions. An existing reused Space is not silently changed,
and later changes to the Flow's references do not rewrite this confirmed selection.

In **Settings → Models**, installing a published Model makes it and its guide available in the account. It does not create a Workspace or upgrade existing ones. If Surface offers several accounts, first choose the one where you want to work; its roles and access still apply.

| Setting    | Expected values                            | Description                          |
| ---------- | ------------------------------------------ | ------------------------------------ |
| Name       | A readable label, such as Clients          | Name shown in navigation             |
| Portfolio  | A Portfolio you can access                 | Shared Workspace context             |
| Model      | A catalog definition or one of your Models | Initial app structure                |
| Access     | Authorized members and roles               | People who can read or change it     |
| Navigation | Destinations declared by the Model         | Home, collections, work and contents |

## Find an object

Home presents useful entry points: open a collection, create an object or resume work. Workspace navigation uses its business vocabulary. In Clients, **Active clients** opens a collection; choosing North Studio opens a record; **Prepare proposal** opens the associated work.

Start cards show their Action's name and description. Choosing a card opens its preparation; it
does not automatically confirm execution. A card without access to that preparation remains
readable, without a launch command.

Navigation preserves the context needed to return to the collection. Opening a related quote changes the object without copying the quote into the client record.

If input or a comment prevents closing a record opened from a table, Surface keeps the panel and
its work in place. Finish or correct that input before trying to close it again; closing does not
automatically save content or resend a comment.

When you open a row from a list inside a record, the return action names that parent record. For
example, open a Knowledge category, choose an entry, then return to that same category. Surface
reads its current accessible contents with your submitted search and filters; saving the entry
does not force you to restart from the category index. If access changes, the return explains
that the destination is unavailable instead of showing a previously loaded copy.

The **Portfolio** brings together your application Workspaces. The secondary **My content** entry at the bottom of navigation on wider screens opens the Spaces you can access: attached to an app, shared or with no visible linked Workspace. Open a Space directly or find the visible Workspaces that use it; this is neither a general document list nor a second Portfolio. An absent link reveals nothing about Workspaces you cannot access. Both entry points preserve the same business titles and access rights.

## Adapt a Workspace

Surface’s product controls use the supported English or French language selected by your host. If no supported language is supplied, the product default is French. The Model’s business labels, your content and saved values remain unchanged; changing the interface language does not translate them or change access rights.

Edit record values in the app. Edit app configuration in Studio: Fields, views, Actions and integrations. Review how a structural change affects existing data before activating it. The [migration guide](https://developers.dagio.ai/migrations/) explains this step.

For example, installing Quotes does not require rebuilding Clients. Add the **Quote → Client** link and use the relation panel on existing records.

## Archive and resume a Workspace

Before confirming an archive, review its consequences: remaining content access and suspended
automations. Content and history are preserved. A new review requires a new confirmation; changing
the language does not change your choice.

If a confirmation's result is still unknown, use **Check result** to resume that same request
without creating a duplicate. When Surface says the change was recorded but returning to your
Workspaces fails, retry that return: it does not repeat the archive. Accessible archived Workspaces
offer separate reviews for restoration or deletion, along with access management.

## Application extensions

An application can include approved extensions for specialized Data views, executable buttons and
record forms in the right sidebar. Their configuration appears under that application in Settings.
A button and an AI request use the same declared command and access checks. Commands requiring
human review retain their confirmation. Eligible automatic commands follow a configured frequency
without leaving the application open.

Extensions keep records, links and tags in Surface and complement Actions, Chat Views and Workmaps.
Email or another external service requires a module implementing that provider; adding an extension
does not connect an account automatically.

### Emails application

The Email capability is distributed as an extension. Its exact release must be installed or
declared as a required dependency of the Emails Model; installing a published Model installs that
dependency through Marketplace. The Emails application keeps messages and drafts in its Data Space. Mailbox adds message excerpts,
a reading pane on the right or below, and compose/reply/forward on the right. The Table view retains
its normal filters, including Mail account. In Settings → Mail accounts, add your IMAP/SMTP accounts,
configure each sender and choose a default. Test the saved connections, then Sync. Replies use the
receiving account; the composer lets you choose another sender. Disable an account to stop using it
while retaining its messages. Eligible periodic Sync visits all enabled accounts without keeping
the application open, and reports synchronization failures separately for each account.

Send reviews the exact recipients, body and attachments before human confirmation. An uncertain
SMTP outcome is kept for investigation rather than automatically resent. The current application
uses text drafts and attachments; classification and a hosted email-address service are separate.
Connecting a real mailbox remains necessary before receiving or sending your mail.

## Marketplace publication and review

The public Marketplace can be browsed without an account on the Surface host's `/marketplace`
page. Sign in to install an accepted application, then create its independent instance separately.
Free, Plus and Teams use the public catalogue. Pro adds a private personal catalogue; Business adds
an organization catalogue, where active membership is required and owners/admins can publish.

Discover applications in **Portfolio → Marketplace → Discover**, then open an application to
explore **Overview**, **What’s included** and **Details**. The topbar breadcrumb and Back return to
the catalogue. The application page shows its published structure and license; **Install application**
and **Create application** are separate actions. Publication progress and requested changes appear in
**My publications**. Technical review reports are not displayed in the application interface.

In Builder, choose **Publish Model to catalogue**, select the Marketplace, provide the title,
version, description and license, then **Submit for validation**. Publish definitions you have the
right to distribute; private records, documents, credentials and instance access are excluded.
The exact submitted version stays **Under review** during Model checks and IBM Granite review of
privacy, security, permissions/dependencies and functional coherence. Semantic review does not
prove that an external integration or user journey has run.

In **Marketplace presentation**, add the publisher name to display, choose a category and a Surface
icon, and write the application overview. You can add up to six public HTTPS screenshot links with
captions. Publish only images you are allowed to distribute and exclude private records and personal
data. These details are reviewed with the application and belong to its exact published version.
The supplied publisher name is a display label, not a verified-brand badge. Readers can filter the
catalogue by category and see the published presentation on the application page.

Open **Portfolio → Marketplace → My publications** to follow progress and read findings.
An accepted version becomes discoverable and installable. A rejection requires a corrected new
version. A blocked technical review can be retried explicitly; unavailable AI never approves by
default. Withdrawing a publication removes discovery and new installations while preserving
existing application instances and their history. Preview/build validation is separate from remote
service deployment.

<!-- surface-examples:start -->

## Applied examples : Organize destinations

Choose the Clients collection in navigation and offer the next actions on the home.

### Configuration

Fragment placed in `composition.navigation[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/).

```json
{
  "key": "clients",
  "label": "Clients",
  "icon": "users",
  "kind": "collection",
  "spaceKey": "clients",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "queryKey": "clients",
  "formKey": null
}
```

### Variation and connection

Fragment placed in `homePresentation`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-home-presentation/).

```json
{
  "contract": "WorkspaceHomePresentation@1",
  "header": {
    "intro": "Clients and quotes",
    "primaryNavigation": {
      "destinationKey": "clients",
      "label": "Open clients"
    }
  },
  "launchers": {
    "title": "Move work forward",
    "description": "Choose an action",
    "icons": [
      {
        "actionKey": "create-client",
        "icon": "users"
      },
      {
        "actionKey": "prepare-quote",
        "icon": "document"
      }
    ]
  },
  "blocks": [
    {
      "kind": "section",
      "sectionKey": "recent-quotes",
      "variant": "collection",
      "placement": "main",
      "maximumVisible": 4,
      "viewAll": {
        "destinationKey": "quotes",
        "label": "All quotes"
      }
    }
  ]
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Clients · Data
2. References · Knowledge
3. Preparation · Work
4. Quotes · Product

<!-- surface-examples:end -->