Kernel APIs: SETUP^XQALERT

$$SETUP1^XQALERT: Send Alerts

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

Description

The $$SETUP1 extrinsic function sends alerts to users. This is the preferred API rather than SETUP^XQALERT API.

To send an information-only alert, make sure that the 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 non-namespaced variables.
Set the input variables you want changed.
Call the API.

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. 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.
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 variable 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: Currently, this functionality has not 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 vs. Alert Identifier" section in the Kernel 8.0 and 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.
XQAREVUE:	(optional) This variable is used to set the DAYS FOR BACKUP REVIEWER (#.15) field in the ALERTS (#8992) file. 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.
XQASUPV:	(optional) Supervisor forwarding. Number of days to wait before Delete Old (>14d) Alerts [XQALERT DELETE OLD] 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 (#200) file entry pointer to the SERVICE/SECTION (#49) file, and then the entry (if any) in the pointed-to service/section's CHIEF field.
XQASURO:	(optional) Number of days to wait before Delete Old (>14d) Alerts [XQALERT DELETE OLD] 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 is 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. Currently, CPRS has not implemented this functionality, so it can only be viewed in the roll-and-scroll environment.

Output

returns:

Returns:

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

XQALERR:

Returns:

NULL—If the alert was sent successfully, this variable is NULL.
Text String—If the alert was not sent successfully, this variable contains 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 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."
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: