In general, Device Engines used to deliver notifications do not require a high level of customization. An exception to this is the Phone Device Engine. The Phone Device Engine requires a high level of customization for initially contacting Users, and for processing requests from Users dialing into the system.
To provide this customization in xMatters, Phone Device Engines are able to execute scripts for sending outbound notifications (Callout) and receiving inbound calls (Callin). Once the conversation has been established with a User, a domain-specific script is called for each notification to present it to the User. The following figure illustrates this event flow:
The inputs into a callout script are:
The following implicit variables are available in the callout script:
All Phone Device Engines reference the Callout script package. Each deployment can contain only one Callout script package. Within the Callout script package, there will be one callout script that is used to initiate contact with Users.
Example: Callout and Play Notifications
This example calls a User and plays all of their pending notifications:
1 main:
2 @recipient = @interaction::getRecipient($targetName)
3 @phone::setLanguage($recipient.country, $recipient.language)
4 $phone_number = @phone::formatDialstring()
5 $result = @phone::makecall($phone_number)
6 IF ( $result == "VOICE_DETECT" )
7 @phone::play("phrase", "call-out greeting")
8 @phone::play("name", $targetName)
9 @session = @interaction::authenticatePhoneLogin($recipient.phoneLogin, $recipient.phonePassword)
10 $notificationIds = @session::getNotifications()
11 FOR ($notId : $notificationIds )
12 @content = @session::getNotificationContent($notId)
13 gosub presentNotification
14 ENDFOR
15 @phone::play("phrase", "goodbye")
16 @phone::hangup()
17 ENDIF
2. Based on the $targetName, retrieves the recipient object. The recipient object is used to provide context on the recipient.
3. Configures the phone script object based upon the recipient’s country and language.
4. Retrieves the phone number to call.
5. Initiates the phone call.
6. Checks to see if we have reached a person. If we have not, then exits.
7-8. Plays a greeting to the User.
9. Establishes a session for the User using the their phone login and password.
10. Retrieves the notification ids for the user.
11-14. Iterates through each notification retrieving the notification content and presenting the notification to the User.
15-16. Plays goodbye message to the User and hangs up.
This subroutine plays a notification to the User using the specified domain-specific interaction script:
1 presentNotification:
2 @interaction::runInteractionScript($notId, $interactionScript, @script, @session, @content, @recipient, @phone)
3 return
1. Subroutine label.
2. Runs the interaction script that has been enhanced for the notification. This script presents the notification to the user.
Next topic: Interaction with Notification Recipient