Class NavigationService

constructor

• new NavigationService(
      workspaceManager: WorkspaceStateManager,
      appManager: ApplicationManager,
  ): NavigationService

  Parameters

  • workspaceManager: WorkspaceStateManager
  • appManager: ApplicationManager

  Returns NavigationService

ReadonlyAgentContextUpdated$

ReadonlyAppContextSnapshot$

QueryParamChanged$

ReadonlyResourceReattached$

DashboardEditModeRequested$

• get DashboardEditModeRequested$(): Observable<string>

  Emits the ID of the tab an OpenDashboard call with openInEditMode opened. The component bound to the tab takes the request with TakeDashboardEditModeRequest.

  Returns Observable<string>

ExplorerAppColor

• get ExplorerAppColor(): string

  Get the neutral color used for system-wide resources (entities, views, dashboards) Returns a light neutral gray

  Returns string

  Deprecated

  Use getDefaultAppColor() for better UX with Home app integration

clearHomeAppCache

• clearHomeAppCache(): void

  Returns void

  Deprecated

  Use ClearHomeAppCache.

ClearHomeAppCache

• ClearHomeAppCache(): void

  Clears the cached Home app info. Call this if apps are reloaded or user logs out.

  Returns void

ForgetResource

• ForgetResource(caller: BaseResourceComponent): void

  Drop a destroyed component's captured tools and detached mark (e.g. on LRU eviction), so nothing here retains references to dead component instances.

  Parameters

  • caller: BaseResourceComponent

  Returns void

IsResourceDetached

• IsResourceDetached(caller: BaseResourceComponent): boolean

  True between NotifyResourceDetached and NotifyResourceReattached for this component: its tab is not on screen, so it must not replace the agent context of the one that is.

  Parameters

  • caller: BaseResourceComponent

  Returns boolean

IsTabShowingResource

• IsTabShowingResource(tabId: string, owner: ResourceData): boolean

  True while the tab shows owner: the same app, resource type, driver class, entity and record as the resource data the tab container gave the owner. The app, resource type, driver class and entity are compared only when the owner has them; the record is always compared.

  Parameters

  • tabId: string
  • owner: ResourceData

  Returns boolean

ngOnDestroy

• ngOnDestroy(): void

  A callback method that performs custom clean-up, invoked immediately before a directive, pipe, or service instance is destroyed.

  Returns void

NotifyQueryParamsChanged

• NotifyQueryParamsChanged(
      tabId: string,
      params: Record<string, string>,
      force?: boolean,
  ): void

  Notify subscribers that query params changed on a specific tab. Called by the shell when back/forward navigation changes query params on the active tab. The notification includes the tab ID so only the component in that tab reacts.

  Parameters

  • tabId: string
  • params: Record<string, string>
  • force: boolean = false

  Returns void

NotifyResourceDetached

• NotifyResourceDetached(caller: BaseResourceComponent): void

  Clears the agent's client tools when the tab of the surface that registered them is detached (the user navigated away), and keeps them for that tab's reattach, so the previous surface's tools are not offered on the next surface. The detach of any other tab leaves the attached surface its tools. Every detach carries Lifecycle: 'Detached', so the shell can also clear the context the detached surface reported. The match is by tab, so a wrapper component being the one cached and detached while an inner child registered the tools (e.g. Data Explorer) still clears and later replays them. The component counts as detached (IsResourceDetached) until it is reattached.

  Parameters

  • caller: BaseResourceComponent

  Returns void

NotifyResourceReattached

• NotifyResourceReattached(caller: BaseResourceComponent): void

  Re-publish a cached resource component's tools when its tab is re-focused. Cached components keep their Angular instance but do NOT re-run ngAfterViewInit, so they never re-register on reattach — the shell calls this so the just-reactivated surface's tools become the agent's active set again. Replays the set captured for this component at its last detach; replays nothing (lets a fresh component register itself) when none was captured (e.g. a component's very first attach). The reattach of a detached component sends an update with Lifecycle: 'Reattached' (with the replayed tools, when there are any), so the shell can restore the context the surface reported before its detach. Either way the component stops counting as detached and ResourceReattached$ emits it.

  Parameters

  • caller: BaseResourceComponent

  Returns void

ObserveTabQueryParams

• ObserveTabQueryParams(
      tabId: string,
      owner?: ResourceData,
  ): Observable<Record<string, string>>

  Reactively observe the query params for a specific tab.

  Backed by the workspace BehaviorSubject, so a subscriber receives the current params immediately on subscribe AND every subsequent change — including the deep-link params that the ResourceResolver merges into the tab configuration on a cold/direct URL load.

  This is the race-free counterpart to NotifyQueryParamsChanged (a plain Subject that drops events fired before a component has subscribed). A resource component that mounts from workspace restoration can subscribe here and still pick up its initial deep-link state regardless of whether the params landed in the tab config before or after it mounted.

  With owner, the params arrive only while the tab shows that resource (see IsTabShowingResource). A tab can be reused for another resource while the owner stays alive in the component cache, still bound to the tab's ID.

  Parameters

  • tabId: string
  • Optionalowner: ResourceData

  Returns Observable<Record<string, string>>

OpenArtifact

• OpenArtifact(
      artifactId: string,
      artifactName?: string,
      options?: NavigationOptions,
  ): string

  Open an artifact Artifacts are versioned content containers (reports, dashboards, UI components, etc.) Uses Home app if available, otherwise falls back to active app or system app

  Parameters

  • artifactId: string
  • OptionalartifactName: string
  • Optionaloptions: NavigationOptions

  Returns string

OpenDashboard

• OpenDashboard(
      dashboardId: string,
      dashboardName: string,
      options?: DashboardNavigationOptions,
  ): string

  Open a dashboard in a tab of an application: options.applicationId when that application is loaded, otherwise the default application (Home app if available, otherwise the active app or system app). The workspace matches open tabs per application, so a tab that shows the same dashboard in another application is not reused. A tab already open for the dashboard is focused. Otherwise a plain open replaces the preview tab, so Back returns to the page it showed, and a Shift-click or options.forceNewTab opens a separate tab. options.openInEditMode asks the tab to enter edit mode (see TakeDashboardEditModeRequest). The tab holds the request in its configuration, and DashboardEditModeRequested$ tells the component bound to the tab.

  Parameters

  • dashboardId: string
  • dashboardName: string
  • Optionaloptions: DashboardNavigationOptions

  Returns string

OpenDynamicView

• OpenDynamicView(
      entityName: string,
      extraFilter?: string,
      options?: NavigationOptions,
  ): string

  Open a dynamic view Dynamic views are entity-based views with custom filters, not saved views Uses Home app if available, otherwise falls back to active app or system app

  Parameters

  • entityName: string
  • OptionalextraFilter: string
  • Optionaloptions: NavigationOptions

  Returns string

OpenEntityRecord

• OpenEntityRecord(
      entityName: string,
      recordPkey: CompositeKey,
      options?: NavigationOptions,
  ): string

  Open an entity record view. Behavior forks on the deployment's record-open style (see record-open-style.ts):

  • 'records' (default): the record ALWAYS opens as its own tab, assigned to the app the user is standing in (no Home reassignment, no nav flip). Re-opening a record that's already open focuses its existing tab, browser-style. The shell's Records pill + strip are the visible UI.
  • 'classic': the original Home-first assignment and tab semantics. Both styles capture the source-app trail into the tab configuration for context UI and diagnostics.

  Parameters

  • entityName: string
  • recordPkey: CompositeKey
  • Optionaloptions: NavigationOptions

  Returns string

OpenHomeDashboard

• OpenHomeDashboard(): Promise<boolean>

  Go to the Home app's landing dashboard. Used where there is nowhere more specific to return to — e.g. a record loaded straight from a URL is deleted. Returns false when the deployment has no Home app (or the user cannot see it), so the caller can choose its own fallback.

  Returns Promise<boolean>

OpenNavItem

• OpenNavItem(
      appId: string,
      navItem: NavItem,
      appColor: string,
      options?: NavigationOptions,
  ): string

  Open a navigation item within an app

  Parameters

  • appId: string
  • navItem: NavItem
  • appColor: string
  • Optionaloptions: NavigationOptions

  Returns string

OpenNavItemByName

• OpenNavItemByName(
      navItemName: string,
      configuration?: Record<string, unknown>,
      appId?: string,
      options?: NavigationOptions,
  ): Promise<string | null>

  Navigate to a nav item by name within the current or specified application. Allows passing additional configuration parameters to merge with the nav item's config. This is useful for cross-resource navigation where a component needs to navigate to another nav item with specific parameters (e.g., navigate to Conversations with a specific conversationId).

  Parameters

  • navItemName: string

    The label/name of the nav item to navigate to

  • Optionalconfiguration: Record<string, unknown>

    Additional configuration to merge (e.g., conversationId, artifactId)

  • OptionalappId: string

    Optional app ID (defaults to current active app)

  • Optionaloptions: NavigationOptions

    Navigation options

  Returns Promise<string | null>

  The tab ID if successful, null if nav item not found

OpenNewEntityRecord

• OpenNewEntityRecord(entityName: string, options?: NavigationOptions): string

  Open a new entity record creation form Uses Home app if available, otherwise falls back to active app or system app

  Parameters

  • entityName: string

    The name of the entity to create a new record for

  • Optionaloptions: NavigationOptions

    Navigation options including optional newRecordValues for pre-populating fields

  Returns string

OpenQuery

• OpenQuery(
      queryId: string,
      queryName: string,
      options?: NavigationOptions,
  ): string

  Open a query Uses Home app if available, otherwise falls back to active app or system app

  Parameters

  • queryId: string
  • queryName: string
  • Optionaloptions: NavigationOptions

  Returns string

OpenSearch

• OpenSearch(
      query: string,
      searchOptions?: { minRelevance?: number; scopeIDs?: string[] },
      options?: NavigationOptions,
  ): string

  Open a universal search results tab for the given query. This is the primary way to open search results from anywhere in the application.

  Parameters

  • query: string

    The search query text

  • OptionalsearchOptions: { minRelevance?: number; scopeIDs?: string[] }

    Optional search-specific options (e.g., minRelevance, scopeIDs)

  • Optionaloptions: NavigationOptions

    Navigation options

  Returns string

OpenView

• OpenView(viewId: string, viewName: string, options?: NavigationOptions): string

  Open a view Uses Home app if available, otherwise falls back to active app or system app

  Parameters

  • viewId: string
  • viewName: string
  • Optionaloptions: NavigationOptions

  Returns string

PublishAppContextSnapshot

• PublishAppContextSnapshot(snapshot: AppContextSnapshot | null): void

  Push a fresh AppContextSnapshot. Called by MJExplorerAppComponent after each (a) app/tab change, (b) handleAgentContextUpdate merging in AdditionalContext from a dashboard. Idempotent — no de-duplication; embedders should treat the stream as "the latest value is canonical."

  Parameters

  • snapshot: AppContextSnapshot | null

  Returns void

RetargetMovedNavItemTabs

• RetargetMovedNavItemTabs(): Promise<number>

  Moves each saved tab of a moved nav item (ResolveMovedNavItem) to the new app's nav item, when the tab's app no longer has the nav item and the user has the new app. The tab keeps its id, driver class and query params. When the new app already has a tab for that nav item, the saved tab is closed instead, and the existing tab becomes active if the saved tab was. Waits for the user's app list. Runs never overlap: a call made during a run gets the one run after it, which every call made meanwhile shares.

  Returns Promise<number>

  The number of saved tabs it moved or closed. A failure is logged and changes nothing.

ReturnToRecordSource

• ReturnToRecordSource(origin: RecordSourceContext): Promise<void>

  Take the user back to where they were when a record was opened (the origin crumb's click path). Fidelity ladder:

  1. The exact source tab, if it's still open — reactivate it with all its state (query params, scroll, cached component) intact.
  2. Otherwise re-resolve by app + nav label via SwitchToApp, which reuses a matching open tab or opens the nav item fresh. No-ops when the context has no sourceAppId (capture was best-effort).

  Parameters

  • origin: RecordSourceContext

  Returns Promise<void>

SetAgentClientTools

• SetAgentClientTools(
      caller: BaseResourceComponent,
      tools: {
          Description: string;
          Handler: (params: Record<string, unknown>) => Promise<unknown>;
          Name: string;
          ParameterSchema: Record<string, unknown>;
      }[],
  ): void

  Register the client tools available from a resource component. Call this on component init and whenever the available tools change. Tools are automatically unregistered when the component becomes inactive (tab switch) and re-registered when it becomes active again.

  Parameters

  • caller: BaseResourceComponent

    Pass this from the calling component.

  • tools: {
        Description: string;
        Handler: (params: Record<string, unknown>) => Promise<unknown>;
        Name: string;
        ParameterSchema: Record<string, unknown>;
    }[]

    Array of tool definitions with Name, Description, ParameterSchema (JSON Schema), and Handler function.

  Returns void

SetAgentContext

• SetAgentContext(
      caller: BaseResourceComponent,
      context: Record<string, unknown>,
  ): void

  Report the current agent-visible state from a resource component. Call this whenever the dashboard's internal state changes (tab switch, filter change, pipeline status change, drill-down, etc.).

  Parameters

  • caller: BaseResourceComponent

    Pass this from the calling component. Used to match against the ComponentCacheManager to identify which cached component this update belongs to.

  • context: Record<string, unknown>

    Key-value pairs representing dashboard state the agent should know about. Each dashboard defines its own shape.

  Returns void

SwitchToApp

• SwitchToApp(
      appId: string,
      navItemName?: string,
      queryParams?: Record<string, string | null>,
  ): Promise<void>

  Switch to an application by ID. This sets the app as active and either opens a specific nav item or creates a default tab. If the requested nav item already has an open tab, switches to that tab instead of creating a new one. A nav item the app no longer has, which moved to another app (ResolveMovedNavItem), opens in that app with the same query params when the user has that app.

  Parameters

  • appId: string

    The application ID to switch to

  • OptionalnavItemName: string

    Optional name of a nav item to open within the app. If provided, opens that nav item.

  • OptionalqueryParams: Record<string, string | null>

    Optional query params to apply to the target tab. Applied SYNCHRONOUSLY once the target tab is active — critical when navigating (e.g. from a Home pin) to an app whose resource component is cached: the params must be in the tab config BEFORE the tab-container reattaches the cached component, otherwise the cache restores its own (stale) saved params and the navigation intent is lost.

  Returns Promise<void>

SwitchToAppHome

• SwitchToAppHome(appId: string): Promise<void>

  Switch to an app's LANDING page — its default nav item in its BASE state (drifted section params cleared, reset force-delivered so the dashboard actually returns to its landing even if its state diverged). The origin crumb's APP segment uses this: classic breadcrumb semantics, each level goes to that level's home.

  Parameters

  • appId: string

  Returns Promise<void>

TakeDashboardEditModeRequest

• TakeDashboardEditModeRequest(
      tabId: string,
      dashboardId: string,
      applicationId: string,
  ): boolean

  Returns true when the tab shows the dashboard in the application and has an openInEditMode request (see OpenDashboard), and removes that request from the tab, so only the first call returns true. The dashboard tab calls this when its dashboard has loaded, when DashboardEditModeRequested$ names its tab, and when the tab container reattaches it to a new tab. A restored or reloaded tab then opens for viewing. OpenTab can replace a preview tab in place, so a cached component can still be bound to a tab that now shows another dashboard, or the same dashboard in another application. That tab keeps its request for its own component.

  Parameters

  • tabId: string
  • dashboardId: string

    The dashboard the caller shows.

  • applicationId: string

    The application of the caller's tab.

  Returns boolean

UpdateActiveTabQueryParams

• UpdateActiveTabQueryParams(queryParams: Record<string, string | null>): void

  Update the query params for the currently active tab. This updates the tab's configuration and triggers a URL sync via the shell's workspace configuration subscription.

  🚨 NEVER CALL THIS FROM A RESOURCE COMPONENT OR DASHBOARD. "The active tab" is whatever the user is looking at right now, which is not necessarily the tab the caller lives in. A component whose async work completes while it sits in a BACKGROUND tab will rewrite — and destroy — the deep link of the tab the user is actually viewing. Components use BaseResourceComponent.UpdateQueryParams, which routes to UpdateTabQueryParams with their own tab id and refuses to write when they have none.

  This remains only for shell-level navigation code that is, by construction, acting on behalf of the user's current tab (nothing in this repo does today).

  Parameters

  • queryParams: Record<string, string | null>

    Object containing query param key-value pairs. Use null values to remove a query param.

  Returns void

  Deprecated

  Prefer UpdateTabQueryParams with an explicit tab id.

  Use this instead of directly calling router.navigate() to ensure proper URL management that respects app-scoped routes.

  Example

  // Add or update query params
  navigationService.UpdateActiveTabQueryParams({ category: 'abc123', dashboard: 'xyz789' });
  
  // Remove a query param
  navigationService.UpdateActiveTabQueryParams({ category: null });
  Copy

UpdateTabQueryParams

• UpdateTabQueryParams(
      tabId: string,
      queryParams: Record<string, string | null>,
      guard?: TabQueryParamUpdateGuard,
  ): boolean

  Update query params for a specific tab, optionally only if the tab still hosts the expected resource identity. This matters in single-resource mode where a tab ID can be reused for a different resource while the previous component is detached but still alive in the cache.

  Parameters

  • tabId: string
  • queryParams: Record<string, string | null>
  • Optionalguard: TabQueryParamUpdateGuard

  Returns boolean

WatchMovedNavItemTabs

• WatchMovedNavItemTabs(): Promise<Subscription>

  Runs RetargetMovedNavItemTabs now, and again each time the user's app list changes while no app load is in progress, for example when an app is installed during the session. Resolves after the first run.

  Returns Promise<Subscription>

  The subscription for the later runs. Unsubscribe it to stop them.