2

D1
64
BD
B2
4F
-1
32
Integrating External Web
87
Content with Active Guidelines 4-
A1
-4

Last Updated: January 31, 2020

AD

Epic | 1979 Milky Way | Verona, WI 53593 | Voice: 608.271.9000 | Fax: 608.271.7237 | www.epic.com | documentation@epic.com
B
-3
61
0F
11
08
D:
UI
icU
Ep
 Table of Contents

Integrating External Web Content with Active Guidelines 3

2
Business Overview 3

D1
Make a Plan 3
Reach the Right Target Audience 3

Determine What Web Request Your Vendor Requires 4

64
Interaction with Epic 4
Supported Versions 4

BD
Distinguishing between the new and old framework 5

Configuring Interaction with Epic in Epic 2015 and Previous Versions 6

Configuring Interaction with Epic in Epic 2017 and Later Versions 6

Placing Orders 12

B2
Placing Orders in Epic 2015 and Previous Versions 12

Placing and Removing Orders in Epic 2017 and Later Versions 14

Filing Flowsheet Data 22

4F
Other Configuration Options Available in Epic 2017 and Later Versions 23
Launching Hyperspace Activities 23

-1
Opening a new window 24

Closing AGL 24

Hibernation and Saving State 25

32
FAQs 25

87
4-
A1
-4
B AD
-3
61
0F
11
08
D:
UI
icU
Ep

Integrating External Web Content with Active Guidelines 2

 Integrating External Web Content with Active
Guidelines

2
D1
Presents an overview of hosting external web content within Active Guidelines, and instructions about how to let
clinicians interact with the external web content. Active Guidelines can interact with Epic by programmatically

64
taking actions such as placing orders, launching activities, and filing flowsheet rows.

BD
Business Overview

B2
You can host external web content inside Epic using Epic’s Active Guidelines ﴾AGL﴿ framework, formerly referred

4F
to as Clinical Knowledgebase ﴾ClinKB﴿. From a user’s perspective, AGL behaves like an internet browser which can
appear inside the context of a patient chart and automatically send out information relevant to that patient.

-1
Unlike a typical browser, the user cannot simply type in any URL they want. Instead, you need to set up a web

32
integration record pointing to the destination, which includes the URL along with other information needed for
building an HTTP request. The hosted webpage can show static information, such as clinical content relevant to

87
the patient, or it can take some actions on the patient chart, such as allowing the provider to place orders in the
patient’s chart from the external webpage.

4-
From a technical perspective, the hosted webpage is a sandboxed iframe endowed with web messaging
A1
capabilities to safely navigate cross‐domain content.
-4

Make a Plan
AD

The web developer and the analyst should work together to answer the following questions:
B

1. Which users should have access to the web app?

-3

2. From where in the patient chart should users access the web app?
61

3. What information does the web app require from Epic?

Reach the Right Target Audience

0F

To make the web app as effective as possible, think carefully about who the target audience is and how they
11

should access the web app.

08

Targeting Providers
The analyst can set up a web integration record in Epic to reach a specific target audience. For example, if the
D:

web app applies only to radiologists, the analyst can easily configure this restriction directly in the web
integration. For finer control over filtering, web integrations also tie into profile records, which allows
UI

configuration at different levels of the healthcare organization, such as by department. The analyst and web
developer should examine the organization's profile structure together to see if it can be used.
icU

Targeting Topics
There are many entry points to AGL throughout the patient chart, including entry points from buttons and from
Ep

options in a right‐click menu. Web integrations can be set up to filter by context. For example, if the web

Integrating External Web Content with Active Guidelines 3

 developer is supplying content specifically targeting medications, the analyst can set up the web integration to
appear only for entry points related to medications, and to not appear when a user opens AGL from another
entry type, such as an entry type of diagnosis.

2
Determine What Web Request Your Vendor Requires

D1
AGL sends out a web request with the patient context sent as URL parameters or POST parameters. The web

64
developer chooses the type of request, GET or POST, and the format for the parameters, HL7 Infobutton or a
custom request. The analyst must then configure the web integration record accordingly, depending on what type

BD
of request and format the web developer requires.

HL7 Infobutton

B2
Epic recommends using the HL7 standard Context Aware Knowledge Retrieval Application, or Infobutton, which
allows an EHR to send a snapshot of the patient chart by means of a robust collection of well‐defined GET or

4F
POST parameters. Epic’s implementation of Infobutton is fully compliant with Meaningful Use. For more
information about the Infobutton standard, visit www.hl7.org.

-1
Custom Requests

32
For situations where HL7 Infobutton is not the right tool, Epic provides a framework for creating custom requests.

87
For example, this might be the case if your website is designed to search only on a specific term without patient
context, or if it needs information not supported by Infobutton. The analyst and the web developer need to work

4-
together closely to build custom integrations.
A1
Interaction with Epic
-4
AD

The analyst can set up a web integration so that users can take actions from within the web app that have
immediate effect in the patient’s chart in Epic. Currently, AGL supports allowing providers to place orders, launch
activities, and file flowsheet rows from your hosted web app.
B

Supported Versions
-3
61

HTML content is rendered by the instance of Internet Explorer ﴾IE﴿ installed next to Epic. The level of support for
HTML5 and CSS3 is completely dependent on which version the organization has installed. Epic 2014, Epic 2015,
0F

and Epic 2017 target IE 11, although it cannot be guaranteed that every Epic organization is in sync. There is a
caveat to web apps that place orders in Epic 2014 and Epic 2015. Refer to the Browser Compatibility section for
11

more information.

Version Differences
08

In Epic 2015 and previous versions, to allow users to take actions from the web app, the web developer needs to
D:

embed custom XML tags directly in the HTML. The XML is parsed out by Epic and converted into hyperlinks.

Starting in Epic 2017, communication with AGL uses JavaScript, which the web developer can tie to any HTML
UI

control he desires, such as buttons. AGL is backed by an embedded iframe, and the rules around cross‐origin
resource sharing ﴾CORS﴿ apply.
icU

Starting in May 2020, EpicCare Link also uses JavaScript to communicate with AGL. In February 2020 and earlier
versions, EpicCare Link uses XML.
Ep

Integrating External Web Content with Active Guidelines 4

 Functionality Epic 2015 Epic 2017

Place orders. X X

2
D1
Override some order defaults, including order mode X X
and indications of use.

64
BD
Override more order defaults, including display name, X X
decision support session, decision support score,
comments associated with indications of use, and

B2
order‐specific questions and answers.

4F
Specify whether the original order is removed. X X

-1
32
File a value to a flowsheet row when AGL is opened X X
from that row.

87
from locations other than the flowsheet row. 4-
File a value to a flowsheet row when AGL is opened X
A1
-4

Pend flowsheet values. X

AD

Pend or file data to multiple flowsheet rows at the X

same time.
B
-3

Override the display name of a flowsheet row. X

61
0F

Distinguishing between the new and old framework

11

In Epic 2017 and later versions, the Epic 2015 framework is not available. The web app is responsible for
08

distinguishing between the two versions and taking the user to the appropriate source depending on context.
There are two methods for accomplishing this.
D:

Listen for Epic 2017

UI

As described below, Epic 2017 relies on JavaScript web messaging to interact with the web app. The web app
requests an initial handshake with some information on load ﴾such as a "token" and "version"﴿. If Epic responds
icU

with that handshake, then the web app knows that it is hosted in Epic 2017. If Epic does not respond, then the
web app is hosted in Epic 2015.
Ep

Divert by IP address

Integrating External Web Content with Active Guidelines 5

 With this method, the web developer keeps a map of IP addresses associated to Epic organizations, and works
with those organization to determine when they will upgrade to Epic 2017. As each organization upgrades, the
web developer flips the switch for that organization to allow those IP addresses to receive Epic 2017 content

2
instead of Epic 2015 content.

D1
Configuring Interaction with Epic in Epic 2015 and

64
Previous Versions

BD
In Epic 2015 and previous versions, to allow users to take actions from your webpage, you need to embed custom
XML tags directly in your HTML. The XML is parsed out by Epic and converted into hyperlinks.

B2
Can the XML be dynamically generated? ‐ No
The XML is parsed out by Epic and converted into hyperlinks. This XML cannot be added dynamically. It must be

4F
statically present when the page loads; that is, when the DocumentComplete event is triggered. This is because
Epic listens on the DocumentComplete event and converts these XML elements into Anchor ﴾A﴿ elements that

-1
render as hyperlinks.

32
Browser Compatibility

87
As browsers are becoming increasingly strict about HTML compliance, newer versions of IE ﴾9+﴿ do not allow you
to embed custom XML tags. To get around this, you must include the following META tag in the HEAD element of

4-
your page’s HTML markup.
A1
<meta content="IE=8" http‐equiv="X‐UA‐Compatible" />

This will force IE to render the content as IE8 would, so test accordingly.
-4

Recommendations
AD

If your web app needs features provided by newer versions of IE, but still needs to place orders or file flowsheets,
Epic recommends that you factor out these follow‐up actions into a separate page within your app. In that case,
B

the above META tag needs to be applied only on this page.

-3

Likewise, if the user interfact for performing follow‐up actions is a hyperlink ﴾as described above, Epic converts
the XML elements into anchor elements﴿ and this becomes a limitation for the web developer, then he can wrap a
61

Paragraph ﴾P﴿ element with an explicit ID around the XML element. This Paragraph element can be styled as not
displayed. Epic will convert the XML element within this Paragraph element into an Anchor element on the
0F

DocumentComplete event. Thereafter, the web app can perform the follow‐up by executing a JavaScript “Click﴾﴿”
method on the Epic generated Anchor element child of the above explicitly identified Paragraph element. Do not
11

try to inspect the Anchor element, because we do not guarantee that the structure will not change.
08

Configuring Interaction with Epic in Epic 2017 and Later

D:

Versions
Starting in 2017, AGL is backed by an embedded iframe and the rules around cross‐origin resource sharing
UI

﴾CORS﴿ apply. This imposes the following restrictions:

icU

1. The web app must be frameable. Web pages can prevent themselves from being framed by using the
HTTP header X‐Frame‐Options ﴾and possibly other mechanisms﴿. Do not use this header or any other ways
to prevent being hosted within an iFrame. If you do, Epic will be unable to render your web app and users
Ep

see an error that says “This content cannot be displayed in a frame.”

Integrating External Web Content with Active Guidelines 6

 2. The web app must use HTTPS. For security reasons, the external web server must use SSL. If the URL in
the web integration does not begin with “https“ AGL opens the app in an external browser and provides no
Epic integration support. Users can view content, but the ability to interact with Epic is not available. This

2
means users cannot take actions within Epic from the external page. If the certificate provided is invalid,

D1
the user is warned before proceeding.
3. The web app cannot attempt to navigate outside of its window. The sandboxing on the iframe

64
prevents top‐navigation. If the web developer needs to navigate the user, he can do so on the window
level, or else open in a new window using the API provided. Refer to the Opening a new window section

BD
for more information.
The sandboxing on the iframe allows popups, JavaScript, and form submission.

B2
Web Messaging
Communication with AGL in Epic 2017 and later versions uses JavaScript, which you can tie to any HTML control

4F
you desire, such as buttons.

-1
Communication between AGL and your webpage takes place using the HTML5 standard called web messaging.
This JavaScript API ﴾postMessage﴿ allows two pages from different domains, one framed inside the other, to

32
communicate. Communication takes place in the post office style. Messages are posted to a window and a listener
assigned to that window responds. Messages are objects subject to some minor restrictions imposed by HTML5

87
﴾not Epic﴿. For example, your object cannot contain functions.

To post an object obj to window win, use:

4-
A1
win.postMessage(obj, '*');
-4

The second argument restricts by domain. Because many domains are involved in a typical organization, we don’t
AD

recommend using this argument.

On the other end, a listener needs to be set up attached to the same window. The event argument to the Listener
B

function has two properties: origin ﴾which is not currently being used﴿ and data. If the Listener were to catch the
-3

message posted above, then event.data = obj. From here on, we will refer to event.data as the payload.
61

To set up a listener, use:

function Listener(event) {
0F

var obj = event.data;

11

. . .
08

win.addEventListener("message", Listener, false);

D:
UI

Listening to Epic
icU

As JavaScript objects, messages from Epic consist of key/value pairs. Here is a list of potential keys which the web
app could receive from AGL:
Ep

error. If Epic needs to send an error to the web app, it uses this tag followed by a string. In JSON, this
would look like this:

Integrating External Web Content with Active Guidelines 7

 { "error": "A detailed error message." }

2
D1
token. To communicate with Epic, the web app needs to return a token with every call to postMessage
except the initial handshake. This token is provided to you in the initial handshake response like this:

64
BD
{ "token": "String identifier." }

B2
actions. This identifies a list of actions supported by AGL within the current context and which your web
app is allowed to call. This allows you to develop a web app which might have different behavior in

4F
different versions of Epic or in different workflows etc. Some actions are restricted by context. For example,
if a chart is read‐only, orders cannot be placed or removed, so no orders‐related action would appear in

-1
this list.

32
87
{ "actions": [ "action 1", "action 2", ... ] }

4-
version. This identifies the current version of the JavaScript interface. As Epic makes changes to this
A1
interface, we will update the version so that web developers can keep track of which version they are
interfacing with. In Epic 2017 with special update C8318738, the version is 10.0.
-4
AD

{ "version": "10.0" }
B

state. In case of hibernation, as described in the Hibernation and Saving State section, the web app can
-3

save off a string of information checkpointing state using the appropriate command. The saved information
61

is sent back with the initial handshake using this tag.

0F

{ "state": "Some string which you have previously saved." }

11
08

actionExecuted. After the web app requests an action, it needs to wait for a response indicating that the
action has been completed before sending the next message. This response is always returned with a
D:

boolean saying whether the action has been executed or not. Any message sent after an initial message is
sent and before the next actionExecuted has returned is ignored.
UI

{ "actionExecuted": true or false }

icU
Ep

errorCodes. In addition to sending a plain error message to the web app ﴾using the “error” property﴿ Epic
might also send a list of error codes for any errors encountered along the way that might be helpful for the

Integrating External Web Content with Active Guidelines 8

 web app to determine how to respond. Currently, only a few error codes are supported that are relevant
for the ordering actions:
[0] The order key specified by the web app could not be mapped.

2
D1
[1] The order could not be replaced. This means that in the replace workflow, a new order could
not be placed ﴾though the triggering order might have been removed﴿.

64
[2] The order could not be removed.

BD
[3] Defaults were invalid.

B2
{ "errorCodes": [2,1] }

Here is an example of a message that might be received if your web app attempts to place an order into a read‐

4F
only chart:

-1
{

32
error: "The action is not allowed in the current workflow.",

actionExecuted: false

87
}

4-
In keeping with the client‐server paradigm, your webpage requests an initial handshake from AGL. AGL responds
A1
with a handshake that includes token, features, and state, if any state was saved. In this way, your webpage can
detect whether it is being hosted in Epic AGL or some other browser.
-4

The code snippet below is designed to request the initial handshake and respond to it.
AD

function Listener(event)

{
B

for (var type in event.data)

-3

{
61

var payload = event.data[type];

0F

switch (type)

{
11

case "token":
08

// this is the token passed down by Epic

// which every post message needs to include

D:

epicToken = payload;
UI

break;
icU

case "error":

// payload is an error string

Ep

break;

Integrating External Web Content with Active Guidelines 9

 case "actions":

// payload is a list of features (or actions)

for (var feature in payload)

2
D1
{

// feature is a string representing a single feature

64
}

BD
break;

case "state":

B2
// payload is some state which you have saved

4F
// before AGL hibernated

break;

-1
case "actionExecuted":

32
// payload is a boolean set to "true" if the action

87
// completed, "false" otherwise

4-
break; A1
case “errorCodes”:

// payload is an array of all errors which might have been // encount

-4

ered

break;
AD

default:
B

// if new properties get implemented which are not

-3

// handled above, you end up here

61

break;

}
0F

}
11

}
08

function onLoad()
D:

{
UI

// Add your listener

window.addEventListener("message", Listener, false);

icU

// Request the initial handshake

Ep

window.parent.postMessage({

"action": "Epic.Clinical.Informatics.Web.InitiateHandshake"

Integrating External Web Content with Active Guidelines 10

 }, "*");

2
To guarantee that the web app’s DOM is completely built before running any JavaScript, take advantage of your

D1
body tag's onload event:

<body onload="onLoad();"> . . . </body>

64
BD
Talking to Epic
AGL listens for messages at the parent window, not your webpage’s window. You must include the token which

B2
was passed down in the handshake. Other properties must be actions from the list of features, which was also
passed down in the handshake:

4F
window.parent.postMessage({

-1
"token": epicToken,

32
"action": name_of_action

87
"args": some_arguments

},"*");

AGL currently implements the following actions:

4-
A1
Epic.Clinical.Informatics.Web.InitiateHandshake
-4

Requests information from AGL

Epic.Clinical.Informatics.Web.PostOrder
AD

For placing orders

Starting in February 2020, Epic.Clinical.Informatics.Web.PostOrderByNDCID
B
-3

For placing orders by NDC ID instead of preference list key

Epic.Clinical.Informatics.Web.RemoveTriggerOrder
61

For removing order which triggered search

0F

Epic.Clinical.Informatics.Web.RemoveSpecifiedOrder
For removing order﴾s﴿ in BPA web service workflow
11

Epic.Clinical.Informatics.Web.ReplaceUnsignedOrder
08

For replacing one order with another

Epic.Clinical.Informatics.Web.PostFlowsheetRow
D:

For posting flowsheet rows

UI

Epic.Clinical.Informatics.Web.OpenExternalWindow
Replaces window.open
icU

Epic.Clinical.Informatics.Web.CloseActivity
Closes the current instance of AGL
Ep

Epic.Clinical.Informatics.Web.SaveState

Integrating External Web Content with Active Guidelines 11

 Saves some state in case of hibernation
The only action that does not require a token is InitiateHandshake.

2
D1
Placing Orders

64
Placing Orders in Epic 2015 and Previous Versions

BD
To map preference list orders to AGL content, add the following HTML markup for each order clinicians should be
able to place from AGL:

B2
<OrderTemplate Key="..." OrderMode="..." RemoveOriginal="...">

End‐user facing name of order

4F
</OrderTemplate>

-1
Key. Required for placing an order ﴾most cases﴿. A key which your third‐party data vendor and you have

32
agreed upon which will represent an order, along with some defaults. When configuring this attribute, you
must enter XML decoded versions of the following characters:

87
Original Character XML Decoded

< &lt; 4-
A1
-4

> &gt;
AD

" &quot;
B

& &amp;
-3
61

' &#39;
0F

﴾ &#40;
11
08

﴿ &#41;
D:
UI

OrderMode. Optional. Enter IP for inpatient or OP for outpatient. Orders can have different behavior based
on whether they are placed in an inpatient or outpatient setting. This property lets you override an order
icU

rather than pulling it from the context. For example, you can force an order to be placed as an inpatient
order even if it’s placed in an outpatient setting.
Ep

RemoveOriginal. Optional. Enter True if you want the order to act as a replacement order. This attribute
applies when a provider accesses AGL from an existing order in the patient chart. When a clinician then

Integrating External Web Content with Active Guidelines 12

 places an order from AGL and the original order is unsigned, the original order is removed and replaced by
the new AGL order. This attribute doesn't affect ordering behavior if the clinician hasn't yet placed an order.
Enter False or leave the attribute blank if you don't want the order to act as a replacement order. In this

2
scenario, any order placed from AGL is added as a new order without removing the original order.

D1
Overriding Order Defaults in Epic 2015 and Previous Versions
There is limited handling of default overrides. In order to override defaults, you first need to build a library of

64
potential defaults in the header of your page using XML as below. These tags are case‐sensitive.

BD
Your webpage must first include the following block in its header:
<xml id="Orders">

B2
<SSSection>

<SSSubsection>

4F
<OrderDefs>

-1
<OrderDef>

32
...

87
</OrderDef>

</OrderDefs>

</SSSubsection>
4-
A1
</SSSection>
-4

</xml>
AD

Under <OrderDef> you will specify a key using the <Defaults> XML tag and a list of defaults using an XML
B

tag corresponding to the default you want to override. Currently, you can override only indications of use:
-3

<OrderDef>
61

<Defaults> defaultkey </Defaults>

0F

<IndicationsOfUse> indication 1 </IndicationsOfUse>

11

<IndicationsOfUse> indication 2 </IndicationsOfUse>

08

</OrderDef>
D:

Then, in your <OrderTemplate> tag, reference your defaults using the Defaults attribute:
UI

<OrderTemplate Key="orderkey" Defaults="defaultkey">

icU

End‐user facing name of order

</OrderTemplate>
Ep

Integrating External Web Content with Active Guidelines 13

 Placing and Removing Orders in Epic 2017 and Later
Versions

2
D1
To allow the user to place an order, your webpage needs to send an object representing an order. Multiple types
of orders can be placed through AGL, including medications, procedures, and panels. Linked panel orders can be

64
placed in the same way as long as the linked group ﴾OSQ﴿ has been built and added to a preference list. The
following properties are available:

BD
OrderKey. Optional. If you want to allow the user to place an order, then this is required. This is a key
which you have agreed upon with your third‐party data vendor that represents an order, along with default

B2
values.
OrderName. Optional. This overrides the name of the order in Epic.

4F
OrderMode. Optional. Enter IP for inpatient or OP for outpatient. Orders can have different behavior based
on whether they are placed in an inpatient or outpatient setting. This property lets you override an order.

-1
For example, you can force it to be placed as an inpatient order even if it’s placed in an outpatient setting.

32
Scenario 1: Ordering a simple lab

In this example, imagine that you have a procedure built with key LAB0129. The name of the procedure shown in

87
the actions queue is pulled from Epic:

window.parent.postMessage({
4-
A1
token: epicToken,

action: "Epic.Clinical.Informatics.Web.PostOrder",
-4

args: { OrderKey: "LAB0129" }

AD

}, "*");

You can change the name of the order as it appears in the actions queue by using the OrderName key, but this is
B

not recommended.
-3

Removing Unsigned Orders in Epic

61

Two actions are provided to remove orders: RemoveTriggerOrder and RemoveSpecifiedOrder. RemoveTriggerO
rder takes no arguments, and can be used for two use cases: removing orders that were the target of a search,
0F

or removing orders that were pulled in from a BestPractice Advisory ﴾BPA﴿ that was configured to suggest the
removal of all triggering orders. RemoveSpecifiedOrder is designed for the BPA web services workflow and
11

takes as argument a comma‐delimited list of keys which the web app has discovered through BPA web services.
08

See the Integrating External Decision Support with Epic white paper for more information.

Note that when removing linked panel orders, we recommend removing the entire linked group rather than a
D:

single order from the group.

Scenario 2: Removing the order that was the source of a search

UI

Imagine that the user sees an unsigned order, right‐clicks the order, and chooses Search Active Guidelines. The
icU

web app can suggest that that order be removed with this workflow. Note that args is not used, because the user
can search on only one order at a time.
Ep

window.parent.postMessage({

token: epicToken,

Integrating External Web Content with Active Guidelines 14

 action: "Epic.Clinical.Informatics.Web.RemoveTriggerOrder"

}, "*");

2
Scenario 3: Removing some orders in the BPA web services workflow

D1
Here, the web app used BPA web services to determine that orders with order numbers 4 and 13 should be
removed. You can remove them with:

64
window.parent.postMessage({

BD
token: epicToken,

action: "Epic.Clinical.Informatics.Web.RemoveSpecifiedOrder",

B2
args: "4,13"

4F
}, "*");

-1
Scenario 4: Replacing an order

32
There are two methods the web app can use to replace an order: using the ReplaceUnsignedOrder action, or
executing a remove order and a new order action, one after the other. If you use the replace action, order defaults

87
from the preference list are respected; however, note that this method cannot replace orders that are components
of pathways, components of linked groups, orders that are being modified or reordered, or orders that are being

4-
placed from a database search. The following example pulls in defaults for a medication and overrides the dose:
A1
window.parent.postMessage({

token: epicToken,
-4

action: "Epic.Clinical.Informatics.Web.ReplaceUnsignedOrder",
AD

args: {

Dose: "400",
B

DoseUnit: "mg"
-3

}
61

}, "*");
0F

Alternatively, you can use a remove order action followed by a new order action. This method is not subject to the
limitations listed above, but it also does not respect order defaults from the original order. To use this method,
11

send one of the two remove order actions first to remove the original order. After you receive the actionExecute
d response, send a PostOrder action with the new order that needs to be placed.
08

Overriding Order Defaults in Epic 2017 and Later Versions

D:

You can use the following properties to override defaults in orders. All of these properties are optional.

IndicationsOfUse and IndicationsComment. Used to override indications of use default and associated
UI

comments. IndicationsOfUse can accept either a string or an array. IndicationsComment accepts only a
icU

string.
DecisionSupportSession and DecisionSupportScore. Used to override decision support session and
decision support score defaults.
Ep

OrderSpecificQuestions. This property accepts an array of objects, each of which represents a

Integrating External Web Content with Active Guidelines 15

 question/answer pair. Multiple answers can be specified for any one question. Properties underneath Orde
rSpecificQuestions include:
Key. This property represents a key in your Epic system that represents a question.

2
ParentQuestion. For cascading questions, use “1” to indicate the parent and “0” to indicate the

D1
children.

64
Answers. This property can point to either an object representing an answer or an array of such
objects. Each object has two properties:

BD
Answer. The answer ﴾a string﴿.
Comment. A comment associated with the answer.

B2
The following additional properties are available in Epic 2018 and Epic 2017 with special update C8307127:

Dose. Used to override the default dose. Enter a numeric string.

4F
DoseUnit. Used to override the default dose unit. Enter one of the following options:

-1
A dose unit from the category list in Epic ﴾I ECT 9010﴿.

32
Starting in February 2020, a dose unit that corresponds to a value that the analyst has set in an
interface ﴾AIF﴿ table using specification 9165‐CDS Order Defaults ‐ Dose Unit.

87
Frequency. Used to override the default frequency. Enter a frequency that corresponds to a value that the

4-
analyst has set in an interface ﴾AIF﴿ table using specification 9158‐CDS Order Defaults – Frequency.
Priority. Used to override the default priority. Enter a priority from the category list in Epic ﴾I ORD 120﴿.
A1
Route. Used to override the default route. Enter a route from the category list in Epic ﴾I ORD 7025﴿.
-4

AdminInstructions. Used to override the default admin instructions. Enter free text.
The following additional properties, which are used for overriding information in TPN orders, are available in Epic
AD

2018 and Epic 2017 with special updates C8305146 and C8311812:

InfusionSite. Used to override the default infusion site. Enter an infusion site from the category list in
B

Epic ﴾I ECT 8505﴿.

-3

InfusionRate. Used to override the default infusion rate. Enter a value measured in mL/hr.
61

Duration. Used to override the default duration. Enter a number of hours.

0F

DurationUnit. Used to override the default duration units. Enter a duration unit from the category list in
Epic ﴾I ECT 9080﴿.
11

LockDosingFields. Used to set the dosing fields to read‐only. This is set to Yes by default.
Weight. Used to override the default weight. Enter a weight measured in kilograms, allowing up to two
08

decimals.
Volume. Used to override the default volume. Enter a volume measured in mL.
D:

MixtureComponents. Beneath this property, you can add any of the following components:
UI

ComponentName or IonName. Enter an alphanumeric string that has been set in an Epic table ﴾AIF﴿ to
translate to an Epic medication record ﴾ERX﴿. For ion‐based TPNs, use IonName.
icU

ShouldAdd. Used to determine whether or not the ingredient will be selected. Enter Yes to include
this ingredient in your TPN or No to exclude it from your TPN. If left blank, the Epic order template
Ep

﴾OTL﴿ setting is used.

Frequency, Dose, and DoseUnit can also be added under MixtureComponents. See the details on

Integrating External Web Content with Active Guidelines 16

 these items above.
The following additional properties are available starting in February 2020. Some of these properties, like
duration, are similar to those used for overriding information in TPN orders, but can now be used for non‐TPN

2
medications.

D1
MedDuration. Used to override the default duration. Enter a number.

64
MedDurationUnit. Used to override the default medication duration unit. Enter a duration unit from the
category list in Epic ﴾I ECT 9080﴿.

BD
DispenseQty. Used to override the quantity of medication dispensed. Enter a number.
DispenseUnit. Used to override the unit of medications dispensed. Enter one of the following options:

B2
A dispense unit from the category list in Epic ﴾I ECT 9010﴿.
A dispense unit that corresponds to a value that the analyst has set in an interface ﴾AIF﴿ table using

4F
specification 9165‐CDS Order Defaults ‐ Dose Unit.

-1
Refill. Used to override the medication's refills. Enter a value for the medication's refills, such as a number
or a value like PRN.

32
DispenseDaysSupply. Used to override the number of days of medication that's dispensed. Enter a

87
number of days. When you use this override, you can't use any other dispense or refill override or the
setting in the DispenseDaysSupply override is ignored.

4-
Route. Used to override the default route. Enter a route from the category list in Epic ﴾I ORD 7025﴿.
A1
Pharmacy. Used to override the pharmacy the prescription is sent to. Enter the ID of a pharmacy. You must
set the PharmacyLookUp parameter as well to specify what type of Pharmacy ID you're using.
-4

PharmacyLookUp. Used to identify which Pharmacy ID is used. This parameter is required to use the
Pharmacy parameter. Enter 0 to use the NCPDP pharmacy identifier or 2 to use the NPI pharmacy identifier.
AD

Scenario 5: Overriding Other Defaults

In this scenario, indications of use and the associated indications of use comments for a lab order are overridden,
B

as well as the decision support session and score:

-3

window.parent.postMessage({
61

token: epicToken,
0F

action: "Epic.Clinical.Informatics.Web.PostOrder",
11

args: {

OrderKey: "LAB0129",
08

IndicationsOfUse: ["pain", "fever"],

D:

IndicationsComment: "Some comment",

DecisionSupportSession: "YOUR CDS SESSION ID",

UI

DecisionSupportScore: "17"
icU

}, "*");
Ep

The following additional properties are available in Epic 2017 and later versions:

Integrating External Web Content with Active Guidelines 17

 Dose. A numeric string used to override the default dose.
DoseUnit. A dose unit string from an Epic‐defined category list list used to override the default dose
unit.

2
Frequency. An interface table mapped string to override the default frequency.

D1
Priority. A priority string from an Epic‐defined category list used to override the default priority.

64
Route. A route string from an Epic‐defined category list to override the default route.
AdminInstructions. Used to override the default admin instructions. Enter free text.

BD
InfusionSite. An infusion site string from an Epic‐defined category list used to override the default
infusion site.

B2
InfusionRate. A value measured in mL/hr to override the default infusion rate.

4F
Duration. A value measured in DurationUnit to override the default duration.
DurationUnit. A duration unit string from an Epic‐defined category list used to override the default

-1
duration units.

32
LockDosingFields. Used to set the dosing fields to read‐only. This is set to Yes by default.
Weight. Used to override the default weight. Enter a weight measured in kilograms, allowing up to two

87
decimals.

4-
Volume. Used to override the default volume. Enter a volume measured in mL.
Scenario 6: Answering Questions
A1
In this scenario, we are filling in answers to questions with keys QUEST1 and QUEST2, which have been built by
-4

the analyst. The first question accepts only one answer, while the second accepts a list of answers. The second
answer for the second question has no associated comment.
AD

window.parent.postMessage({

token: epicToken,
B

action: "Epic.Clinical.Informatics.Web.PostOrder",
-3

args: {
61

OrderKey: "LAB0129",
0F

OrderSpecificQuestions: [
11

Key: "QUEST1",
08

Answers: {
D:

Comment: Comment for question 1,

UI

Answer: Answer for question 1

}
icU

},

{
Ep

Key: "QUEST2",

Integrating External Web Content with Active Guidelines 18

 Answers: [{

Comment: Comment for question 2,

Answer: Answer 1 for question 2

2
D1
}, {

Answer: Answer 2 for question 2

64
}]

BD
}]

B2
}, "*");

4F
Scenario 7: Overriding Mixture Orders

In this scenario, some components or ions in a mixture order are overridden with different components or ions.

-1
To override one or more of the default components or ions that are included in a mixture, first make sure the

32
order to place is a mixture, then use a MixtureComponents property in a PostOrder action to override defaults
for mixture components.

87
Mixtures can either be component‐based or ion‐based. If the mixture is component‐based, your

4-
MixtureComponents property specifies one or more components identified by the ComponentName property. If
the mixture is ion‐based, use the IonName property instead. You can specify the following properties for each
A1
component or ion in the MixtureComponents property:

ComponentName. Used in component‐based mixtures only. Enter an alphanumeric string that has been set
-4

in an Epic table ﴾AIF﴿ record to translate to an Epic medication ﴾ERX﴿ record.

AD

IonName. Used in ion‐based mixtures instead of ComponentName. Enter string from an Epic‐defined
category list.
B

ShouldAdd. Used to determine whether or not the ingredient will be selected. Enter Yes to include this
ingredient in your TPN or No to exclude it from your TPN. If this property is blank, the setting from the
-3

Epic order template ﴾OTL﴿ record for this order is used.

61

Frequency, Dose, and DoseUnit can also be added under MixtureComponents. Refer to Scenario 5:
Overriding other defaults for information about these properties.
0F

For example, to place an order for a mixture but override some default settings of the components:
11

window.parent.postMessage({
08

token: epicToken,

action: "Epic.Clinical.Informatics.Web.PostOrder",
D:

args: {
UI

OrderKey: "MIXTURETPN",

MixtureComponents: [
icU

ComponentName: "ECDEXTROSE",
Ep

ShouldAdd: "Yes",

Integrating External Web Content with Active Guidelines 19

 Frequency: "ECQ4H",

Dose: "10",

2
DoseUnit: "ml/day "

D1
},

64
ComponentName: "ECSODIUM",

BD
ShouldAdd: "No",

Frequency: "ECPRN",

B2
Dose: 8,

4F
DoseUnit: "mEq/kg"

}]

-1
}

32
} , "*");

87
Scenario 8: Overriding Panel Orders

4-
In Epic, an order panel is a group of individual orders that clinicians place as a unit. Note that this section does
A1
not apply to Order Sets, which are a separate ordering tool that also contains decision support.

This scenario overrides some of the individual orders in a certain panel. To override individual orders inside a
-4

panel, first make sure the order that your application places is an order panel, not an individual order, and then
use a PanelOrders property in a PostOrder action to override defaults for each individual order within the
AD

panel. In this example, one of the orders in the panel happens to be a mixture, so defaults for that can be
overridden in the same manner as described in scenario 7.
B

window.parent.postMessage({
-3

token: epicToken,
61

action: "Epic.Clinical.Informatics.Web.PostOrder",

args: {
0F

OrderKey: "ECTPNPANEL",
11

PanelOrders:
08

{
D:

PanelOrderName: "ECMIXTURETPN",
UI

MixtureComponents: Mixture Components overrides in scenario 7

icU

},

{
Ep

PanelOrderName: "fat emulsion",

Dose: 5,

Integrating External Web Content with Active Guidelines 20

 DoseUnit: "mL/hr",

LockDosingFields:"yes",

2
}

D1
]

64
}

} , "*");

BD
B2
Scenario 9: Overriding Order Defaults for Non‐TPN Orders and Specifying a Pharmacy

Starting in February 2020, you can override order defaults for non‐mixture medications and specify the pharmacy

4F
where the order will be sent. This works essentially the same as overriding order defaults in mixture medications,
but you'll use the MedDuration and MedDurationUnit properties instead of Duration and DurationUnit.

-1
window.parent.postMessage({

32
token: epicToken,

87
action: "Epic.Clinical.Informatics.Web.PostOrder",

4-
args: {

OrderKey: "5",
A1
OrderMode: "OP",
-4

Frequency: "DAILY",
AD

MedDuration: 25,

MedDurationUnit: "Days",
B

DispenseQty:25,
-3

DispenseUnit:"tablet"
61

Refill:3,
0F

Pharmacy:1506089,

PharmacyLookUp:0,
11

} , "*");
08
D:

Scenario 10: Placing Orders Using NCD ID

Starting in February 2020, you can use a medication's NCD ID to match your third‐party vendor's medication to a
UI

medication ﴾ERX﴿ record in Epic. To do so, use the PostOrderByNDCID action. This action is similar to the PostOrd
er action, but it requires the NCDID in the args parameter and does not allow the use of the OrderKey
icU

parameter.

window.parent.postMessage({
Ep

token: epicToken,

Integrating External Web Content with Active Guidelines 21

 action: "Epic.Clinical.Informatics.Web.PostOrderByNDCID",

args: {

NDCID: "55111‐682‐01",

2
D1
OrderMode: "OP",

Frequency: "DAILY",

64
Dose: 200,

BD
DoseUnit: "mg",

} , "*");

B2
4F
Filing Flowsheet Data

-1
Filing flowsheet data is much simpler than ordering. Think of flowsheets as a spreadsheet with different rows
representing different pieces of data and columns determined by time. To specify a value, Epic needs the row, the

32
value, and the column ﴾time﴿. The last is handled internally by Epic and is not specified by your webpage.

87
In a typical workflow, referred to below as the flowsheet workflow, the user opens AGL from a cell in the
flowsheets activity, in which case AGL remembers the location ﴾both row & column﴿ and you need to specify only

4-
the value. To guarantee that your webpage is accessed only from flowsheets, be sure that you list Flowsheets as
the only available context in the web integration record.
A1
Filing Flowsheet Data in Epic 2015 and Previous Versions
-4

Prior to Epic 2017, the only workflow supported is the flowsheet workflow described above. All your webpage
AD

needs to supply is the value, which you can do like this:

<FLODATA VALUE=”The value you wish to file">

B

Filing Flowsheet Data in Epic 2017 and Later Versions

-3

Epic 2017 offers some more flexibility. To send a flowsheet row to Epic for filing, use the command
61

Epic.Clinical.Informatics.Web.PostFlowsheetRow
0F

You can use this command to file to flowsheet rows that contain numeric, string, or custom list data, but not to
other types of rows, such as formula or min/max rows.
11

This command accepts the following properties:

08

RowID. Specifies the flowsheet row to which to file your value. For the flowsheets workflow described
above, leave this property blank unless you want to file to other rows. Work with your third‐party data
D:

vendor to specify the IDs of the flowsheet rows to which you want to file data.
RowName. Specifies the name of the row, which the user sees in your webpage. For the flowsheets workflow
UI

described above, leave this property blank unless you want to file to other rows.
icU

RowValue. Specifies the value to file to the flowsheet row. Be careful that your type matches the internal
type of row, which must be either numeric, string, or custom list.
Pend. By default, flowsheet rows are filed. If the value should be pended instead, set this property to True.
Ep

Integrating External Web Content with Active Guidelines 22

 Scenario 11: File a flowsheet row in the flowsheet workflow

In a typical scenario, a user opens AGL directly from a cell in the flowsheets activity. Therefore, your webpage
needs to supply only a value:

2
D1
window.parent.postMessage({

token: epicToken,

64
action: "Epic.Clinical.Informatics.Web.PostFlowsheetRow",

BD
args: { RowValue: value to file to row }

}, "*");

B2
4F
Scenario 12: File a flowsheet row from a non‐flowsheet workflow

You can also let the user file a flowsheet row even if he opens AGL from somewhere other than a flowsheet cell.

-1
In this case, you need to specify the row and name of the cell to which you want to file data:

32
87
window.parent.postMessage({

token: epicToken,

4-
action: "Epic.Clinical.Informatics.Web.PostFlowsheetRow",
A1
args: {
-4

RowValue: value to file to row,

AD

RowID: row ID,

RowName: end‐user‐facing name of row

B

}
-3

}, "*");
61
0F
11

Other Configuration Options Available in Epic 2017

and Later Versions
08

Launching Hyperspace Activities

D:

Available starting in Epic 2018, web apps hosted in Active Guidelines can launch activities in Hyperspace to
UI

navigate clinicians to the right place to complete a specific workflow. This requires the Epic analyst to set up a
mapping table to map the ActivityKey to an internal activity record. Work with your Epic analyst to come up with
icU

an ActivityKey for each activity by following the steps in the Allow Clinicians to Launch Hyperspace Activities from
Active Guidelines topic.
Ep

Launching Hyperspace activities is not supported from BestPractice Advisory web service‐driven weblink
launches.

Integrating External Web Content with Active Guidelines 23

 Scenario 13: Launch a Hyperspace activity

window.parent.postMessage({

2
token: epicToken,

D1
action: "Epic.Clinical.Informatics.Web.LaunchActivity",

args: {

64
PatientID: patient ID,

BD
ActivityKey: key for activity,

B2
}, "*");

4F
-1
Opening a new window

32
Internet Explorer prevents webpages hosted inside iframes from opening new windows. To circumvent this, you
can request that a new window be opened with the Epic.Clinical.Informatics.Web.OpenExternalWindow

87
command. The args parameter is designed to match window.open. To use multiple arguments, pass in an array.

4-
Scenario 14: Open a URL in a new window
A1
window.parent.postMessage({

token: epicToken,
-4

action: "Epic.Clinical.Informatics.Web.OpenExternalWindow",
AD

args: destination url

}, "*");
B
-3

Closing AGL
61

In some workflows, your webpage might decide that there is nothing for the user to do. In that case, you can
0F

request to close AGL using Epic.Clinical.Informatics.Web.CloseActivity. Be aware that if the user has
actions queued up which require them to click Accept, a warning appears before the window closes. If the user
11

chooses not to quit, your webpage receives the actionExecuted message with value false, which allows your
webpage to respond.
08

Scenario 15: Close AGL

D:

window.parent.postMessage({

token: epicToken,
UI

action: "Epic.Clinical.Informatics.Web.CloseActivity"
icU

}, "*");

Scenario 16: Close AGL and abort the signing process

Ep

In this scenario, the user has encountered AGL via a BPA which fired on the “sign order” trigger. Your web

Integrating External Web Content with Active Guidelines 24

 application has determined that the signing process should be aborted and presents the user with a “Cancel”
button. It knows it’s in the signing process because it received the CloseAndCancel and CloseAndContinue
actions with the handshake.

2
window.parent.postMessage({

D1
token: epicToken,

64
action: "Epic.Clinical.Informatics.Web.CloseAndCancel",

}, "*");

BD
Hibernation and Saving State

B2
4F
In some circumstances AGL might go into a state of hibernation. This can happen either when AGL is not currently
active or if the user locks the Epic session to step away from the workstation. In these cases, the iframe hosting

-1
the web app is destroyed.

32
To help provide a way around this, you can use Epic.Clinical.Informatics.Web.SaveState to checkpoint
some state with Epic. This string is returned to every navigation starting from your initial source using the state

87
property, described above. So, if your web app receives a "state," then you know that this not a new pageload, but
a hibernation restore and you can use the state checkpoint to bring the user back to where he last was. Note that

4-
this is only for hibernation. No state is preserved if the user navigates to another source or closes AGL.
A1
Scenario 17: Save off the current URL
-4

window.parent.postMessage({
AD

token: epicToken,

action: "Epic.Clinical.Informatics.Web.SaveState",
B

args: string representing state

-3

}, "*");
61
0F
11

FAQs
08

Q: What method of authentication should I use?

D:

A: Epic recommends using SMART on FHIR for authentication. AGL integrates with SMART on FHIR as of 2017
with some minor limitations on what actions can be taken by the web app ﴾for instance, it can place orders
UI

and override most, but not all defaults﴿. SMART on FHIR allows the web application to authenticate itself to
Epic. The reverse can established ﴾Epic to the application﴿ by whitelisting the FHIR server.
icU

Q: My application should only allow framing when hosted in Epic. To that end, I need to know the domains of
Ep

the host app. How do I obtain that?

Integrating External Web Content with Active Guidelines 25

 A: The web servers supporting AGL are called “Hyperspace Web Servers”. Typically an organization will have
at most 3. If the organization is hosted by Epic, you can use the token %CLIENTHOSTSOURCE% ﴾in November
2019 and later versions﴿ for the host name of the frame within Hyperspace where the application is hosted. In

2
August 2019 and earlier versions, they will need to contact their Client Systems TS for Hosting to get the host

D1
name of the frame within Hyperspace.

64
Q: My application needs to be able to print. Does AGL allow printing?

BD
A: AGL does nothing to restrict printing to the local printer using standard JavaScript ﴾like window.print()﴿. You
can leverage CSS’ @media print query to restyle your page for printing.

B2
4F
Q: What is the difference between using cookies and saving state?

A: Cookies are tied to the user session and cannot distinguish between instances of AGL. State is tied to each

-1
instance of AGL. Think about this example: Suppose a user logs into Epic, opens a patient and launches AGL
in that patient context. Then the user launches a second instance of AGL pointing to the same application.

32
Any cookies created by the application in the first instance of AGL will be available to it in the second

87
instance, regardless of whether or not that first instance was closed or not. This is true even if the patient
context for second instance was different. State from the first instance, however, will not be passed to the

4-
second. State is cleared when AGL is closed. Cookies are cleared when the user logs out.
A1
-4
B AD
-3
61
0F
11
08
D:
UI
icU
Ep

Integrating External Web Content with Active Guidelines 26

©2018 ‐ 2020 Epic Systems Corporation. All rights reserved. PROPRIETARY INFORMATION ‐ This item and its contents may not be accessed, used, modified,
reproduced, performed, displayed, distributed or disclosed unless and only to the extent expressly authorized by an agreement with Epic. This item is a Commercial
Item, as that term is defined at 48 C.F.R. Sec. 2.101. It contains trade secrets and commercial information that are confidential, privileged and exempt from disclosure
under the Freedom of Information Act and prohibited from disclosure under the Trade Secrets Act. After Visit Summary, Analyst, App Orchard, ASAP, Beacon, Beaker,
BedTime, Bones, Break‐the‐Glass, Bugsy, Caboodle, Cadence, Canto, Care Everywhere, Charge Router, Chronicles, Clarity, Cogito ergo sum, Cohort, Colleague, Comfort,

2
Community Connect, Cosmos, Cupid, Epic, EpicCare, EpicCare Link, Epicenter, Epic Earth, EpicLink, EpicWeb, Garden Plot, Good Better Best, Grand Central, Haiku, Happy

D1
Together, Healthy Planet, Hyperspace, Kaleidoscope, Kit, Limerick, Lucy, Lumens, MyChart, OpTime, OutReach, Patients Like Mine, Phoenix, Powered by Epic, Prelude,
Radar, Radiant, Resolute, Revenue Guardian, Rover, Share Everywhere, SmartForms, Sonnet, Stork, System Pulse, Tapestry, Trove, Welcome, Willow, Wisdom, With the
Patient at Heart, and WorldWise are registered trademarks, trademarks, or service marks of Epic Systems Corporation in the United States of America and/or other

64
countries. Other company, product, and service names referenced herein may be trademarks or service marks of their respective owners. Patents Notice:
www.epic.com/patents.

BD
B2
4F
-1
32
87
4-
A1
-4
B AD
-3
61
0F
11
08
D:
UI
icU
Ep

Integrating External Web Content with Active Guidelines 27