Reference Type: Supported, Category: Alerts, Integration Agreement: 10081
This API sends alerts to users. This is the preferred API rather than
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.
Make sure to perform the following steps before calling this 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:
>S XQA(USERDUZ)="" >S XQA("G.MAILGROUP")=""
(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
(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.
(optional) Alert flag to regulate processing (currently not supported). The values are:
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.
(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
(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.
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:
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.
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.
Once the routine or option finishes, Alert Handler deletes the alert, under the following conditions:
If XQAKILL remains at the value of 1 as it was set in Step #1 above, the alert is deleted for the current user only.
To prevent the alert from being deleted, KILL XQAKILL during Step #2 above. You may not want the alert to be deleted if processing, such as entering an electronic signature, was not completed.
To delete the alert for all recipients of the alert, not just the current user, set XQAKILL to zero (0) during Step #2 above. When XQAKILL is set to 0, Alert Handler searches for any alerts with a matching Alert Identifier, all three semicolon pieces:
It purges them so that other users need not be notified of an
NOTE: To delete an alert for all recipients, you must define XQAID with appropriate specificity when creating the alert.
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 N XQA,XQAARCH,XQADATA,XQAFLG,XQAGUID,XQAID,XQAMSG,XQAOPT,XQAROU,XQASUPV,XQASURO,XQATEXT,XQALERR 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." S VAR=$$SETUP1^XQALERT I ‘XQALERR W !,"ERROR IN ALERT: ",XQALERR Q
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:
June 28, 2012