Workspaces and navigation
Install, organize and open the apps in your Portfolio.
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 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 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.
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.
{
"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.
{
"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.
- Clients · Data
- References · Knowledge
- Preparation · Work
- Quotes · Product
Records and reference information
Pricing, procedure and sources
Steps, decisions and results
Durable deliverable and revisions