Kernel 8.0 APIs Banner [skip navigation]
Office of Information & Technology (OIT) Banner

$$SETUP1^XQALERT: Send Alerts

Reference Type: Supported, Category: Alerts, Integration Agreement: 10081


This API sends alerts to users. This is the preferred API rather than SETUP^XQALERT.

To send an information-only alert, make sure that XQAOPT and XQAROU input variables are not defined. To send an alert that takes an action, specify either the XQAOPT (to run an option) or XQAROU (to run a routine) input variables.



Input Variables

Make sure to perform the following steps before calling this API:

  1. NEW all non-namespaced variables.

  2. Set the input variables you want changed.

  3. Call the API.

(required) Array defining at least one user to receive the alert. Subscript the array with users' DUZ numbers to send to individual users; subscript the array with mail group names to send to users in mail groups:


(optional) Number of days that alert tracking information for this alert should be retained in the ALERT TRACKING file (#8992.1). Default time period is 30 days. You can specify a different number of days using this input variable.

NOTE: Critical patient data, as part of medical records, should be retained for at least 65 years, which is 23,725 days. To retain information forever, a value of 100000 is recommended (good for about 273+ years). Sites may not have sufficient disk storage space to accommodate this need, however.


(optional) Setting a value in the XQACNDEL variable prior to calling this API causes the CAN DELETE WITHOUT PROCESSING field (#.1) in the ALERT file (#8992) to be set. A value in this field indicates that the alert can be deleted by the user without having processed it.


(optional) Use this to store a software application-specific data string, in any format. It will be restored in the XQADATA input variable when the user processes the alert and is therefore available to the routine or option that processes the alert.

You can use any delimiter in the input variable, including the caret. You can use it to make data such as patient number, lab accession, or cost center available to your software application-specific routine or option without needing to query the user when they process the alert. It is up to your routine or option to know what format is used for data in this string.


(optional) Alert flag to regulate processing (currently not supported). The values are:

  • D—To delete an information-only alert after it has been processed (the default for information-only alerts).

  • R—To run the alert action immediately upon invocation (the default for alerts that have associated alert actions).

This input variable currently has no effect, however.


(optional) As of Kernel Patch XU*8.0*207, the GUID FOR GUI adds an interface GUID (a 32 character string containing hexadecimal digits in a specific format within curly braces) to permit a program on the client to process the alert. The presence of a GUID in the variable indicates that the alert can be processed within a GUI environment, and is used to open the correct application to process the alert within the GUI environment.

NOTE: Currently, this functionality has not been implemented by CPRS or other GUI applications.


(optional) Package identifier for the alert, typically a software application namespace followed by a short character string. Must not contain carets ("^") or semicolons (";"). If you do not set XQAID, you will not be able to identify the alert in the future, either during alert processing, to delete the alert, or to perform other actions with the alert.

NOTE: For information on CPRS conventions for the format of the Package Identifier, please refer to the "Package Identifier versus Alert Identifier" topic in the Kernel Developer's Guide.


(required) Contains the text of the alert. 80 characters can be displayed in the original alert. 70 characters can be displayed in the View Alert listing. The string cannot contain a caret ("^").


(optional) Name of a non-menu type option on the user's primary, secondary or common menu. The phantom jump is used to navigate to the destination option, checking pathway restrictions in so doing. An error results if the specified option is not in the user's menu pathway.

XQAREVUE: (optional) This variable is used to set the DAYS FOR BACKUP REVIEWER field (#.15) in the ALERTS file (#8992). It must be an integer from 1 to 15.
XQAROU: (optional) Indicates a routine or tag^routine to run when the alert is processed. If both XQAOPT and XQAROU are defined, XQAOPT is used and XQAROU is ignored.

(optional) Supervisor forwarding. Number of days to wait before Delete Old (>14d) Alerts option forwards alert to recipient's supervisor, if unprocessed by recipient. Can be a number from 1 to 30. Supervisor is determined from the recipient's NEW PERSON file (#200) entry pointer to the SERVICE/SECTION file (#49), and then the entry (if any) in the pointed-to service/section's CHIEF field.


(optional) Number of days to wait before Delete Old (>14d) Alerts option forwards alert to recipient's MailMan surrogates (if any), if alert is unprocessed by recipient. Can be a number from 1 to 30.


(optional) As of Kernel Patch XU*8.0*207, this variable permits informational text of any length to be passed with an alert. When the alert is selected, the contents of this variable will be displayed in a ScreenMan form within the roll & scroll environment.

NOTE: It was also intended to be displayed within a text display box within the GUI environment. Currently, CPRS has not implemented this functionality, so it can only be viewed in the roll & scroll environment.




  • 1—The alert was sent successfully.

  • 0—The alert was not sent successfully, in which case the XQALERR variable will contain a text string indicating the reason that the alert was not sent.

It the alert was sent successfully, this variable will be null. If the alert was not sent successfully, this variable will contain a text string that indicates the reason that the alert was not sent.


Once the alert is created, the user is then able to receive and process the alert from their View Alerts listing. When this occurs, Alert Handler executes the following four steps for the alert:

  1. Alert Handler sets up the following input variables:

    If you associated a software application identifier, XQAID, with the alert, it is restored along with two additional semicolon pieces:

    With the two additional semicolon pieces, the software application identifier becomes the alert identifier. If you did not define XQAID when creating the alert, Alert Handler sets XQAID input variable to "NO-ID" followed by the two additional semicolon pieces.

  2. Alert Handler runs the routine or option specified, if any, in the XQAOPT or XQAROU input variables.

    You can refer to the three input variables listed above (i.e., XQADATA, XQAID, and XQAKILL) in the option or routine that processes the alert.

  3. Once the routine or option finishes, Alert Handler deletes the alert, under the following conditions:

  4. Finally, the Alert Handler cleans up by KILLing XQADATA, XQAID, and XQAKILL. Alert Handler returns the user to the View Alerts listing if pending alerts remain. Otherwise, Alert Handler returns the user to their last menu prompt.


Alerts: Call to send an alert sample:

;send an alert
;assume DFN is for patient KRNPATIENT,ONE
S XQA(161)="" ; recipient is user `161
S XQAMSG="Elevated CEA for "_$$GET1^DIQ(2,DFN_",",.01)_" ("_$E($$GET1^DIQ(2,DFN_",",9),6,9)_")
 Schedule follow-up exam in Surgical Clinic."

Alerts: Resulting alert, from View Alerts option

Select Systems Manager Menu Option: "VA

 1.I  Elevated CEA for KRNPATIENT,ONE (5345).  Schedule follow-up exam in Surgical Clinic.
          Select from 1 to 1
          or enter ?, A, I, P, M, R, or ^ to exit:


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: June 28, 2012

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.