EpicACT Link Usage

Internal (Epic and EpicACT) links can enhance workflows for users by embedding needed information and actions so that workflows are not interrupted to find information or take related actions. However, such links need to be used with care... and tested extensively. A number of potential problems may arise. This section will grow with experience.

Link Syntax - Activities and Parameters

All EpicACT links have a common format.

  • EpicACT:Activity_Descriptor,Runparams:Param=value(s)

The Activity Descriptor must be present, whereas Run Parameters are not always required. Run Parameters can take a variety of formats but generally include one or more parameters ("Param") coupled with "value(s)". The examples offered in the EpicACT Link Library help builders appreciate how parameters are specified and delimited.

Parameter specifications can be finicky. They are not well documented, with the ordering and delimiting of parameters varying from link to link and following no consistent style or schema. And parameters can look quite different for different Epic modules.

We recommend using the Connect Care EpicACT link library as much as possible. Full links (with parameters and values) are provided for common navigational, informational and data management tasks. These have been tested in Connect Care.

Activity Permissions

It is possible for a correct activity descriptor to be used in a navigational internal link, for example, but for Hyperspace to reject the link by indicating that it is not allowed for the current user. It is likely that the activity in question has not been added to the Connect Care "Browser Allowlist". In most cases, a needed activity descriptor can be added to the allowlist. Follow instructions provided in that section of the handbook.

HyperLinks and Special Characters

EpicACT internal link run parameter may include characters that have a special meaning when included in Internet universal resource locators (URLs, or hyperlinks). When an EpicACT link is added to text as a hyperlink, those special characters may interfere with Epic's parsing of the EpicACT instructions. In such cases, it is better to use a different EpicACT link syntax:

  • EpicACT:Activity_Descriptor,RunParamsURLencoded:Param=value(s)

The "RunParamsURLencoded" tells Epic to look for special "ASCII escape codes" within the EpicACT link and to convert those to special characters before parsing the link for its meaning. The most common special characters and escape codes are documented separately.

Activity Contexts

If an internal link is used to open a relevant activity within a patient's chart, builders should wary of activities that are not available in all contexts. Some may be limited to specific roles, departments or modules (e.g., ASAP for emergency providers).

Navigator Activities

Internal links that open navigators (e.g., Discharge Navigator), possibly additionally moving to specific navigator sections (e.g., Discharge Summary), are at particular risk of not working in all clinical contexts. While it is obvious that they will not be available in outpatient contexts (and builders would avoid links for those navigators there), it may not be appreciated that the same Navigator may have a different activity descriptor in different modules within the same context. The discharge navigator, for example, is available as a separate activity to charts opened in a general inpatient mode but is found within a navigators activity in surgical inpatient contexts (OpTime). Different navigator activity descriptors must be used in OpTime. Accordingly, builders should consider limiting such links to a build objects that appear only in the correct context, or that can be dynamically adjusted with context-checking rules.