Kernel APIs: SETUP^XQALERT

SETUP^XQALERT: Send Alerts

Reference Type: Supported, Category: Alerts, ICR#: 10081

The SETUP^XQALERT API sends alerts to users; however, the preferred API to use is $$SETUP1^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.

Format

  SETUP^XQALERT

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

NEW all non-namespaced variables.
Set all input variables.
Call the API.

Input Variables

XQA:	(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")=""
XQAARCH:	(optional) Number of days that alert tracking information for this alert should be retained in the ALERT TRACKING (#8992.1) file. Default time period is 30 days. Users can specify a different number of days using this input variable. To retain information forever, a value of 100000 is recommended (good for approximately 220 years).
XQACNDEL:	(optional) Setting a value in the XQACNDEL variable prior to calling this API causes the CAN DELETE WITHOUT PROCESSING (#.1) field in the ALERT (#8992) file to be set. A value in this field indicates that the alert can be deleted by the user without having processed it.
XQADATA:	(optional) Use this to store a software application-specific data string, in any format. It is 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.
XQAFLG:	(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.
XQAGUID:	(optional) As of Kernel Patch XU8.0207, 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: This functionality has never been implemented by CPRS or other GUI applications.
XQAID:	(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 are not able to identify the alert in the future, either during alert processing, to delete the alert, or to perform other actions with the alert. REF: For information on CPRS conventions for the format of the Package Identifier, see the "Package Identifier versus Alert Identifier" section in the Kernel 8.0 & Kernel Toolkit 7.3 Developer's Guide.
XQAMSG:	(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 (^).
XQAOPT:	(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.
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.
XQASUPV:	(optional) Number of days to wait before Delete Old (>14d) Alerts option forwards alert to recipient's supervisor based on Service/Section, if alert is unprocessed by recipient. Can be a number from 1 to 30.
XQASURO:	(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.
XQATEXT:	(optional) As of Kernel Patch XU8.0207, this variable permits informational text of any length to be passed with an alert. When the alert is selected, the contents of this variable are displayed in a ScreenMan form within the roll and scroll environment. NOTE: It was also intended to be displayed within a text display box within the GUI environment. However, CPRS has never implemented this functionality, so it can only be viewed in the roll and scroll environment.

Output

none.

Details

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:
- XQADATA—If originally set when alert was created.
- XQAID—If originally set when alert was created.
- XQAKILL—The purge indicator; always set to 1 by the Alert Handler.
If you associated a software application identifier, XQAID, with the alert, it is restored along with two additional semicolon pieces:
- Current user number.
- Current date/time.
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 any option specified 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, the alert is deleted for the current user only.
- To prevent the alert from being deleted, KILL XQAKILL during Step 2. 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. When XQAKILL is set to 0, Alert Handler searches for any alerts with a matching Alert Identifier, all three semicolon pieces:
  - Original Package Identifier.
  - Alert sender.
  - Date/Time the alert was sent.
  It purges them so that other users need not be notified of an obsolete alert.
  
  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.

Example

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."
D SETUP^XQALERT
Q

Alerts: Resulting alert, from View Alerts option