AGL.js | Epic Active Guidelines

A typed client for Epic's Active Guidelines (AGL) platform. Call do() to run actions, listen for events, and read session details — the handshake, tokens, and message plumbing are handled for you.

It handles:

• Detecting whether the app is running inside Epic
• Communicating with the Epic backend
• Triggering and queuing actions in Hyperspace
• Subscribing to and handling AGL events, including print requests
• App state and navigation history
• Clean teardown of the persistent message listener

Table of Contents

1. Getting Started
2. Configuration
3. Usage
4. Parameters
5. Methods
6. Queuing
7. Error Handling
8. Subscriptions
9. State Management
10. Navigation History
11. Teardown
12. Migrating from 1.x

Disclaimer

AGL.js is not affiliated with or endorsed by Epic Systems Corporation. It is intended solely for use by organizations with active Epic licenses. Please ensure compliance with your Epic agreements before using or distributing this library.

Getting Started

📦 Installation

Install via npm or yarn:

npm install agljs
# or
yarn add agljs

TypeScript

import AGL from 'agljs'

const agl = new AGL()
if (await agl.active) console.log(agl.details.availableActions)

JavaScript (ESM)

import AGL from 'agljs'

const agl = new AGL()
if (await agl.active) console.log(agl.details.availableActions)

JavaScript (CommonJS)

const AGL = require('agljs')

const agl = new AGL()
agl.active.then(active => active && console.log(agl.details.availableActions))

💾 Script Tag (download or CDN)

Download agl.min.js from the releases page, or load it from a CDN such as jsDelivr:

The script tag exposes the class as the global AGL:

<!-- local: <script src="path/to/agl.min.js"></script> -->
<script src="https://cdn.jsdelivr.net/npm/agljs/js/agl.min.js"></script>
<script>
  const agl = new AGL();

  agl.active.then(function(active) {
    if (active) console.log(agl.details.availableActions);
  });
</script>

Configuration

The AGL constructor accepts an optional configuration object with the following optional parameters:

| Parameter | Type | Description | Default | |----------------|----------------|--------------------------------------------------------------------|---------| | debug | boolean | Enables debug logging for troubleshooting | false | | timeout | number | Timeout (in milliseconds) before failure for action responses | 2000 | | targetOrigin | string | Restricts inbound/outbound messages to a specific Epic origin | '*' | | subscribe | object | An object containing events to subscribe to during the handshake | {} | | onError | function | Callback for handling errors | null | | onNavigate | function | Callback for navigation events (e.g., back/forward) | null | | onReload | function | Callback for reload (history package) events | null | | onAGLEvent | function | Callback for custom AGL events | null | | onSubscribed | function | Callback for handling subscription results | null | | onPrint | function | Callback fired when Epic requests a print | null |

Debugging tip: set debug: true in the constructor as your first step. Because the handshake runs at construction, only a constructor-time debug flag captures it — this is the most useful log for diagnosing initialization.

Note: subscribe and targetOrigin are fixed at first construction. Re-constructing AGL updates only debug, timeout, and callbacks.

Example Configuration

const agl = new AGL({
   debug: true,
   timeout: 5000,
   subscribe: {
      "Epic.Common.RequestToCloseApp": { PauseDuration: 300 },
   },
   onError: (error) => console.error('Error:', error),
   onNavigate: (event) => console.log('Navigation event:', event.direction),
   onReload: (payload) => console.log('Reload payload:', payload),
   onPrint: () => window.print(),
});

Usage

All actions must wait for the AGL handshake to complete and confirm the app is running inside Epic, via if (await agl.active).

Example:

const agl = new AGL();

if (await agl.active) {
   agl.do('Epic.Clinical.Informatics.Web.SaveState', { state: 'example' })
      .then((success) => console.log('State saved:', success))
      .catch((err) => console.error('Error saving state:', err));
}

Example:

const agl = new AGL();
if (!await agl.active) throw new Error('AGL is inactive! Not running in Epic.');

agl.on('navigate', (event) => {
   console.log('User navigated:', event.direction);
});

Parameters

active (read-only)

Always returns a Promise<boolean> that resolves to whether AGL is active and initialized. await it before performing actions:

if (await agl.active) console.log('AGL is initialized and ready.');

details (read-only)

Provides information from Epic about the current AGL context. Properties include:

| Property | Type | Description | |---------------------------------------|-------------------|-----------------------------------------------------| | availableActions | string[] | List of actions supported in the current context | | actionsNotRequiringUserConfirmation | string[] | Actions Epic will run without a confirmation prompt | | currentState | string \| null | State restored from the handshake (see below) | | interfaceVersion | string \| null | Version of the AGL JavaScript interface | | readOnly | boolean | Indicates if the AGL context is read-only | | token | string \| null | Token required for posting messages to Epic |

Example:

console.log('Token:', agl.details.token);
console.log('Available actions:', agl.details.availableActions.join(', '));

debug (write-only)

Enables or disables debug logging dynamically

Example:

agl.debug = true; // Enable debug logging

Methods

do(action, args = null, haltOnError = false)

Executes an action within AGL.

| Parameter | Type | Description | |----------------|------------|----------------------------------------------------------------------------------------------| | action | string | The name of the action to perform | | args | object | Optional Arguments to pass with the action | | haltOnError | boolean | Optional Stops the queue if this action fails, preventing subsequent actions from running |

do() automatically waits for the handshake to finish before running, so you do not need to guard every call with await agl.active. It resolves false if AGL never initializes (e.g. not running in Epic).

Example: Basic Action

agl.do('SaveState', { state: 'example' });

For convenience, actions without a full namespace (i.e., actions without a dot) are automatically prefixed with Epic.Clinical.Informatics.Web. To override this behavior, include the full namespace directly:

Example: Full Namespace Action

if (await agl.active) {
   agl.do('Custom.Namespace.Action', { someArg: 'value' });
}

on(eventName, callback)

Registers a callback for specific AGL events. | Parameter | Type | Description | |-----------------|------------|----------------------------------------------------------| | eventName | string | The name of the event to listen for | | callback | function | The callback function to execute when the event occurs |

Events types:

| Event Name | Example Response | |-----------------|-----------------------------------------------------------------------| | error | { message: 'Error description', details: ['Detail 1', ...] } | | navigate | { direction: 'Back' } | | reload | The raw historyPackage payload from Epic (see note below) | | aglEvent | { name: 'Event name', args: { arg1: ... } } | | subscribed | { EventName: 'Event name', SubscriptionSuccess: boolean } | | print | (no arguments) — fired when Epic requests a print |

reload payload: Epic delivers the navigation-history package under historyPackage. Its inner shape is passed through unchanged as a Record<string, unknown>; inspect it against your Epic build (enable debug) rather than assuming key names. This is distinct from state restoration — see State Management.

Example:

agl.on('navigate', (event) => {
   console.log('User navigated:', event.direction);
});

Example: Chaining listeners

agl
   .on('navigate', (event) => console.log('User navigated:', event.direction))
   .on('reload', (payload) => console.log('History package:', payload));

Queuing

Actions are added to a queue and executed sequentially to avoid race conditions. By default, the queue continues processing even if an action fails. However, setting haltOnError in do to true stops the queue when that action fails, ensuring dependent actions are not executed. A timeout is treated as a lost connection: it tears the session down entirely (see Teardown).

Example:

agl.do('SaveState', { state: 'example' }, true) // Stop queue if SaveState fails
   .catch((error) => console.error('SaveState failed:', error));

agl.do('CloseActivity', null) // Will only execute if SaveState succeeds
   .catch((error) => console.error('CloseActivity failed:', error));

Advanced Usage

Error Handling

Without an error handler, a failed action rejects with an Error. With a handler, the callback receives the structured error and the action resolves false. If the handler throws, the action rejects with that error.

Overriding Error Handling

You can override internal error handling by providing a custom onError callback in the configuration.

Example: During instantiation

const agl = new AGL({
   onError: (error) => {
      console.error('Custom error handler:', error.message);
   },
});

Example: After instantiation

agl.on('error', (error) => {
   console.error('Custom error handler:', error.message);
});

Subscriptions

You can specify subscriptions during initialization using the subscribe property. Subscriptions allow your application to register for specific events, such as changes in patient demographics or requests to close the app.

Confirming Subscriptions

To confirm that each subscription was successfully processed during the handshake, you can define an onSubscribed callback. This callback receives the subscription results, allowing you to verify whether your subscriptions were accepted by Epic.

Example:

const agl = new AGL({
   subscribe: {
      "Epic.Patient.Demographics.Updated": { IncludeHistory: true },
      "Epic.Common.RequestToCloseApp": { PauseDuration: 200 }
   },
   onSubscribed: (results) => {
      console.log('Subscription handshake completed:', results);
   },
});

Listening for Subscribed Events

After subscriptions are successfully established, your application can handle the events triggered by those subscriptions using the aglEvent handler.

Example:

agl.on('aglEvent', (event) => {
   if (event.name === 'Epic.Patient.Demographics.Updated') {
      console.log('Patient demographics updated:', event.args);
   }
   if (event.name === 'Epic.Common.RequestToCloseApp') {
      agl.do('Epic.Common.CloseApp',  {
         CanClose: true
      });
   }
});

State Management

AGL.js supports saving and restoring app state during transitions or hibernation.

Saving State

To save the current state of your application, use the SaveState action.

Example: Simple string

agl.do('SaveState', { state: 'dashboard' });

Example: Complex state

agl.do('SaveState', {
   state: JSON.stringify({ tab: 'overview', filters: { active: true } })
});

Restoring State

Epic returns the previously saved state on the handshake, exposed as details.currentState. Read it once AGL is active — it is null when no state was saved:

Example:

const agl = new AGL();

if (await agl.active && agl.details.currentState) {
   const restored = JSON.parse(agl.details.currentState);
   console.log('Restored state:', restored);
   activatePage(restored.tab, restored.filters);
}

State restoration (SaveState → details.currentState) is separate from the reload event, which carries Epic's navigation-history package. Do not use reload to restore saved state.

Navigation History

The library supports managing navigation history, tracking user interactions with Back/Forward buttons, and maintaining app-specific navigation states.

Listening to Navigation Events

Use onNavigate to track Back/Forward button clicks.

Example:

agl.on('navigate', ({ direction }) => {
   console.log(`Navigated: ${direction}`);
   // Handle navigation here
});

Saving Navigation History

Save custom navigation states using SaveHistoryState. AGL.js will persist these states for the current session.

Example:

agl.do('Epic.Clinical.Informatics.Web.SaveHistoryState', {
   state: JSON.stringify({ tab: 'dashboard', filters: { active: true } })
});

Disabling Navigation Buttons

Disable Back/Forward buttons in unsupported contexts.

Example:

agl.do('Epic.Clinical.Informatics.Web.SetEnabledHistBtns', {
   Back: false,
   Forward: false
});

Teardown

AGL.js installs one persistent message listener for the session. Call destroy() to remove it, settle any outstanding actions as false, and release the singleton. A later new AGL() then performs a fresh handshake.

Example:

agl.destroy();

The instance is also disposable, so using cleans it up automatically:

{
   using agl = new AGL();
   await agl.active;
   await agl.do('SaveState', { state: 'example' });
} // destroy() runs here

Migrating from 1.x

| Change | 1.x | 2.0 | |--------|-----|-----| | active | Returned boolean after init | Always returns Promise<boolean> — always await it | | reload payload | { state, fromHibernation } (unverified) | Raw historyPackage object | | State restore | Documented via reload | Read details.currentState after await agl.active | | CommonJS | require('agljs').default | require('agljs') | | Script-tag global | window.agl | window.AGL | | Print | (none) | onPrint / on('print', ...) | | Teardown | (none) | destroy() / [Symbol.dispose] | | Runtime | ES2022 | ES2024 with Symbol.dispose |

2.0 targets ES2024 and requires Symbol.dispose (modern Chromium/Edge).

Contributing

Fork, branch, and open a pull request.

License

Kopimi. Free to use, modify, and share. If the code is used, borrowed, modified, or incorporated into a commercial product or service, attribution is required.