Class NavigationService

constructor

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

  Parameters

  • workspaceManager: WorkspaceStateManager
  • appManager: ApplicationManager

  Returns NavigationService

ReadonlyAgentContextUpdated$

ReadonlyAppContextSnapshot$

QueryParamChanged$

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

  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 (e.g. on LRU eviction), so the map doesn't retain references to dead component instances.

  Parameters

  • caller: BaseResourceComponent

  Returns void

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>): 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>

  Returns void

NotifyResourceDetached

• NotifyResourceDetached(caller: BaseResourceComponent): void

  Capture + clear the active client tools when a resource component's tab is detached (navigated away from), so the previous surface's tools aren't offered to the agent on the next surface. We snapshot whatever tools are CURRENTLY active and key them by the detaching component, so NotifyResourceReattached can replay them — robust to a wrapper component being the one cached/reattached while an inner child actually registered the tools (e.g. Data Explorer).

  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; no-op (lets a fresh component register itself) when none was captured (e.g. a component's very first attach).

  Parameters

  • caller: BaseResourceComponent

  Returns void

ObserveTabQueryParams

• ObserveTabQueryParams(tabId: string): 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.

  Parameters

  • tabId: string

  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?: NavigationOptions,
  ): string

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

  Parameters

  • dashboardId: string
  • dashboardName: string
  • Optionaloptions: NavigationOptions

  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 Uses Home app if available, otherwise falls back to active app or system app

  Parameters

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

  Returns string

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

OpenReport

• OpenReport(
      reportId: string,
      reportName: string,
      options?: NavigationOptions,
  ): string

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

  Parameters

  • reportId: string
  • reportName: 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

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.

  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>

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.

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

  Parameters

  • queryParams: Record<string, string | null>

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

  Returns void

  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