Dovetail RuleManager Documentation

Introduction

Welcome to the RuleManager Documentation. RuleManager is Dovetail Software's application event processing engine, based on Microsoft™'s .NET framework.

RuleManager is an important part of the Dovetail system. It is a Windows service that monitors the Dovetail database for application events, and processes these events. The type of processing that occurs depends on the type of event.

Processing includes:

• Evaluation and firing of business rules
• Commitment warning and expiration notifications
• Sending outgoing email

In general, RuleManager is meant to be a drop-in replacement for the Amdocs Rulemanager product. For more information, see the Comparison to Amdocs Rulemanager section.

Getting Help

If you need additional help beyond this user guide, you can use any of the following resources:

• Dovetail SelfService - Use our online customer support site to notify us of a support issue, to manage your Dovetail products, to seek sales support, or to search the knowledge base.
• Knowledge Base Articles - Search our online knowledge base for existing issue resolutions.
• Product Documentation - Find Dovetail's most up-to-date product documentation.
• Contact Us - Contact us directly if you need further assistance.
  • support@dovetailsoftware.com
  • phone 800-684-2055 or 512-610-5400

What's New - Version 3.2.3

Enhancements

• New connection string parameters: Integrated Security=SSPI; and Persist Security Info=True; can be used to log into the database using current Windows login credentials.
  Important: Before Integrated Security can be used a server set up procedure must be followed, see Integrated Security with Dovetail server applications for details.
• New DovetailDatabaseSettings.ApplicationUsername setting is available to specify a valid Clarify username used by the application.
• MSGraph Email Service has been enhanced to better handle throttling scenarios:
  • Added new MsGraphExecutor settings and expanded the methods of control of the retry process in response to a series transient exceptions.

Bug Fixes

• None

Upgrading to Version 3.2.3

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
6. Start the Rulemanager service

What's New in Previous Versions

Previous Versions

Version 3.2.2

Enhancements

• MSGraph Email Service has been enhanced to handle throttling scenarios:

  • Added transient exception detection functionality with exponential delay methodology for retries.
  • Added new MsGraphExecutor settings to control the retry process in response to a transient exception.
  • Improved the logging for all MSGraph Email actions taken, and their results.

• Slack configuration:

  • Added Slack.BaseURL setting to allow for using a proxy.

Bug Fixes

• Correctly resolve a rule property into a valid email address if it's wrapped within angle brackets or double quotes.
• Fixed a problem when a Consumer thread would stop before sending an email; all other processing also stops. A new configuration parameter EmailServiceConfig.ParseMarkdownTimeoutMilliseconds has been added to control for how long at the maximum the markup parser should run before timing out.

Version 3.2.1

Enhancements

• None

Bug Fixes

• An exception could happen when a string containing a single apostrophe character is used in "is in" or "is not in" business rule condition.

Version 3.2.0

Enhancements

• Added support for Oracle database version 19c.

Bug Fixes

• None

Upgrading to Version 3.2.0

• follow the same steps as described for version 3.1.0

Version 3.1.0

Enhancements

• None

Bug Fixes

• Sending email using MsGraph fails with file attachments > 3 MB
• If sending email using MsGraph fails, it could potentially continue to retry forever
• SQL exception when Rulemanager tries to create Notifier messages for many (more than 300) users at one time

Additional Information

• If using MsGraph to send email, the MsGraph API has some built-in throttling to be aware of, which will influence how you should configure the number of worker threads. Refer to the Dovetail knowledgebase article on Throttling of the MsGraph API with Carrier and Rulemanager for more information.

Upgrading to Version 3.1.0

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
   • Note: the assemblyBindings have changed within the FChoice.RuleManager.WindowsService.exe.config file.
6. If you wish to use the Ms Graph API to send email, configure Rulemanager to do so. Refer to the Microsoft Graph API settings for specific details.
7. Start the Rulemanager service

Version 3.0.0

Enhancements

• In addition to SMTP, Rulemanager can now send email using an Azure application and the Microsoft Graph API. Refer to the Microsoft Graph API settings to understand the settings relevant to configuring Rulemanager to send email using the Microsoft Graph API.

Bug Fixes

• None

Upgrading to Version 3.0.0

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
   • Note: the assemblyBindings have changed within the FChoice.RuleManager.WindowsService.exe.config file.
6. If you wish to use the Ms Graph API to send email, configure Rulemanager to do so. Refer to the Microsoft Graph API settings for specific details.
7. Start the Rulemanager service

Version 2.8.1

Enhancements

• None

Bug Fixes

• An exception could happen when communicating with the SMTP server if EmailServiceConfig.EnableSsl was set to false. This issue was first introduced in version 2.8.0.

Upgrading to Version 2.8.1

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
6. If you wish to connect to the SMTP server using TLS or SSL, review (and edit if needed) the following config settings, and be sure they're correct for your environment: EmailServiceConfig.EnableSsl, EmailServiceConfig.SmtpSslMode, and EmailServiceConfig.Port
7. Start the Rulemanager service

Version 2.8.0

Enhancements

• Updated Rulemanager to support SSL and TLS 1.2 when communicating with the SMTP server. This requires the new EmailServiceConfig.SmtpSslMode setting to be set within the FChoice.RuleManager.WindowsService.exe.config file. For more information, refer to the Dovetail knowledgebase article on Rulemanager and TLS / SSL

Bug Fixes

• None

Requirement Changes

• Requires Microsoft .NET version 4.7.2 (or higher).

Upgrading to Version 2.8.0

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
6. If you wish to connect to the SMTP server using TLS or SSL, review (and edit if needed) the following config settings, and be sure they're correct for your environment: EmailServiceConfig.EnableSsl, EmailServiceConfig.SmtpSslMode, and EmailServiceConfig.Port
7. Start the Rulemanager service

Version 2.7.2

Enhancements

• None

Bug Fixes

• Resolved an issue where business rules would fail to process if both table_user and table_employee contained an identically named custom column starting with x_

Upgrading

To upgrade to Version 2.7.2:

1. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
2. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
3. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
4. Install the new version of Rulemanager
5. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
6. Start the Rulemanager service

Version 2.7.1

Enhancements

• None

Bug Fixes

• Slack Notifications are using the pager messages (of a business rule) instead of normal action messages.

Upgrading

To upgrade to Version 2.7.1:

1. Apply Schema Changes.
   • The schema changes to be applied are defined in $rulemanager\config\schema\rulemanager.schemascript.xml. The easiest way is to simply apply these changes using Dovetail SchemaEditor and the rulemanager.schemascript.xml file - it will add the new schema and skip over any changes that already exist.
2. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
3. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
4. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
5. Install the new version of Rulemanager
6. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
7. If you plan to use Slack Notifications, follow the instructions for configuring Slack Notifications
8. Start the Rulemanager service

Version 2.7.0

Enhancements

• Add support for Slack Notifications. Dovetail Rulemanager can send User notifications via Slack (https://slack.com/). You must have a Slack account in order to use Slack notifications.

Upgrading

To upgrade to the version 2.7.0:

1. Apply Schema Changes.
   • The schema changes to be applied are defined in $rulemanager\config\schema\rulemanager.schemascript.xml. The easiest way is to simply apply these changes using Dovetail SchemaEditor and the rulemanager.schemascript.xml file - it will add the new schema and skip over any changes that already exist.
2. Stop the Dovetail Rulemanager Windows service. Be sure to close the Windows Services application window after doing so.
3. Backup any Rulemanager files that you have previously modified (such as FChoice.RuleManager.WindowsService.exe.config, other .config files, or custom property extension DLLs)
4. Un-install the old version of Rulemanager (using Control Panel - Add/Remove Programs).
5. Install the new version of Rulemanager
6. Merge any of your existing changes with updated files, then copy the merged files back into the Rulemanager directory. This includes any changes to FChoice.RuleManager.WindowsService.exe.config.
7. If you plan to use Slack Notifications, follow the instructions for configuring Slack Notifications
8. Start the Rulemanager service

Version 2.6.0

Enhancements

• Business Rule Conditions can now be processed in a defined order. It is now possible to add some ordering capabilities to conditions via Dovetail Agent version 20 or later. This helps administrators define which conditions to evaluate first and can help with performance/load. Conditions that are based on custom function properties can sometimes cause higher server load, so it is beneficial to evaluate those conditions later in the sequence. If other simpler conditions are not met, the following custom function conditions wouldn’t be evaluated.
• Consumer Action logging has been enhanced to include the focus object related to the event.
• The Rulemanager Installer now installs the application for all users. This allows the Rulemanager application to show up in the Control Panel for all users instead of just one.

Bug Fixes

• When a business rule has been set to inactive, and then a time bomb for that rule gets executed, a NullReferenceException was being thrown since the rule was not being loaded. Now the execution is logged and avoided, and the time bomb gets rescheduled to 12-31-2999.

Version 2.5.0

Enhancements

• Add support for "is not in" operator in business rule conditions.

Version 2.4.3

Bug Fixes

• A Rulemanager consumer thread could hang due to a regular expression (regex) timeout due to a bad IsIn rule condition. Regular expression evaluation now has a configurable timeout to avoid rare occurrences where complex regular expressions fail to evaluate in a timely manner.

Version 2.4.2

Bug Fixes

• When a commitment escalation email was sent, Rulemanager could incorrectly update the x_subject and sender of an email_log record whose objid matched that of the commit_log objid.

Version 2.4.1

Enhancements

• Dovetail SDK updated. This version of the SDK is now more forgiving of "bad" data, including unexpected NULLs and invalid or duplicate state_prov records. There is also additional debug-level logging at application startup, for better troubleshooting.

Version 2.4.0

Enhancements

• Add support for SMS Notifications. Dovetail Rulemanager uses Twilio (https://www.twilio.com) as an SMS provider. You must have a Twilio account in order to use SMS notifications.

Version 2.3.0

Enhancements

• Add support for Configuration Item Rule Properties, which allow Configuration Items to be evaluated like rule properties.
• Dovetail SDK updated. The notable change here is that the SDK will now ignore duplicate states with the same name or full_name within the same country. Previously this would cause a fatal error. Now, the duplicate state will be ignored, and a warning will be logged.

Bug Fixes

*[Accept Date-Time] and [Dispatch Date-Time] rule properties are not expanded.

Requirement Changes

• Requires Microsoft .NET version 4.5.x.

Version 2.2.1

Bug Fixes

• Rule properties used in business rule conditions were being truncated to their max length, as defined in the rule property definition. This could cause some rule conditions to be evaluated improperly. This was a result of property rule changes made in version 2.2.0. Now, the max length value of rule properties are ignored when the rule property is used as part of a business rule condition. The max length value is honored when the rule property is part of a business rule action message.

Version 2.2.0

Enhancements

• Add support for Custom Function-based Rule Properties
• Business Hour calculations now support holidays

Version 2.1.0

Bug Fixes

• Error in certain situations when performing business hour calculations. (System.NullReferenceException)
• Error trying to parse markdown when sending an email notification with certain text (Microsoft.ClearScript.ScriptEngineException: TypeError: Cannot read property 'type' of undefined)
• Out of license errors when processing many markdown enabled messages and/or performing business hour calculations (FChoice.Common.FCLicenseException: (5308) Could not obtain license productId 1 as all user and grace license limits are full or there is no license present for this product.)

Version 2.0.0

Enhancements

• Rulemanager now supports a business rule action type of Carrier Message, which will send a message to Dovetail Carrier.This is primarily used as part of Dovetail Task Manager. Requires the Carrier.QueueAddress setting. Requires Dovetail Carrier version 2 or higher.

Version 1.7.0

Enhancements

• When sending an email with an inline image from the ResourceStore (S3 or Seeker), and that image can not be retrieved, then a default image (shown below) will be displayed instead. Previously, an exception would be thrown, the time_bomb's escalate_time would be set to 1/1/2999, and the email would not be sent.

This default image will be used when an inline image cannot be retrieved:

Version 1.6.0

Enhancements

• Emails that contain a link to an image stored in Dovetail Seeker (such as those sent from Dovetail Agent version 9 and later) will show the image as an inline image. This requires the ResourceStore setting to be set within the FChoice.RuleManager.WindowsService.exe.config file. More information is available in the HTML Emails section. Requires Dovetail Seeker 2.4 or higher.

Version 1.5.1

Enhancements

• Outgoing emails can now be sent as HTML. This includes Log Emails and business rule notification emails. This functionality is controlled with the EmailServiceConfig.ParseMarkdown configuration setting. When true, RuleManager will convert any markdown present within outgoing emails to HTML.
• Emails that contain a link to an image stored in Amazon S3 (such as those sent from Dovetail Agent version 8 and later) will show the image as an inline image. This requires the S3 settings to be set within the FChoice.RuleManager.WindowsService.exe.config file. More information is available in the HTML Emails section.

Bug Fixes

• Fixed a property evaluation issue. Any Integer property that overflows the Int32 boundary is now evaluated as a string property.
• Fixed a property evaluation issue. Properties that used the focus_obj2act_entry relation for non-rule time bombs would not always resolve properly. This was due to the table_time_bomb.time_period value being zero. For rule time bombs, the time_period column holds the objid of the act_entry. For non-rule time bombs, this value would be zero. Rulemanager was add a constraint of table_act_entry.objid = table_time_bomb.time_period when evaluating the rule. If time_period was zero, then no activity entry would be found, and the property would not resolve. Now, that constraint is not included if the time_period is equal to zero.

Installer

• There are now two different RuleManager installers - 64 and 32 bit. Use the one that matches the bit-ness of the machine where RuleManager is being installed.

Dependencies

• Dovetail SDK updated to 3.3.7.4

Version 1.4.4

When RuleManager sends a log email, it will now update the email_log record. The information is pulled from the outgoing email, and will update the sender (email_log.sender) and subject (email_log.x_subject, if that field exists).

Added EmailServiceConfig.DefaultFromEmailAddressDisplayName configuration setting. This setting allows the display name to be set for email notifications.

Removed LicenseInstaller.exe from the installation package. All license installation should be performed with the LicenseInstaller that ships with Dovetail SDK.

Version 1.4.3

IsIn Condition Evaluation Update

Fixed a bug for the IsIn Condition where parenthesis in the list values would cause the values to not be recognized correctly.

Version 1.4.2

IsIn Condition Evaluation Update

Fixed a bug for the IsIn Condition where spaces between the list values would cause the values to not be recognized correctly.

Dovetail SDK updated to 3.3.3.

Version 1.4.1

Property Evaluation Enhancements and Fixes

• Rule Properties which resolve to the contact table will now use the property's resolved field value as a source of email addresses in addition to the contact's email address field.
• Fixed a bug for Rule Properties which resolve to an employee. When the employee had no email address, an exception would be thrown when building the email message. Now it will log a warning and use the default RuleManager email address to send the email.

Version 1.4.0

Important: This release of RuleManager requires Microsoft .Net 4.0 Full edition.

Dovetail SDK updated to 3.2.3.

RuleManager can now sign outgoing emails when an digital certificate is present. This feature can be enabled via configuration.

Property expansion: added support for rule properties that use the focus_obj2act_entry relation which traverses from the focus object to act_entry when those two tables are related via the fact-participant model.

Version 1.3.0

RuleManager will now support sending email notifications to contact and employees who have multiple email addresses in their email fields. For example if a contact has "contact@domain.com, alternate@homemail.com" their email field they will receive mail at both addresses. These email addresses can be delimited by comma, semi colon and white space.

Version 1.2.6

The name of the RuleManager windows service is now "DovetailRuleManager" (was RuleManager). This change has been made across all our products with Windows services for consistency. Please be aware that this change may affect service monitors or automation scripts.

Fixed bug where activity entries being created by scheduled application events were not being enlisted into the current database transaction.

Version 1.2.5

Fixed bug related to property evaluation

• Integer properties that overflow the Int32 boundary are now evaluated as string properties.

Version 1.2.4

Fixed two bugs related to the intrinsic property "Current Queue Memberships"

• Corrected typo in the relation path for the object type bug.
• Expansion of this property for objects who are not in a queue will now result in no queue members being returned.

Version 1.2.3

Dovetail SDK updated to version 2.4.6

Version 1.2.2

• Added support for Dialogue and Communication objects
• Added support for creating fact-participant activity logs
• Dovetail SDK has been updated since it was upgraded to support Dialogue and Communication objects

Version 1.2.1

• RuleManager now updates the arrival time on a new message created for a notification.
• Rules applying to solutions using the old term "Problem Description" were not being fired correctly.

Version 1.2

In this release we focused on adding support for Amdocs 6 thru Amdocs 7.5.

No changes to the rule processing were required, but Dovetail SDK has been updated since it was upgraded to support the new database enhancements.

Version 1.1.9

Fixed a regression introduced in 1.1.8 that caused the RuleManager service to stop when sending email to an invalid address. This situation will cause the application event's escalation time to be forwarded to the far future.

Version 1.1.8

When evaluating rule conditions where the operands cannot be coerced to the specified operand type. The condition's operands will be treated as type string.

Added ApplicationEventExecutor.StopApplicationIfEmailServiceIsDown configuration setting. This setting allows you to avoid stopping RuleManager if the Email Server goes down.

Version 1.1.7

Added EmailServiceConfig.Timeout configuration setting to the allow control of the number of seconds until sending an email will timeout.

Version 1.1.6

Added more verbose logging when failing to send an email.

Version 1.1.5

This release makes Dovetail RuleManager compatible with Amdocs Rulemanager's expansion of the [Current Queue Members] property. The [Current Queue Members] property now excludes the queue supervisors from the list of queue members.

Version 1.1.4

Sending emails with attachments that exceed the server message size limit will now be sent without attachments. An error log will be generated when this situation occurs. The email message body will be prepended with this message:

Attachments in this email have been removed due to the message size limit of the senders email server.

Version 1.1.2

Fixed a bug when executing a command line process whose argument values contain newline characters.

For example, sending a page (using the NotificationConfig.PagerApplicationPath) when the message to be sent contains newlines would cause an error such as Cannot start process because a file name has not been provided. This has been fixed.

Version 1.1.1

Fixed an issue where RuleManager was not processing business rules on objects that were not defined in a built-in list of standard objects. For example, business rules would properly fire for "case", "contact", etc. However, if a business rule was created on a "modem" object or on a "x_my_custom_table" object, then these rules would never fire. This has been fixed.

Version 1.1

• RuleManager can now include attachments for emails initiated via a LogEmail action, which is typically made from within Dovetail Agent or the Clarify Client. For more information, see the Email Attachments section.
• The working directory of RuleManager is now the directory where RuleManager is installed. This is relevant when having business rules that execute command line processes. As of this version, command line processes will be executed from the RuleManager directory, which by default is "C:\Program Files\Dovetail Software\Rule Manager". Previous versions used the c:\windows\system32\ directory as its working directory.
• As of this version, saving Dovetail SDK cache information to files has been disabled. This will cause a slight increase in startup time, but will reduce common cache-related issues and tasks (such as having to find and delete cache files). Note that this common cache information is still cached in memory for optimum performance.

  Note: The configuration file (FChoice.RuleManager.WindowsService.exe.config)
  changed in this release. Specifically, a new spring context element
  (EmailLogDataAccess.config) was added. You must use this new config file 
  when upgrading, and edit it for your environment.

Version 1.0.4

Fixed database verification to ensure proper version of MSSQL database is being used.

Version 1.0.3

Fixed issue when sending an email to a local invalid mailbox. This could cause many duplicate emails to be sent to the valid recipients, and could also cause the RuleManager service to shut down.

Version 1.0.2

Fixed issue with the "CC List1" Intrinsic property. It was missing from the list of known properties, which could result in a warning such as: No property "CC List1" was found in intrinsic XML properties

Version 1.0.1

Fixed an issue with the condition operator expecting the left operand property to always expand into whichever type the right operand was.

Version 1.0

Initial Release

Installation

Before You Begin

Requirements

The section describes the minimum and recommended system requirements for both the computer RuleManager is on as well as the database server software and platform:

Packaging

RuleManager is shipped as a ZIP file containing the MSI installation package.

Installing RuleManager

Using the MSI Installation Package

Begin the installation by extracting the contents of the RuleManager ZIP file into a temporary folder. Run the MSI installation process by double-clicking on the RuleManager.msi file.

The installation will then proceed through a series of steps or screens which will either provide information about the installation process, or request information necessary to install RuleManager.

Update the Clarify Schema

You can update the Clarify schema with Dovetail SchemaEditor.

Prior to making schema changes, backup the current database.

To make these changes using Dovetail SchemaEditor:

1. Edit the .SchemaEditor file
   • Set the database connection information.
   • Set the inputFilePath to [InstallDir]\config\schema\rulemanager.schemascript.xml
2. Preview the changes (SchemaEditor.exe -p).
3. Apply the changes (SchemaEditor.exe -a).

License Installation

You should have received a license for RuleManager either with your distribution or separately. If you have not received a license for RuleManager, please contact us to obtain one.

To install your RuleManager license

1. Execute the Dovetail Software License Installer which is found in the Dovetail SDK installation root.

2. The database connection/login screen will appear (Figure 2). This allows License Installer to connect to your Clarify™ database instance and view current and install new Dovetail Software licenses. Please enter required information (all fields are required except for "DB Name" when the database type is "Oracle") and click "Login". The License Installer will then attempt to connect to the database.
   
   Figure 2: License Installer Login Screen

3. After successfully connecting to the database and retrieving any existing license information, the license information screen (Figure 3) will be displayed. This will list any existing licenses and some basic information about them. It also allows you to install new licenses by clicking on the "Install New License(s)" button.
   
   Figure 3: License Installer License Information Screen

4. To install a new license or licenses, click the "Install New License(s)" button. You will be prompted (see Figure 4) to select an XML license file, or paste a license XML fragment you may have received in an email or other source. Once you have loaded or pasted the XML fragment, click the "Install" button to install the license.
   
   Figure 4: License Installer Load License Screen

5. If the installation is successful, the license information screen will appear. The newly installed license(s) should appear in the list of installed license. At this point the License Installer can be closed, or new licenses can be installed as many times as is needed. If the installation is not successful, an error dialog window will appear giving further details about what went wrong.

Security Considerations

For Windows 2000, Windows XP, and Windows 2003, there are special security considerations to think about before starting the RuleManager service.

The RuleManager installer defaults the RuleManager service to run under the predefined local account named "LocalSystem". This account has extensive privileges on the local computer. Most services do not need such a high privilege level and due to the risk posed, it is advised not to run other services as this account. It is recommended that you change the account that the RuleManager service runs as.

This account should have the following privileges:

• Read and execute access to the RuleManager install directory (typically C:\Program Files\Dovetail Software\RuleManager)
• If logging, read/write write permissions to the folder where the log files will be created.
• Any other permissions to folders or files used by the software (such as Read/Execute access to the .NET Framework Runtime DLLs, or, for Oracle, the Oracle client bin folder)
• Standard permissions to run as a service and access the .NET Framework - the list of these permissions is beyond the scope of this document. Please consult the Microsoft knowledge base for specific information.
  
  

[Optional] Setup SMS Notifications

If you plan to use SMS Notifications, follow the instructions for configuring SMS Notifications

[Optional] Setup Slack Notifications

If you plan to use Slack Notifications, follow the instructions for configuring Slack Notifications

Starting the Service

By default, after the service is installed, it is not started. In order for RuleManager to begin processing, the service must be started.

1. Open Control Panel, Administrative Tools, and open the 'Services' applet.
2. Find the RuleManager service in the list (or whatever name you gave your service during installation).
3. Click the "Play" or "Start" button in the toolbar. RuleManager should start after a few seconds.

   Note: If RuleManager fails to start, you will be prompted with a generic
   error message from Windows. Consult the Windows Event Viewer to get more
   information about why RuleManager failed to start. To run the Event
   Viewer, open the "Event Viewer" applet in the same folder where the "Services"
   applet was.

Configuring RuleManager

Once the installation is complete, edit the configuration file for RuleManager.

RuleManager uses the .NET Application Configuration mechanism to read load-time configurable settings. Configuration parameters for RuleManager are specified in the FChoice.RuleManager.WindowsService.exe.config found in the RuleManager install directory (typically C:\Program Files\Dovetail Software\RuleManager).

There are several sections of the configuration file, described in this section:

• appSettings - Used to configure the Dovetail SDK parameters, including the database connection
• fchoice - RuleManager specific configuration settings
• log4net - Used to configure the log settings
• configSections - Do not change anything in this section

appSettings Section

fchoice Section

Dovetail SDK specific configuration settings; For additional details on Dovetail SDK configuration options, refer to the Dovetail SDK documentation.

RuleManager specific configuration settings:

Email settings

These settings define how Rulemanager sends outgoing emails.

SMTP Email settings

Rulemanager can send email using SMTP or using the Microsoft Graph API. If using SMTP, these settings apply.

MsGraph Email settings

Rulemanager can send email using SMTP or using the Microsoft Graph API. If using MsGraph and an Azure application, these settings apply. More information is available in the MS Graph Account Configuration section.

MsGraph Retries - Additional Information
When sending emails with MsGraph APIs, the API may rate-limit requests, which can result in a transient exception. A transient exception is a temporary error that may later succeed by retrying the operation. Examples of transient exceptions and their response codes:

• 429, too many requests
• 503, service unavailable
• 509, bandwidth limit exceeded

When a transient exception is detected, Rule Manager will retry the operation up to a maximum of MsGraphExecutor.NumberOfRetries times. After all retry attempts in response to MsGraph transient exceptions are exhausted the timebomb associated with the send email operation will be rescheduled by MsGraphExecutor.RescheduleDelaySeconds. This allows to repeat the whole send email operation. The idea is to repeat it in not too distant future, e.g. in 2 minutes time.
In case of persistent MsGraph transient exceptions being encountered the timebomb associated with the send email operation will be rescheduled up to MsGraphExecutor.NumberOfReschedules times. If still unable to send email due to MsGraph transient exceptions the timebomb will be rescheduled to the maximum future date.
All MsGraph non-transient exceptions are subject to the same handling as non-MsGraph ones which fall under the VolatileResourceExecutor rules.

For even more details, refer to the Dovetail knowledgebase article Throttling of the MsGraph API with Carrier and Rulemanager.

SMS settings

These settings apply when using SMS notifications. More information is available in the SMS Notifications section.

Slack settings

These settings apply when using Slack notifications. More information is available in the Slack Notifications section.

Amazon S3 settings

These settings apply when HTML emails contain links to an image stored in Amazon S3 (such as those sent from Dovetail Agent version 8 and later).

More information is available in the HTML Emails section.

log4net Section

RuleManager uses the same logging framework that is built into the Dovetail SDK. This framework allows developers and administrators a high degree of flexibility to control the quality and detail of the information RuleManager generates.

Logging capabilities include:

• Different log levels: Debug, Info, Warning, Error, and Fatal
• Can log to: File, Database, Windows Event Log, Email, several other sources, or any combination of these
• Set maximum log file size, number of file rollovers, etc
• Configurable log output (date/time format, log source, etc)
• Dynamic configuration: Make changes on-the-fly, without re-starting your application

RuleManager ships with multiple loggers and logging appenders, which determines where logs are saved (file, email, database, etc.), along with which levels of logging infomation (error, warning, info, debug, none) are saved. The following information describes the default (out of the box) settings. Of course, these can be completely tailored to your preferences.

log4net Loggers

log4net Appenders

More Information on Logging

For full details on configuring the logging configuration file, please refer to the Logging section of the the Dovetail SDK Documentation, or refer to the log4net online documentation.

Application configuration files are in an XML format. .NET expects the XML to be formatted according to a specific tag schema. This is outlined in the .NET Framework SDK documentation under the heading Configuration File Schema.

log4net Project

Log4net is part of the Apache Logging Services project. More information about log4net can be found on the log4net Project Home Page.

log4net is Copyright © 2004-2017 The Apache Software Foundation. All rights reserved.

configSections

Do not change anything in the configSections.

Number of Worker Threads

RuleManager is a multi-threaded application, which allows processing of multiple time_bombs simultaneously. The processing of each time_bomb is done by a worker thread. As work enters RuleManager, it is placed in a queue. This work is then assigned to a thread that does the work on it.

The number of worker threads is controlled by the ApplicationEventProcessorState.NumberOfWorkerThreads configuration setting. By default, this value is set to 5, assuming a single processor machine. Depending upon the application and the server hardware, this value may be set higher or lower for optimal server behavior.

Threads consume resources, so handle this setting with care—you can degrade performance by increasing the value unnecessarily. Adding more threads does not necessarily imply that you can process more work. Even if you add more threads, you are still limited by the power of your processor. A high thread count causes more memory to be used and increases context switching, which can degrade performance.

In general, the default setting should be used for initial testing. If RuleManager is running on a machine with multiple processors, then the default value should be appropriately scaled. For example, set it to 20 for a dual processor machine, 40 for a quad processor machine, etc.

If RuleManager does not appear to be processing time_bombs fast enough, then this setting can be increased slightly. In addition to monitoring the activity of the RuleManager application, system resources (such as memory and CPU usage) should be monitored as well.

Note: If using MsGraph to send email, the MsGraph API has some built-in throttling to be aware of, which will influence how you should configure the number of worker threads. Refer to the Dovetail knowledgebase article on Throttling of the MsGraph API with Carrier and Rulemanager for more information.

MS Graph Account Configuration

RuleManager can send email using the Microsoft Graph API and an Azure application.

Azure Application

In order to you the Microsoft Graph API, an Azure application needs to be setup/configured in the Azure Portal. Once the application is setup, the client ID and tenant ID will be made available.

Example:

From the overview page, click on the "Certificates & secrets" section to create a new client secret.

Azure Application API Permissions

Rulemanager needs the following API permissions in order to send email: Microsoft Graph - Mail.ReadWrite Microsoft Graph - Mail.Send

Example:

If the EmailServiceConfig.UseDefaultFromEmailAddressForAllMessages setting is set to false (which means that the MsGraphUserName will be sending log emails as other users), then additional Azure permissions may be necessary. The Microsoft documentation topic on how to Send Outlook messages from another user may be useful. Please consult with your Azure administrators for more information.

Additional Azure Application settings

Additional settings and/or configuration may be desired, such as Conditional Access. This additional azure app configuration is outside the scope of Dovetail RuleManager's configuration. Please consult with your Azure administrators for more information.

Configure Rulemanager to send email using the Microsoft Graph API

Refer to the Microsoft Graph Email settings to understand the settings relevant to configuring Rulemanager to send email using the Microsoft Graph API.

Throttling of the MsGraph API

If using MsGraph to send email, the MsGraph API has some built-in throttling to be aware of, which will influence how you should configure the number of worker threads. Refer to the Dovetail knowledgebase article on Throttling of the MsGraph API with Carrier and Rulemanager for more information.

RuleManager Features

Based on the .NET Managed Code Environment

Because RuleManager is based on the Microsoft .NET Framework, it inherently gains powerful features such as an object-oriented, managed code, highly secure operating environment. The features and advantages of the Microsoft™ .NET Framework are too numerous to list here, but describes a few of the major ones.

Managed Code

The .NET CLR is a language-neutral development and execution environment that provides modern features such as memory management, Just In Time (JIT) compilation performance enhancements, strongly typed code enforcement, and code access security (CAS) among many others.

This means that applications based on the .NET Framework do not suffer from typical attacks which plague unmanaged code like stack and buffer overflow vulnerabilities. While its possible that the .NET Framework itself could potentially contain a vulnerability like this, patching a single framework is a much less daunting task then it would be to patch many different applications in different ways as is currently the case with unmanaged code.

Garbage Collection

Because memory management is handled by the .NET Framework, memory leaks are far less likely in managed code than in unmanaged code. This helps RuleManager to be a much more robust product -- reducing maintenance and support costs.

Support for Modern Technologies such as XML and Web Services

The .NET FCL provides standardized access to modern technologies and standards such as XML, SOAP (Web Services), TCP/IP, HTTP, and other networking protocols, etc. This allows the RuleManager to support more features and standards out-of-the-box by taking advantage of the standard features in the .NET Framework which is well tested and widely used in the development community.

Runs as a Windows Service

RuleManager is a full Windows Service and runs just like other Windows services. It can be configured to log on as any user. It will start automatically when the computer starts and, most importantly, does not require a user to be logged on to the console.

Secure

RuleManager was designed with security as a top priority. RuleManager will run with very few privileges and is designed to run as the 'Network Service' user on XP and later as recommended by Microsoft for services such as RuleManager. In fact, on Windows XP and later, RuleManager doesn't even have the privileges to write log files unless specifically granted by the administrator of the computer.

For more information about security considerations when using RuleManager, consult the Security Considerations section.

SMTP-based

RuleManager requires no additional software to be installed on the server (other than the .NET Framework and the Dovetail SDK) and connects directly to any SMTP server. SMTP is the main email standard which all Internet email servers must implement in order to interact with each other. This allows RuleManager to work against whichever email solution your organization has chosen to install (including Unix™ and Linux mail servers as well as other Windows-based email servers).

SSL / TLS

Dovetail Rulemanager supports SSL and TLS 1.2 when connecting to a SMTP server. For more information, refer to the Dovetail knowledgebase article on Rulemanager and TLS / SSL

Email Signing

If desired outgoing emails can be digitally signed. For email signing to occur a valid digital certificate must be present in the Personal certificate store of Windows account user whose credentials are used by the RuleManager windows service. To obtain a digital certificate you'll need to purchase one from a digital certificate vendor such as Verisign or Thawte.

Enhanced Logging

RuleManager takes advantage of the powerful and flexible logging features built into the Dovetail SDK. This makes it easier to troubleshoot and diagnose problems that may arise as well as audit and monitor the health of RuleManager. Logging settings can be changed on-the-fly at runtime without having to stop the service and restart it. Changes are seen immediately.

HTML Emails

RuleManager can convert Markdown within an email to HTML. This is commonly used in conjunction with Dovetail Agent (version 8 or later), which supports sending richly-formatted emails using Markdown.

Markdown is a lightweight and easy-to-use syntax for styling text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

The Markdown to HTML conversion is enabled/disabled by the EmailServiceConfig.ParseMarkdown configuration setting.

Markdown can be used in any text that gets sent as an email, including

• Log Email (such as on a case or subcase)
• Business Rules
• Email templates (such as the send_email_about_obj com_tmplte which is used in conjunction with Log Email)
• Commitments (and commitment templates)

Images

RuleManager supports publicly available images within an email. The Markdown for these would look like:

![kittens.jpg](http://www.mycompany.com/images/kittens.jpg)

RuleManager supports images that have been uploaded to Amazon S3 from Dovetail Agent. The Markdown for these would look like:

![image.jpg](store://s3/agent-images/b3445724-abcd-1234-90db-1107f0913e1cx)

Emails that contain a link to an image stored in Amazon S3 (such as those sent from Dovetail Agent version 8 and later) will show the image as an inline image.

This requires the S3 settings to be defined within the FChoice.RuleManager.WindowsService.exe.config file.

RuleManager (as of version 1.6) also support images that have been uploaded to Dovetail Seeker from Dovetail Agent. The Markdown for these would look like:

![image.jpg](store://seeker/agent-images/b3445724-abcd-1234-90db-1107f0913e1cx)

This requires the ResourceStore setting to be defined within the FChoice.RuleManager.WindowsService.exe.config file.

Styles

When RuleManager converts the Markdown to HTML, it also inlines the CSS styles. Inline styles are supported across all major email clients. The styles are defined in the email.css file, which is shipped with RuleManager. This file can be customized, if needed. Once the file is edited, RuleManager needs to be restarted in order to pick up the changes.

Function-based Rule Properties

Rule properties are used in a number of places throughout the Dovetail suite, including:

• Business Rule Conditions
• Business Rule Action Messages
• Canned Response Variables
• Task Manager Properties
• Email Log Templates

Traditionally, a rule property would traverse a path through the schema, starting from the base object, and ending at a column.

For example, the Contact First Name property for a case would use the path case_reporter2contact:first_name.

However, there are instances where a path cannot be traversed, or where a calculation needs to be made.

For example, you may wish to fire a business rule only if all of the subcases on a case have been closed. So your two business rule conditions would be:

1. Number of Subcases is greater than zero
2. Number of Open Subcases is equal to zero

Or, you may wish to fire a business rule if the Number of cases for product X within the last 7 days is greater than 10.

Or you may wish to use a variable (rule property) as part of a canned response that retrieves data from another system using a web service call.

Or you may wish to use a variable (rule property) as part of a task manager property that calculates a value or retrieves data from another system using a web service call.

With these examples, there is not a schema path that can be traversed to provide these values.

You can now write your own custom code for these rule properties. This opens up a whole new avenue for customization.

Dovetail provides an example code project that demonstrates custom function-based rule properties.

This project is freely available at https://dovetailsoftware.github.io/property-extensions/.

That link provides more details, working code examples, and steps on how to build and deploy.

Once your code has been written, and the assembly copied into the application directory, then the property can be defined using the Rule Property UI within Dovetail Agent (Agent version 14 or higher).

• Assign it a property name, as normal.
• Check the "Is Function" checkbox
• For the Path, rather than a schema path, type in the Class Name of your custom property function, such as "NumberOfSubcases"

Configuration Item Rule Properties

Rule properties are used in a number of places throughout the Dovetail suite, including:

• Business Rule Conditions
• Business Rule Action Messages
• Canned Response Variables
• Email Log Templates

Traditionally, a rule property would traverse a path through the schema, starting from the base object, and ending at a column.

For example, the Contact First Name property for a case would use the path case_reporter2contact:first_name.

However, there are instances where a static value may be desired, and this static value cannot be traversed to via a schema path. In these instances, a Configuration Item Rule Property is useful.

Configuration Items

As a refresher, Configuration Items (commonly referred to as Config Items) are a way to store name/value pairs on a system-wide or user-specific level. They are stored in table_config_itm, and can be managed using Dovetail Admin, or imported via a DAT file.

Configuration Items have a Value Type, which defines the type of value they hold, which would be either String, Integer, or Float.

Usage examples

Business Rule Message

You may wish to have a business rule message that contains a static string, such as a URL to a website. Rather than hard-coding that URL in every business rule, the URL can be stored in a Config Item. This would allow the string to be edited at a later time in one place (in the config item), as opposed to having to modify many business rules.

Here's an example of how this would look in a business rule message:

RE: Action Item [Action Item ID] Assigned
Action Item [Action Item ID] has been assigned to you by [Logger]. The priority is [Priority]. Please take appropriate action.
[ConfigItem.Dovetail Agent URL.String]/action-items/[Action Item ID]

Email Template

A URL could also be used in an email template, such as in the send_email_about_obj com_template which is used when a Log Email is performed on a case.

Here's an example of the action for the send_email_about_obj com_template, showing a config item used for the company logo URL, and for the Selfservice URL.

TO: <FOCUS.recipient>
CC: <FOCUS.cc_list>
FR: <FOCUS.sender>
RE: About Case <ADDITIONAL_INFO> : [Case Title] [Subcase Title]
![Company Logo]([ConfigItem.Company Logo URL.String])
<FOCUS.message>
---
[Check the status and update your case (Case <ADDITIONAL_INFO>) online at the Dovetail SelfService site]([ConfigItem.Dovetail Selfservice URL.String]/case/<ADDITIONAL_INFO>)

Business Rule Condition

You may wish to have a business rule that only fires if this is the production database (as opposed to a test or development database). You could use a business rule condition based on a configuration item's value. The config item would indicate the database type (production, test, development, etc. )

1. In your production database, create a config item named Database Instance, and set its value to production.
2. In your test database, create a config item named Database Instance, and set its value to test
3. Create a business rule property named Database Instance.
   Set its path to be [ConfigItem.Database Instance.String].
   This allows for it to be presented to the user in the Business Rule Condition picker UI.
4. Create a business rule with a condition of: Database Instance = production

Now that business rule will only fire if it happens in your production database. It will not fire in the test database.

Defining Configuration Item Rule Properties

Configuration Item Rule Properties can be defined in either of two ways

1. By directly referencing the Config Item using the Configuration Item Reference Syntax.
2. By creating a business rule property whose path follows the Configuration Item Reference Syntax.

Details on both of these are below.

Configuration Item Reference Syntax

To reference a configuration item, use the following syntax:

[ConfigItem.Configuration Item Name.Configuration Item Value Type]

Notice that there are three parts

1. a static string (ConfigItem)
2. the name of your config item
3. and then its value type

All wrapped in square brackets, similar to other rule properties.

Valid values for Configuration Item Value Type are:

• String
• Int
• Float

Examples:

• [ConfigItem.MySupportSiteUrl.String]
• [ConfigItem.default_notifier_frequency.Int]
• [ConfigItem.PriceThreshold.Float]
• [ConfigItem.My Support Site Url.String]
• [ConfigItem.Dots.In.Name.String]
• [ConfigItem.Dots. and spaces In.Name.String]
• [ConfigItem.config item with all values.String]
• [ConfigItem.config item with all values.Int]
• [ConfigItem.config item with all values.Float]

Creating a Business Rule Property for a Configuration Item

You can also create a business rule property that resolves to a configuration item.

This is useful when you want to make it available in the UI, such as in a business rule condition.

To do so, create a rule property with the following settings:

Name: A user-friendly name for the property

Path or Function: [ConfigItem.Configuration Item Name.Configuration Item Value Type]

Note: Be sure to include the square brackets

Here is an example of a rule property for a configuration item:

Comparison to Function-based Rule Properties

Function-based Rule Properties allow you to write your own code to determine a value.

You could write your own Function-based rule property for a config item's value, such as MySupportSiteUrlConfigItem, which would query for the MySupportSiteUrl configuration item and return its String value.

But, a Configuration Item Rule Property makes this process much simpler, and eliminates having to write or deploy custom code.

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:

• Email
• Notifier
• Forward to my Supervisor
• Tone Pager
• Text Pager
• Digital Pager
• None

Dovetail Rulemanager adds support for two additional options:

• SMS
• Slack

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
   
   

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.

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

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:

• 5121234567
• 512-123-4567
• 512.123.4567
• +1-512-123-4567
• +1 512-123-4567
• 512 123 4567

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.

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:

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:

   • 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.

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:

• Within Slack, Click on your UserName
• On the About tab click View full profile link
• Click the vertical 3-dot button next to View as

• Click Copy member ID option

  

For all users:

• Within Slack, choose Administration - Manage Members
• Click on the Download link to download a CSV of the member list
• That CSV file will contain the memberid for each member.

Property Paths

Additional details regarding rule property paths

• SQL Constraints in Property Paths
• Property Expansion in Rule Conditions
• Property Path Constraints

SQL Constraints in Property Paths

When defining custom properties, the path to resolve these properties can traverse through a MTM or OTM relation in one or more portions of its path. The syntax to defines these constraints is:

relation1(SQL_constraint):relation2(SQL_constraint):field

where the SQL_constraint describes some attribute of the field that uniquely identifies that object.

For example, a traversal from contact to site must go through the contact_role table.
A contact can have many contact roles, so a constraint can be used to uniquely define which role is to be used.

To define the Sys Admin role:

contact2contact_role(role_name='Sys Admin'):contact_role2site:site_name

To define the Primary Role:

contact2contact_role(primary_site=1):contact_role2site:site_name

RuleManager supports the use of constraints; however, the following operators within a constraint are NOT supported:

• is null
• is not null
• between

Property Expansion in Rule Conditions

Rules for property expansion in business rule conditions:

• The right hand side can be a literal value.
• The right hand side can be a property (indicated by wrapping in square brackets).
• The left hand side is always considered a property (which gets expanded using the path of the rule property). If the property is not found, it will be interpreted as an empty string.

For example:

Property Path Constraints

In a property, the path traverses through relations to reach the correct field for this property. The syntax for defining a property path is:

relation:relation:field

For example, the Current Owner Phone path for a case looks like:

case_owner2user:user2employee:phone

When traversing through OTM or MTM relations, the result would be multiple sets of data. In order for the property to resolve to a single piece of data, a constraint can be used. The syntax for using a constraint is:

relation(column_name operator value):field

For example:

contact2contact_role(role_name='President'):contact_role2site:site_name

The valid operators for constraints are:

• =
• <
• >
• <=
• >=
• !=
• like
• not like

The following operators are NOT supported in constraints:

• is null
• is not null
• between

Comparison to Amdocs Rulemanager

This section describes the differences between Dovetail RuleManager and Amdocs Rulemanager.

Feature Comparison

Feature		Dovetail RuleManager	Amdocs Rulemanager	Comments
Evaluation and firing of business rules and Actions
Sending outgoing email (via Log Email or Business Rule notifications)				RuleManager works with any SMTP mail server (it does not require Outlook).
HTML emails				See HTML Emails
Commitment warning and expiration notifications
Business Rule action types:
	Message
	Command Line
	Carrier Message			Requires Dovetail Carrier
	Service Message/Run Service
Business Rule notification methods:
	Email			RuleManager does not ship with a pager clerk executable. However, RuleManager can call on an existing pager clerk executable. Note: SMS requires a Twilio account See Notifications.
	Notifier
	Tone Pager
	Digital Pager
	Text Pager
	None
	Forward to my Supervisor
	SMS
	Slack
Notifications based on "Normal Business Hours" and "After Hours"
Notifications based "High", "Medium", and "Low" Urgency
Repeating Business Rule Notifications
Create Activity Log on Action
Business Rule Event Creation Times:
	Event Creation
	Contract Response
	Subcase Commit
	Subcase Warning
	Commitment Time
	Commitment Warning
	Renew Notification
	Quote Expiration Date
	Earliest Service End Date
	Support Program Response
	Process/Action Duration
	Clarify Defined
Business Rule Calendars:
	Elapsed Time
	Customer Business Hours
	Support Business Hours
	Customer Spt Prog Hours
	Internal Spt Prog Hours
	Process Instance
User Defined:
	Properties
	Recipient Alias
	Object Types
	Events
	Event Creation Times
	Calendars
Trend Tracker				RuleManager does not ship with a trend tracker executable. However, RuleManager can call on an existing trend tracker executable or bat file.
Dovetail Task Manager				Requires Dovetail Carrier and Dovetail Agent applications
Tskmgr.exe (Clarify Task Manager)				RuleManager does not ship with a task manager executable. However, RuleManager can call on the Amdocs task manager executable (tskmgr.exe).
ClearBasic Scripts				RuleManager does not ship with any ClearBasic scripts. However, RuleManager can call on the Amdocs cbbatch executable to execute ClearBasic scripts.
Service Manager Executables				RuleManager does not ship with any Service Manager executables. However, RuleManager can call on the Amdocs Service Manager executables.
Report Execution
Support for Custom Function-based Rule Properties
Support for Configuration Item Rule Properties
Holiday support in Business Calendar calculations

Legend
	Supported
	Unsupported
	See comments for explanation

Specific Differences

Additional details regarding specific differences between Dovetail RuleManager and Amdocs Rulemanager.

• Action Calendars
• Case Insensitive Property Names
• Condition Evaluation
• Email from Address
• Process Manager
• Email Attachments
• Rule Properties that traverse a MTM or OTM relation
• focus:path:field notation in email templates

Action Calendars

Calendars are used in business rules so that actions take place relative to the specified business calendar.

Baseline action calendars include Elapsed Time, Customer Business Hours and Support Business Hours.

Case Insensitive Property Names

Condition Evaluation

Email from Address

TO: customer@company.com, cc_customer@company.com
CC: 
FROM: rulemanager@company.com
SUBJECT: regarding Case Number 12345
BODY:
FR: sender_login_name
This is the actual message body typed in by the user.

TO: customer@company.com, cc_customer@company.com
CC: 
FROM: rulemanager@company.com
SUBJECT: regarding Case Number 12345
BODY:
This is the actual message body typed in by the user.

Process Manager

Email Attachments

Rule Properties that traverse a MTM or OTM relation

There are differences in how Dovetail Rulemanager and Amdocs Rulemanager handle when a rule property traverses through a MTM (Many-To-Many) or OTM (One-To-Many) relation.

Rule Properties

A rule property typically resolved to one piece of data.

For example, consider a property that is the site name for a case. The path to resolve this would be case_reporter2site:site_name.

This would resolve to one piece of data, which is the site name.

If a rule property traverses a MTM or OTM, it's possible that the end result would be many pieces of data, not just one.

For example, a solution can be related to many change requests (bugs).

Given a property for a solution named "Related CR IDs", with a property path of probdesc2bug:id_number, this could resolve to multiple ID numbers.

There is a difference in how Clarify Rulemanager resolves these properties versus how Dovetail Rulemanager resolves these properties.

Amdocs/Clarify Rulemanager

If the rule property has a subtype of "Property", then Clarify Rulemanager will not properly resolve the property.

It will return [property name = ???]

The Rulemanager log will show the details of the evaluation:

Info Verbose 1968 0 Mapping 'Related CR IDs' to path… 'Related CR IDs' is a Property Name.

loc_dbg_print: Found string 'Relation '%s' in the relation path cannot be traversed.

Info Medium 1968 0 Property [Related CR IDs] evaluated to '[Related CR IDs=???]'

However, there is a workaround. Clarify Rulemanager can resolve a MTM if the rule property has a subtype of "Alias".

This is typically used for Business Rule Recipient Aliases, i.e. who to notify.

Changing the rule properties subtype to alias allows Clarify Rulemanager to properly resolve it as a single string, with each piece of data separated by a space.

If the solution was related to multiple CRs (23 and 24), then the result would be "23 24" (without the quotes).

The Rulemanager log will show the details of the evaluation:

Info Verbose 1968 0 Mapping 'Related CR IDs' to path… 'Related CR IDs' is a Alias Name.

Info Medium 1968 0 Property [Related CR IDs] evaluated to '21 23 '

As you can see, if its an Alias, it is properly evaluated.

This indicates that the property evaluation mechanism within Clarify Rulemanager is different depending on the subtype (alias or property). Unexpected, but true.

There is one small downside to this workaround - since your property is now defined as an alias, it will not show up in the list of variables on the Business Rule Message Form. And it will show up in the list of Business Rule Recipients on the Business Rule Actions form.

Dovetail Rulemanager

Dovetail Rulemanager simply creates a single string, with each piece of data separated by a space.

Given a property for a solution named "Related CR IDs", with a property path of probdesc2bug:id_number, this could resolve to multiple ID numbers.

If the solution was related to multiple CRs (23 and 24), then the result would be "23 24" (without the quotes).

This works the same whether it's a property or an alias.

Additional Information

Refer to Dovetail Solution 544 for additional information on this topic.

focus:path:field notation in email templates

When outgoing emails are sent, Rulemanager combines the data from the email_log record with a template, specifically the com_tmplte with a title of send_email_about_obj

To include data from the email_log record into the template, use the FOCUS.field syntax. For example, FOCUS.recipient will resolve to table_email_log.recipient.

Clarify/Amdocs Rulemanager

With Clarify/Amdocs Rulemanager, you can use path traversals, such as:

<FOCUS:case_email2case:case_reporter2contact:first_name>

which will traverse from the email_log to the case, from the case to the contact, and resolves to the contact's first name.

But, this causes an issue if you use log email from multiple workflow types, i.e. if you use cases and subcases.

This is because the single send_email_about_obj template is used by log emails for many workflow types, including cases and subcases.

This syntax would resolve for cases, but wouldn't for subcases.

So, any log emails for subcases would contain that text as a literal string, which would not be desired.

If you only use cases, then you can probably get away with this.

Dovetail Rulemanager

With Dovetail Rulemanager, the <focus:path:field> notation is not supported.

Instead, you can use rule properties, such as [Case Title] or [Contact First Name].

These properties would need to be defined as standard rule properties.

This blog posts discusses this in detail, and provides sample rule properties and a sample send_email_about_obj template:

http://clarify.dovetailsoftware.com/gsherman/2010/11/18/use-rule-properties-in-your-outgoing-emails/

A rule property that doesn't resolve properly is ultimately resolved to an empty string, not a literal.

For example, given a send_email_about_obj template that contains this:

Title: [Case Title] [Subcase Title]

For cases, the [Subcase Title] property wouldn't resolve, so it would be blank.

And for subcases, the [Case Title] property wouldn't resolve, so it would be blank.

Hence, you get the output that you want.

Additional Information

Refer to Dovetail Solution 658 for additional information on this topic.

Copyright Notice and Trademarks

Copyright © 2022 Dovetail Software, Inc. All rights reserved

Dovetail Software intends the information in this document solely for its licensees and to aid prospective customers in evaluating Dovetail Software products. Any other use is prohibited. Dovetail Software makes a written warranty to its licensees, as is stated in its written license agreement. Dovetail Software makes no warranty to any other party regarding the accuracy or usefulness of the information contained in this document. Dovetail Software reserves the right to modify the content of this document without obligation to notify any party. Dovetail Software is not liable for consequential or incidental damages.

Dovetail Software develops and supplies software and customizations to the following Clarify products: ClearSupport, ClearQuality, ClearHelpDesk, ClearContracts, Policies and Customers, ClearSales, ProductManager, ClearCallCenter, and ClearLogistics.

Many Dovetail Software products use the following Clarify tools: User Interface Editor, ClearBasic Exchange, Data Dictionary Editor, ClearBasic Batch, Data Exchange, Clarify Business Objects, RuleManager, eBusiness Framework, ClearBasic, and Clarify Low-Level API©.

Clarify, its product names, and tools are trademarks of Amdocs, which may include the following: AmdocsCRM, ClearConfigurator, SalesBasic, ClearConfigurator Workshop, Notifier, eSupport, Classification Engine, eOrder Routing Server, eResponse Manager, ClearEnterprise, Email Clerk, Email Manager, Traveler, e.link, Diagnosis Engine, and Flexible Deployment.