Notifications

When employees are notified as part of a business rule action, the notification method is determined by the employee's notification preference.

The default notification methods are:

Dovetail Rulemanager adds support for two additional options:

SMS Notifications

An SMS notifications will send an SMS message to an employee's configured device, typically their mobile phone.

Twilio

Dovetail Rulemanager uses Twilio as an SMS provider.

You must have a Twilio account in order to use SMS notifications.

Pricing

As of this writing, Twilio charges $1.00 per month for a phone number, and $0.0075 per SMS message sent.

For 1000 messages/month, the total monthly cost would be $8.50 ($1.00 for the phone number, plus $7.50 for 1000 messages).

More information is available at https://www.twilio.com/sms/pricing

Twilio Setup
  1. Create a Twilio account
  2. Buy a phone number from Twilio
  3. Retrieve your Account SID and Auth Token from the Programmable SMS page within Twilio. This information will get used later.
  4. Configure SMS Responses


SMS Responses

If an employee responds to an SMS message, we can define the message that they get back.

By default, nothing within Clarify/Dovetail happens with any messages that they send back, so we want to inform them of this.

Example:

The following image shows an example of:

  1. an SMS message being sent to an employee
  2. the employee responding
  3. an auto-reply saying that responses are not accepted

    SMS with reply


Configuring the auto-reply

We'll do this by some simple configuration within Twilio.

  1. Create a new TwiML Bin

    • From the Developer Console, click on TwiML Bin, then the Plus icon to create a new one.
    • Set its friendly name to be SMS response - not accepted

    • Set the TWIML to be:

      <?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message>Sorry - responses are not accepted. Not yet, anyway</Message>
</Response>

    • Click the Create button to save it.

TwiML Bin

  1. Assign this response to your phone number

    • Twilio - All Products and Services - Phone Numbers
    • Click on the phone number you created.
    • Within the Messaging section:
    • Configure With --> WebHooks/TwiMl
    • A message comes in --> TwiMl - SMS response - not accepted
    • Click the Save button

Messaging


Rulemanager Configuration

Within the FChoice.RuleManager.WindowsService.exe.config file, configure Rulemanager with your Twilio information

<add key="Twilio.From" value="myTwilioPhoneNumberGoesHere" />
<add key="Twilio.AccountSid" value="myTwilioSidGoesHere" />
<add key="Twilio.AuthToken" value="myTwilioAuthTokenGoesHere" />

Example:

<add key="Twilio.From" value="512-123-4567" />
<add key="Twilio.AccountSid" value="ACdf864ac420dd4f87a533b4fe7d62d" />
<add key="Twilio.AuthToken" value="505416a718d0418dabd991cdd656da38" />

Rulemanager must be restarted after making changes to the FChoice.RuleManager.WindowsService.exe.config file.

Field for employee's SMS/Mobile number

By default, Rulemanager will use the employee's Pager number to send SMS messages.

By default, the label in the UI is "Pager", and this maps to the beeper field on the employee table (table_employee.beeper)

If you wish to use a different field on the employee table, you can do so by editing the Sms.EmployeeSmsField configuration setting within the FChoice.RuleManager.WindowsService.exe.config file.

Example:

<add key="Sms.EmployeeSmsField" value="x_cell_phone" />



Add SMS as a notification option


Dovetail Agent

To add SMS as a Notification option, simply edit the user-defined list named Notification Types, and add a new element titled SMS. Then refresh the application cache within Dovetail Agent.

Clarify Classic Client

To add SMS as a Notification option within the Clarify Client:

  1. Edit form 707 (Employee - 2 of 2).

    • Edit the Static List for the HIGH_PRI dropdown, adding a value of "SMS"
    • Edit the Static List for the MED_PRI dropdown, adding a value of "SMS"
    • Edit the Static List for the LOW_PRI dropdown, adding a value of "SMS"

  2. Edit form 721 (Preferences for).

    • Edit the Static List for the HIGH_PRI dropdown, adding a value of "SMS"
    • Edit the Static List for the MED_PRI dropdown, adding a value of "SMS"
    • Edit the Static List for the LOW_PRI dropdown, adding a value of "SMS"

  3. Compile ClearBasic code modules for the following forms:

    • Form 707
    • Form 721
    • Form 703

The ClearBasic code can be found at https://gist.github.com/gsherman/656a2c1e6aa48a5e06b98c1850ceb14f

If you already have existing CB code for these forms, merge the given code with your existing code.

Phone Number formats

When sending SMS messages, Twilio is very forgiving with the format of a phone number.

The following phone number formats have been tested and all work successfully:

More information is available at https://support.twilio.com

Business Rule - Pager message

When sending a SMS message as a result of a business rule, Rulemanager will use the "Pager Message" from the business rule action for the message body.

If the Pager Message field is empty, then the regular "Message" will be used.

Business Rule Action


Test

To test SMS Notifications:

  1. Configure Twilio as outlined above
  2. Configure Rulemanager as outlined above
  3. Create a test case, and take note of its id number.
  4. Log in as yourself, and set your notification preference to SMS for High urgency notifications, for both during and after business hours.
  5. Ensure that your Pager number on your profile is set to your actual mobile phone number
  6. Create a business rule:
Property Value
Object Type Case
Name Twilio SMS test rule
Rule Set Test
Start Event Log Note
Condition Object ID = {the id of the test case you just created}
Action title Notify with high urgency
Notify with high urgency Message
Start 0 minutes from Event Creation using Elapsed Time
Create Activity Log? True
Notify - To {Your login name}
To Urgency High
Message RE: notification for case [Object ID]
A note was logged to case [Object ID]
This is the regular message
Pager Message A note was logged to case [Object ID]
This is the pager message
  1. Back on the case, log a note.
  2. The History / Activity Log should show that the business rule fired
  3. You should receive an SMS message.
  4. If you did not, review the $rulemanager/logs/RuleManager.log file for any errors.

Slack Notifications

When a user chooses to receive Slack Notifications, RuleManager will send the notification as a direct message to the employee's Slack channel.

Slack Application Setup

RuleManager uses Slack's API to send notifications. It is the basis for all Slack clients, and RuleManager uses a bot user integration to send notifications to your workspace.

  1. Start by creating a Slack app for your workspace. You can use the Create New App button to get started. You just need to provide an App Name and select the Development Slack Workspace to get started.

  2. Once the App is created, open the App from the listing of Your Apps, and head to the Basic Information page. Click on Add features and functionality, and then on Bots. Fill in the Display name and Default username, then save the changes.

  3. Retrieve the Bot User OAuth Access Token from the OAuth & Permissions page. This is the value needed for RuleManager to authenticate and send messages.

  4. Navigate to Slack API Apps to learn more about configuring and customizing your Slack App.


Rulemanager Configuration
Slack Authentication Token

Within the FChoice.RuleManager.WindowsService.exe.config file, configure Rulemanager with your Slack Access Token

<add key="Slack.AuthToken" value="BotAuthTokenGoesHere" />
Field for employee's Slack Member ID

Within the FChoice.RuleManager.WindowsService.exe.config file, configure Rulemanager with the field where an employee's Slack Member ID is stored. This will be a field on table_user. By default, Rulemanager will use the x_slack_member_id field on table_user. If you wish to use a different field, edit the Slack.MemberField setting.

<add key="Slack.MemberField" value="x_slack_member_id" />
Access Slack Via a Proxy

Within the FChoice.RuleManager.WindowsService.exe.config file, configure Rulemanager with your Slack proxy URL

<add key="Slack.BaseURL" value="ProxyURLGoesHere" />

Note: Rulemanager must be restarted after making changes to the FChoice.RuleManager.WindowsService.exe.config file.

Add Slack as a notification option

Dovetail Agent

To add Slack as a Notification option, simply edit the user-defined list named Notification Types, and add a new element titled Slack. Then refresh the application cache within Dovetail Agent.

Clarify Classic Client

To add Slack as a Notification option within the Clarify Client:

  1. Edit form 707 (Employee - 2 of 2).

    • Edit the Static List for the HIGH_PRI dropdown, adding a value of "Slack"
    • Edit the Static List for the MED_PRI dropdown, adding a value of "Slack"
    • Edit the Static List for the LOW_PRI dropdown, adding a value of "Slack"

  2. Edit form 721 (Preferences for).

    • Edit the Static List for the HIGH_PRI dropdown, adding a value of "Slack"
    • Edit the Static List for the MED_PRI dropdown, adding a value of "Slack"
    • Edit the Static List for the LOW_PRI dropdown, adding a value of "Slack"

  3. Compile ClearBasic code modules for the following forms:

  4. Using UI Editor, add a new textbox to Form 703 (Employee), mapped to the x_slack_member_id field on the login contextual object. (The login contextual object is the user record for the employee)

Slack Member ID

Rulemanager uses the user's Slack Member ID (typically stored in table_user.x_slack_member_id) to message a user within Slack.

Note: Slack Member ID is not the same as Slack Username! See this Slack post for more information

To retrieve a user's Slack Member ID
For an individual user:
For all users: