> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/linked-app-exchange-screen.md). # Linked App Exchange Screen > Current state: this native screen is part of **Automation**. It is entitlement-gated, uses NotionApps runtime state instead of ordinary Notion data controls, and should be tested with realistic workflow or messaging activity before a maker relies on it in production. The **Linked App Exchange** screen is a collaboration screen for requests, messages, payloads, and acknowledgements exchanged between linked NotionApps applications. Think of this screen as **An app-to-app mailbox for structured handoffs.** ![Builder view of this screen with the configuration panel open](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FDdkIHCaOye9vCav1Vew8%2F00-builder-hero.jpg?alt=media) ## Who This Guide Is For This guide is for makers configuring a **Linked App Exchange** screen in the app builder. It lists every builder option available on the screen and explains how to use each one. Use this guide when: * Work or data must move between two NotionApps apps. * Operators need to acknowledge linked-app payloads. * Makers need visibility into cross-app request state. ## What The Screen Is For ### Use Linked App Exchange when * Work or data must move between two NotionApps apps. * Operators need to acknowledge linked-app payloads. * Makers need visibility into cross-app request state. ### Do not use it when * Inside-one-app chat — use Conversation. * Human approvals — use Decision. * External SaaS webhooks with no linked app — use webhook routes / Workflow Status. ## What Users See In The Live App * Exchange cards for inbound/outbound linked-app activity. * Acknowledge action for received exchanges. * Payload preview based on visibility settings. | Default | Value | | ------------------------------- | ------------------------------------------------------------------------ | | Default listen scope | Entire app (prefer Linked application in practice) | | Require claim before action | Off | | Default preview persona / state | Operator / Live | | Empty title | No linked app exchanges | | Empty description | Linked app activity appears here after an app-to-app route is connected. | ## Required Foundations | Requirement | Why it matters | | ------------------------------------------ | ------------------------------------------------------------------ | | Automation screen entitlement | Linked App Exchange appears in the Automation / Operational group. | | Messaging, optional Workflow | Primary foundation for this screen’s runtime state. | | Private app + Users database (recommended) | Role/tenant visibility and audience policy need user fields. | ## Complete Builder Options Reference The sections below follow the builder order. Each option is explained in prose so makers can configure a cross-app exchange surface that is clearly scoped, appropriately restricted, and easy for operators to acknowledge. ### Header and screen type This section defines the cross-app exchange desk. The screen works best when users immediately understand that the content is coming from a linked NotionApps application, not from ordinary local workflow items. #### Screen type **What it does:** Sets the native behavior to **Linked App Exchange**, which renders app-to-app exchange runtime state instead of local data rows.\ **How to use it:** Keep the type as Linked App Exchange. Use Conversation for in-app messaging and Work Queue for human-owned local tasks.\ **Why / recommended default:** Cross-app handoffs are easier to operate when they have their own dedicated surface. #### Category **What it does:** Places the screen in the native Automation or Operational grouping.\ **How to use it:** Keep the built-in grouping and position the screen near other integration or operations tools.\ **Why / recommended default:** Clear separation helps makers and operators distinguish exchange issues from local workflow issues. #### Title **What it does:** Sets the live title shown to users.\ **How to use it:** Use titles like `Linked app exchange`, `Partner handoffs`, or `Integration inbox` so the source is obvious.\ **Why / recommended default:** Naming matters here because users need to know that another app is involved. #### Description **What it does:** Adds helper text beneath the title.\ **How to use it:** Explain what kinds of payloads arrive here and whether users should review or acknowledge them.\ **Why / recommended default:** Good description text makes the screen easier for non-builders to operate. ### Automation source ![Annotated builder screenshot: Automation source](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Fm4mLkrchy859dykP8G9u%2F01-section-automation-source.jpg?alt=media) This section is the most important part of the screen. Linked App Exchange only works when it is pointed at the correct app and, when needed, the correct message context inside that app relationship. #### Listen scope **What it does:** Chooses the top-level source of exchange items shown on the screen.\ **How to use it:** Prefer **Linked application** for most real exchange desks. Use **Entire app** only for a broad integration oversight screen run by trusted admins.\ **Why / recommended default:** The practical default for this screen is **Linked application** even though broader scopes may exist. It keeps the screen tied to the specific partner app operators expect. #### Source screen or form **What it does:** Binds the screen to one local source surface when that scope is selected.\ **How to use it:** Use this only when the exchange is conceptually anchored to one intake surface in the current app.\ **Why / recommended default:** Most exchange desks are better defined by the linked app than by a local form. #### Workflow **What it does:** Filters exchange context to one workflow when **Specific workflow** is selected.\ **How to use it:** Use workflow scope if one integration flow is handled by a dedicated team.\ **Why / recommended default:** Workflow scope can help, but linked-app binding is usually the clearer starting point. #### Messaging channel **What it does:** Narrows exchange items to a particular channel.\ **How to use it:** Match the exact channel used by the app-to-app exchange route.\ **Why / recommended default:** Channel mismatch is one of the first things to check when an expected exchange never appears. #### Topic **What it does:** Filters the selected channel to a specific topic.\ **How to use it:** Use stable topics when one linked app sends several classes of exchange messages.\ **Why / recommended default:** Topic filtering is useful for clarity, but it can also hide items unexpectedly if names drift across environments. #### Conversation or correlation **What it does:** Limits the exchange desk to one case or one correlated handoff thread.\ **How to use it:** Use this only when the screen is embedded inside a specific case experience.\ **Why / recommended default:** Most exchange desks should stay reusable and broader than a single correlation. #### Linked application **What it does:** Binds the screen to the external NotionApps application participating in the exchange.\ **How to use it:** Choose the exact linked app that should feed this screen. Re-check the binding if you clone, relink, or rename the partner app.\ **Why / recommended default:** This is the defining setting for the screen. If the wrong linked app is selected, the desk will either be empty or show the wrong partner traffic. ### App audience and notification prefs These app-level controls matter because cross-app exchange data can still be tenant-sensitive and role-sensitive, even when the items originate outside the current app. #### Tenant mode **What it does:** Decides whether exchange visibility is partitioned by tenant relation.\ **How to use it:** Use **Relation** when partner-specific or client-specific exchange data should stay isolated. Use **Off** only for simple single-tenant internal integration setups.\ **Why / recommended default:** Cross-app payloads can carry sensitive context, so tenant isolation is often the safer default. #### Tenant field **What it does:** Selects the Users-sheet relation that defines tenant membership.\ **How to use it:** Use the same tenant field the rest of the app already trusts.\ **Why / recommended default:** Consistency keeps access behavior predictable across internal and external runtime surfaces. #### Role field **What it does:** Tells the platform which field stores user roles when it is not named `Role`.\ **How to use it:** Set it only for custom user schemas.\ **Why / recommended default:** Integration desks are often restricted to specialized teams, so role mapping needs to be correct. #### Notification categories **What it does:** Maps notice categories to user preference fields.\ **How to use it:** Configure only the categories that matter for exchange-related alerts or follow-up notices.\ **Why / recommended default:** Clean policy makes it easier to understand who should be alerted about partner traffic. #### Add notification category **What it does:** Adds another category row to the app-level policy.\ **How to use it:** Add one only when the exchange system really uses it.\ **Why / recommended default:** Fewer categories are easier to govern. #### Save audience policy **What it does:** Saves tenant and category policy at the app level.\ **How to use it:** Save before testing linked-app visibility with another persona.\ **Why / recommended default:** Unsaved policy is a frequent cause of misleading access tests. ### Template setup state This diagnostic section is especially useful after templates are cloned or linked apps are reconnected. #### Setup state indicator **What it does:** Reports whether the screen setup is provisioned, needs review, or has no setup report.\ **How to use it:** Treat **Needs review** as a sign to re-check the linked app binding and any channel or topic filters.\ **Why / recommended default:** Exchange screens depend on several bindings, so this quick health signal is valuable. ### Related context This read-only panel helps makers locate neighboring screens, workflows, and channels connected to the exchange. #### Related context panel **What it does:** Shows discovery counts and related runtime objects.\ **How to use it:** Use it to find the partner-facing workflow, a related Conversation screen, or a follow-up Workflow Status page.\ **Why / recommended default:** Cross-app experiences are easier to maintain when makers can see their neighboring context. ### Visibility and access ![Annotated builder screenshot: Visibility and access](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F6IofLmflApqsKNiMVuTb%2F02-section-visibility-and-access.jpg?alt=media) Linked App Exchange is usually an internal or partner-ops surface, so the audience should be explicit and narrow. #### Visibility rules **What it does:** Applies condition-based screen visibility.\ **How to use it:** Restrict the screen by role, tenant, or integration team membership.\ **Why / recommended default:** Exchange payloads often contain operational detail that ordinary users should not see. #### Allowed role names **What it does:** Adds a direct role allow list.\ **How to use it:** Use focused roles like `Integration, Operator, Admin`.\ **Why / recommended default:** A short role list is usually the clearest access model for exchange desks. #### Allowed users **What it does:** Grants access to specific named people.\ **How to use it:** Use this for pilots, partner-specific coordinators, or break-glass support.\ **Why / recommended default:** Named-user access is best kept exceptional. ### Display and action policy ![Annotated builder screenshot: Display and action policy](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FUwZ0JaeLR7MuyYvHK6h2%2F03-section-display-and-action-policy.jpg?alt=media) These settings control how much exchange detail operators see and whether the desk feels like a light inbox or a denser integration console. #### Screen title override **What it does:** Refines the live title.\ **How to use it:** Use language the operator team actually uses for the partner relationship or handoff.\ **Why / recommended default:** Clear terminology is important because "exchange" can mean different things to different teams. #### Description **What it does:** Sets the helper text under the title.\ **How to use it:** Explain whether users should inspect, acknowledge, or follow up on items from the linked app.\ **Why / recommended default:** Good copy reduces uncertainty about whether the desk is passive or actionable. #### Payload visibility **What it does:** Chooses whether users see metadata only, a redacted preview, or fuller payload detail.\ **How to use it:** Use **Redacted preview** for most operator desks and **Full payload** only when trusted integration users really need raw exchange content.\ **Why / recommended default:** Cross-app payloads can expose a lot of detail, so conservative visibility is usually the right default. #### Density **What it does:** Chooses comfortable or compact spacing.\ **How to use it:** Use **Comfortable** for occasional operators and **Compact** for specialized teams who monitor exchange volume all day.\ **Why / recommended default:** Comfortable layouts reduce operator error when the payload structure is unfamiliar. #### Show timeline **What it does:** Shows related audit and runtime history around the exchange item.\ **How to use it:** Leave **On** when users need to understand when the handoff happened, who acknowledged it, or whether a downstream step followed.\ **Why / recommended default:** Timeline context is often useful in integration work because timing and sequence matter. #### Require claim before action **What it does:** Exists in the shared policy section, but Linked App Exchange does not use claim behavior in its default action model.\ **How to use it:** Leave it **Off**.\ **Why / recommended default:** The standard exchange action is acknowledgement, not claiming ownership. ### Available actions ![Annotated builder screenshot: Available actions](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FF3s1IIQk3SC1q1FpZABW%2F04-section-available-actions.jpg?alt=media) This screen intentionally keeps the action model light. In most cases, the main operator action is to acknowledge that the cross-app payload has been seen or processed. #### Acknowledge **What it does:** Marks the linked-app exchange item as acknowledged.\ **How to use it:** Keep Acknowledge enabled when operators need to record that they reviewed or accepted the handoff.\ **Why / recommended default:** Acknowledge is usually the right default because it adds traceability without turning the screen into a full queue. #### After-action screen **What it does:** Routes the user to another screen after acknowledgement.\ **How to use it:** Use Workflow Status or Conversation only when the handoff naturally leads to a next step in the same app. Otherwise leave the user on the exchange desk.\ **Why / recommended default:** Staying on the exchange desk is often least surprising, especially for teams processing several handoffs in a row. #### Target workflow **What it does:** Supplies a workflow target for custom launch or escalation actions if you add them later.\ **How to use it:** Leave it blank on the standard screen unless an added action truly starts another workflow.\ **Why / recommended default:** Unused workflow targets add complexity without helping operators. ### Preview scenario ![Annotated builder screenshot: Preview scenario](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FbtvSDEyoPA2wSHFH83Yr%2F05-section-preview-scenario.jpg?alt=media) Preview controls help you confirm that the linked-app context is understandable before the first real partner handoff arrives. #### Device and orientation **What it does:** Changes the preview frame across desktop, tablet, and mobile sizes.\ **How to use it:** Check the device your operators actually use, then validate mobile if exchange work may happen away from a desk.\ **Why / recommended default:** Payload-heavy integration screens can break more easily on smaller layouts. #### Test persona **What it does:** Simulates the viewer role.\ **How to use it:** Test with the actual integration or operator persona rather than only with Admin.\ **Why / recommended default:** Persona testing catches visibility issues that are especially common on restricted operational screens. #### Preview state **What it does:** Simulates states such as Live, Empty, Loading, and Error.\ **How to use it:** Check **Live** for payload readability and **Empty** to ensure the screen still feels intentional before the first linked-app route is connected.\ **Why / recommended default:** The empty state matters because builders often configure this screen before the integration is fully active. #### Test mode **What it does:** Switches between simulated preview and live testing.\ **How to use it:** Use live testing once the linked app is connected so you can verify the real binding and acknowledgement path.\ **Why / recommended default:** Simulation helps with layout, but live exchange testing is what proves the linkage works. ### Empty state and sample data ![Annotated builder screenshot: Empty state and sample data](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FoMAgLY86hdT3MCl9OOce%2F06-section-empty-state-and-sample-data.jpg?alt=media) A new integration desk is often empty at first, so the empty state should reassure users that the connection is simply quiet. #### Empty title **What it does:** Sets the headline shown when no exchange items match.\ **How to use it:** Keep the default `No linked app exchanges` unless your team uses a more specific phrase like `No partner handoffs`.\ **Why / recommended default:** The default is accurate and easy to understand. #### Empty description **What it does:** Explains when exchange items will appear.\ **How to use it:** Keep or adapt the default `Linked app activity appears here after an app-to-app route is connected.`\ **Why / recommended default:** Helpful empty copy prevents operators from assuming the integration is broken before any traffic exists. #### Sample item, run, or conversation **What it does:** Provides builder-only sample references for preview and QA.\ **How to use it:** Use realistic cross-app payloads so you can validate the acknowledgement pattern and payload visibility before a real partner starts sending traffic.\ **Why / recommended default:** Thin or fake samples often hide exactly the field-length and timing issues that show up first in production. ## Recommended Default Setup | Setting | Recommended value | | ------------------ | ------------------------------------------------------------------ | | Listen scope | Linked application (select the linked app; optional channel/topic) | | Visibility | Operator / Integration / Admin | | Payload visibility | Redacted preview | | Show timeline | On | | Actions | Acknowledge | ## Common Configuration Patterns ### Two-app handoff inbox Linked application scope + Acknowledge. ### Integration audit view Entire app for admins; Full payload for trusted operators. ## Testing Checklist * [ ] Send a linked-app message and confirm it appears. * [ ] Acknowledge and confirm state updates. * [ ] Confirm the wrong linked app binding shows empty. ## Troubleshooting ### No exchanges Linked application not selected, apps not linked, or channel/topic mismatch. ### Cannot acknowledge Action missing or user lacks access. ## Best Practices * Configure **Linked App Exchange** for one clear user job. * Prefer the narrowest listen scope that still shows the right work. * Keep payload visibility conservative for broad audiences. * Test as an allowed user and a blocked user before publish. * Pair related screens (Decision + Conversation + Workflow Status + Notification Center) instead of overloading one screen.