Response Object

The @response object is created within the handler script to allow a script author to access the details of the response.

Creation Method: System-provided object

Reference Name: Access this object using @response.

Scope: Script lifecycle; exists only within the handler script execution.

Note that not all of the following variables are populated for every notification; for more information, see Response object variables and notification hierarchy.

Reserved object variables

Name

Description

$response.REPLY

Recipient's reply to the notification; this value may be a text string, such as "Acknowledge", or a numerical value. For example, a User on a Voice Device may respond to a notification by pressing a number button on their phone; xMatters would translate the DTMF tone into the numerical value of the button.

$response.queryclaim

Claimcheck used to check for responses from two-way Devices (pagers in particular); for example, the following XML code illustrates a claimcheck for a WCTP Device:

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE wctp-Operation SYSTEM "http://wctp.myairmail.com:80/wctp/wctp-dtd-v1r1.dtd"> 
<wctp-Operation wctpVersion="wctp-dtd-v1r1.dtd" wctpToken="x224"> 
<wctp-SubmitClientResponse> 
  <wctp-ClientSuccess successText="Message Accepted" successCode="200" 
    trackingNumber="1784193744"/> 
</wctp-SubmitClientResponse> 
</wctp-Operation>
 

$response.DEVICE_TARGET

Target name of the Device used to respond to the notification.

$response.DEVICE_ID

Database ID of the Device used to respond to the notification.

$response.DEVICE_NOTIFICATION_ID

Notification ID for the Device used to respond to the notification.

$response.PERSON_TARGET

Target name of the User who responded to the notification.

$response.PERSON_ID

Database ID of the User who responded to the notification.

$response.PERSON_NOTIFICATION_ID

Notification ID for the User who responded to the notification.

$response.TEAM_TARGET

Target name of the Team to which the responding User belongs.

$response.TEAM_ID

Database ID of the Team to which the responding User belongs.

$response.TEAM_NOTIFICATION_ID

Notification ID for the Team to which the responding User belongs.

$response.GROUP_TARGET

Target name of the Group to which the responding User belongs.

This value is not populated if the User is not a member of a Group, unless the User is a Group Supervisor.

$response.GROUP_ID

Database ID of the Group to which the responding User belongs.

$response.GROUP_NOTIFICATION_ID

Notification ID for the Group to which the responding User belongs.

$response.RECIPIENT_TARGET

Target name of the recipient that responded to the notification.

$response.RECIPIENT_ID

Database ID of the recipient that replied to the notification.

$response.RECIPIENT_NOTIFICATION_ID

Notification ID for the recipient that replied to the notification.

$response.RESPONSE_EVENT

The delivery event status that triggers the handler script.

Note that not all of the possible values are supported by all protocols or service providers. Furthermore, some service providers do not return all of the responses that their protocol supports.

Note: To configure the notification to run the response script when the delivery of a notification is successful, set the notification to handle delivery events:

@notification::setHandleDeliveryEvents(true)

 

Possible values for this variable that will execute the handler script are:

  • DEVICE_DELIVERED: The service provider has responded that the notification was delivered to the Device. (This value is unlikely as it is supported by a limited number of protocols and providers.)
  • DEVICE_ATTEMPT_FAILURE: An internal error or connectivity problem prevented the notification from reaching the service provider. The notification will be retried for the number of times and after the set timeout configured for the Protocol Provider.
  • DELIVERY_FAILURE: The notification could not be delivered; xMatters will not attempt to deliver the notification again.
  • SUCCESSFUL_DELIVERY: xMatters has successfully delivered the notification to the service provider.
  • RECEIVED_RESPONSE: The notification was delivered, and a response has been received from the Device.

$response.MESSAGE

By default, this is the message that was sent out to the Device. In some cases, this can be overridden by the User to some other value; for example, some integrations use the $response.message variable to provide additional annotation messages that can be added to the originating event on the management system.

$response.DEVICECLASSIFICATION

The type of Device on which the User replied; possible values for this variable are:

  • EMAIL
  • VOICE
  • TEXT_PHONE
  • TEXT_PAGER
  • NUMERIC_PAGER
  • VIRTUAL
  • BES
  • IM
  • BROWSER
  • GENERIC

$response.failure_type

This variable is set only in the callout scripts for Phone Devices. At all other times, it is null. For an explanation and example of how this variable is used, see @session::reportFailure.

$response.error_msg

The error message returned by the User Service Provider when attempting to contact a Device; the following example illustrates the contents of a $response.error_msg variable when the service provider could not connect to the SMTP host:

<message>Cannot connect SMTP server [IP: <IP_ADDRESS>]. Service provider name BAD SMTP, 
  Exception: Could not connect to SMTP host: <IP_ADDRESS>, port: 25;
    nested exception is:
      java.net.ConnectException: Connection refused: connect</message>
 

Response object variables and notification hierarchy

Due to the way xMatters structures notifications, not all of the variables in the above table are populated for every notification. The following examples provide an overview of how and when these variables will contain values.

Example One

A notification that targets a Group is delivered to a User's Text Phone and the User responds on the same Device. In this case, the scripts would populate the following variables:

Example Two

A notification that targets a User directly is sent to the User's Voice Phone; the User responds using the xMatters Web User Interface. The scripts populate the following variables:

Example Three

A notification that targets a Group is delivered to a User's Email Device. Before the User responds, the Group Supervisor responds using the xMatters web user interface. The scripts populate the following variables:

System Tokens

Inbound reserved names

Device Engine Content