Skip to main content

AdvaView PostMessage Integration API: Viewer Lifecycle Controls

AdvaView provides in-browser lifecycle control via the standard HTML5 window.postMessage() API. This allows a launching parent application (e.g., AdvaPACS worklist, RIS, or third-party EMR) to manage an open AdvaView window or iframe during patient context transitions and session termination.

1. Security & Permitted Origins​

To protect Protected Health Information (PHI), AdvaView enforces origin validation on all incoming postMessage events:

  • Default Origin: The tenant's primary AdvaPACS domain is permitted by default.
  • Third-Party Origins: Any external worklist or portal domain must be explicitly registered in the tenant's Permitted Origins configuration in AdvaPACS settings.
  • Rejected Messages: Commands originating from unlisted origins are silently dropped and will not trigger actions or acknowledgments.
tip

Always specify the exact target origin instead of '*' when calling postMessage, for both CLEAR_VIEWER and CLOSE_VIEWER commands.

2. CLEAR_VIEWER Integration Point​

Overview​

Resets the viewer to an idle state by closing open studies, clearing viewports, and purging patient data and images from memory and the DOM/canvas, while keeping the browser window and header toolbar open.

Typical Use Cases​

  • Patient Context Switching: The user navigates back to the worklist to select another patient study. Clearing previous images avoids visual flashing from closing/reopening windows while ensuring PHI is not left visible.
  • Empty/Non-Image Orders: The user auto-advances to an order or procedure with no associated DICOM series.

Command: CLEAR_VIEWER (Host → AdvaView)​

Sent from the launching window to the AdvaView window reference.

Payload Schema​

interface ClearViewerCommand {
  action: "CLEAR_VIEWER";
  /** Optional: Scope clearing to specific studies. If omitted or empty, all open studies are cleared. */
  studies?: Array<{
    studyInstanceUid?: string;
    storageId?: string;
  }>;
}

3. CLOSE_VIEWER Integration Point​

Overview​

The CLOSE_VIEWER message is an inbound postMessage command sent from the launching host application (worklist, RIS, PACS, or EMR) to the target AdvaView window or iframe instance. It instructs AdvaView to terminate its session, release loaded study resources from memory, and close the browser window/tab.

Typical Use Cases​

  • Host Application Logout: When a user logs out of the host RIS/PACS or closes their session, the host dispatches CLOSE_VIEWER to terminate any detached viewer windows and prevent unauthorized access to open patient data.
  • Patient Context Teardown: Explicitly closing a dedicated single-study viewer instance when returning to a multi-patient worklist.
  • Workflow Transitions: Programmatically managing child viewer windows across multi-monitor workstations.

Command: CLOSE_VIEWER (Host → AdvaView)​

Sent from the launching window to the AdvaView window reference.

Payload Schema​

interface CloseViewerCommand {
  /** Required action identifier */
  action: "CLOSE_VIEWER";

  /** 
   * Optional: If true, bypasses any unsaved annotations, measurements, 
   * or drafts confirmation prompts and terminates immediately.
   * Default: false
   */
  force?: boolean;

  /** 
   * Optional: Correlation or session ID to confirm in the response payload.
   */
  sessionId?: string;
}