Kernel APIs: SETUP^XQALERT

$$SETUP1^XQALERT: Send Alerts

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

This API sends alerts to users. This is the preferred call 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.

Format

  $$SETUP1^XQALERT

Input Variables

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

NEW all of the following variables.
Set the input variables you want changed.
Call the API.

If you do not follow these steps, the variables could unintentionally assume the values of the variables of the current running task.

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) 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, and then the entry (if any) in the pointed-to service/section's CHIEF field.
XQADATA:	(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.
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: Unfortunately, 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 don't 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 Programmer Manual.
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 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. To retain information forever, a value of 100000 is recommended (good for about 220 years).
XQASURO:	(optional) Number of days to wait before Delete Old (>14d) Alerts option forwards alert to recipient's MailMan surrogate(s) (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 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. However, CPRS has never implemented this functionality, so it can only be viewed in the roll & scroll environment.

Output

returns:

Returns:

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.

XQALERR:

It the al;ert 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.

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 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:
  - 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."
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:

VA (Internet) / VA (Intranet) / OI / HSD&D / Site Map / Terms of Use / VA Privacy Policy / Accessibility