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:

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:

What's New - Version 3.2.0

Enhancements

Additional Information

Upgrading to Version 3.2.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

What's New in Previous Versions

Previous Versions

Version 3.1.0

Bug Fixes

Additional 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

Bug Fixes

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

Bug Fixes

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

Bug Fixes

Requirement Changes

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

Bug Fixes

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

Bug Fixes

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

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

Bug Fixes


Version 2.5.0

Enhancements


Version 2.4.3

Bug Fixes


Version 2.4.2

Bug Fixes


Version 2.4.1

Enhancements


Version 2.4.0

Enhancements


Version 2.3.0

Enhancements

Bug Fixes

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

Requirement Changes


Version 2.2.1

Bug Fixes


Version 2.2.0

Enhancements


Version 2.1.0

Bug Fixes


Version 2.0.0

Enhancements


Version 1.7.0

Enhancements

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

Image Not Available


Version 1.6.0

Enhancements


Version 1.5.1

Enhancements

Bug Fixes

Installer

Dependencies


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


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


Version 1.2.4

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


Version 1.2.3

Dovetail SDK updated to version 2.4.6


Version 1.2.2

Version 1.2.1

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

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:

Dovetail SDK version 2.2 or later
  • Follow the Installation steps outlined in the Dovetail SDK Installation Guide, including the Post Installation Tasks.
  • Run the Data Verifier utility and resolve any data issues.
Operating System
  • Microsoft™ Windows™ 7, 10
    - OR -
    Windows Server 2008, 2008 R2, 2012, or greater
Microsoft™ .NET Framework 4.7.2 (or higher) Full Runtime
  • Install through Windows Update OR download from Microsoft.
Microsoft™ Message Queueing (MSMQ)
  • MSMQ is only required if sending messages to Dovetail Carrier, such as via Dovetail Task Manager, or if using business rules with an action of Carrier Message.
  • Installed in Windows Server 2003 and earlier using Control Panel - Add/Remove Windows Components.
  • In Windows Vista and later versions of Windows search for 'Turn Windows features on or off'.
Hardware
  • Intel™ Pentium II (or compatible) 400MHz or faster
  • 256 MB RAM (1 GB recommended) or higher
  • 1 GB free hard disk space (estimate) free hard disk space or more
Twilio Account and Phone Number
  • Dovetail Rulemanager uses Twilio (https://www.twilio.com) as an SMS provider. You must have a Twilio account in order to use SMS notifications. If you are not using SMS as a notification option, then Twilio is not required.
Clarify™ System Environment
  • Clarify™ 7.0 through 12.5, Amdocs 6 through 7.5
  • Microsoft™ SQL Server™ 2000 SP3 and greater
    - OR -
    Oracle™ Database Server 8, 9, 10g, 11g, 12c, and 19c

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.
    Installer Login Screen
    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.
    Load Information Screen
    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.
    Load License Screen
    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:

[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 Section

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

Parameter Name Required Default Description
fchoice.dbtype No "MSSQL" Specifies the type of provider ClarifyApplication should to connect to the DB. Standard values are "MSSQL", "ORACLE", or "ODPNET".
fchoice.connectionstring Yes N/A An ADO.NET connection string to use with the specified DB type (or default if none is specified). The default provider is MSSQL and the connection string must be useable by the System.Data.SqlClient.SqlConnection class. Consult the SqlConnection.ConnectionString property documentation for specifics about what parameters are allowed in the connnection string. Please consult the documentation for other ADO.NET providers if you plan on using a different data provider type (like Oracle or Sybase).

Maximum Connection Pool Size (Max Pool Size): It is recommended to override the default maximum database connection pool size. This setting is defined as part of the connection string. By default, the maximum pool size is 100. RuleManager does not typically need this many connections. The recommended number of for the maximum connection pool size is 20.
fchoice.disableloginfromfcapp Yes "false" Allows the RuleManager to use a single login for both the FCApplication and FCSession logins.


fchoice Section


RuleManager specific configuration settings:
Parameter Name Required Default Description
ApplicationEventExecutor.
StopApplicationIfEmailServiceIsDown
No true When an email cannot be sent and the maximum number of retries has been exceeded, the application by default will stop. If this setting is false the application event will be rescheduled to the far future and the application will continue running.
ApplicationEventProcessorState.
NumberOfWorkerThreads
Yes 5 Number of time_bombs that will be executed simultaneously.

See Also:
Number of Worker Threads
ApplicationEventProcessorState.
PollingIntervalMilliseconds
Yes 1000 How often the application polls the database for expired time_bombs.
ApplicationEventProcessorState.
ApplicationEventChunkSize
Yes 200 The total number of expired time_bombs that will be retrieved per database poll.
VolitileResourceExecutor.
NumberOfRetries
Yes 300 Retry mechanism when the application communicates with external resources such as the database or smtp server. How many times should it retry before giving up.
VolitileResourceExecutor.
RetryDelayMilliseconds
Yes 2000 Retry mechanism when the application communicates with external resources such as the database or smtp server. How long to wait between retries.
NotificationConfig.
DefaultNotification
Yes Email If notification recipient does not have a notitification preference this is how the user will be notified.
Valid options: EMAIL, NOTIFIER, FORWARD TO MY SUPERVISOR, NONE
NotificationConfig.
PagerApplicationPath
No The path and filename of the paging application. Example: c:\paging\pager_clerk.bat
LicenseValidator.
LicenseExpirationWarningDays
Yes 30 Number of days prior to license expiration that warnings will be logged. It will repeat these warnings every day. This warning will be logged using the standard logging mechanism (log4net), so be sure that your logging is configured properly.
Resource.ResourceStore No Where are inline images retrieved from. Valid values are S3 or Seeker
Search.ResourceTimeout No 1000 days How long should inline image URLs be valid for.
Search.TokenIsUnique No True Determines whether a Dovetail SeekerProxy URL for an inline image will have a unique token or not. Leave as True.
Carrier.QueueAddress No msmq://localhost/dovetail.carrier Address of Dovetail Carrier's incoming message queue. Typically used as part of Dovetail Task Manager.
RegularExpressionSettings.
TimeoutInSeconds
No 30 Number of seconds a regular expression will execute before timing out. Timed out expressions will throw an exception.

Regular expressions are used when evaluating rule conditions. It is possible that in some rare cases a complex regular expression for certain inputs could runaway. This timeout is a relief value preventing the consumer thread from getting stuck evaluating a regular expression.


Email settings

These settings define how Rulemanager sends outgoing emails.

Parameter Name Required Default Description
EmailServiceConfig.
DefaultFromEmailAddress
Yes email@domain.com The email address that RuleManager should use in the FROM: field when sending out emails.
EmailServiceConfig.
DefaultFromEmailAddressDisplayName
No Company Support The display name for the default From email address. For example, the default settings would be seen as Company Support email@domain.com.
Note: This is only supported when sending emails using SMTP. It does not work with MsGraph.
EmailServiceConfig.
UseDefaultFromEmailAddressForAllMessages
Yes false When RuleManager sends emails, it can honor the "FR:" token in the com_tmplte, or not. If this setting is set to true, then all emails will be sent from one address (EmailServiceConfig.DefaultFromEmailAddress). If set to false, and the com_tmplte has a "FR:" token, then the "FR:" token will be used.

For example, when sending an email out, the send_email_about_obj com_tmplte is used. The baseline com_tmplte has "FR: " in it. If UseDefaultFromEmailAddressForAllMessages is set to true, then the email will come from the EmailServiceConfig.DefaultFromEmailAddress. If UseDefaultFromEmailAddressForAllMessages is set to false, the the email will come from the actual sender of the email.
EmailServiceConfig.
EnableTestMessage
Yes true Should test message be sent during application startup to validate SMTP configuration?
EmailServiceConfig.TestEmailAddress Yes test@domain.com Email address which will receive the startup test email message.
EmailServiceConfig.ParseMarkdown No false This setting enables or disables Markdown parsing of emails. More information is available in the HTML Emails section.


SMTP Email settings

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

Parameter Name Required Default Description
EmailServiceConfig.Mode No SMTP Specify which mode Rulemanager uses for sending email. Supported Modes are SMTP, and MsGraph.
EmailServiceConfig.Host No emailServer IP or hostname of the SMTP server. If left blank, localhost will be used.
EmailServiceConfig.Port No 25 The TCP/IP port to use when connecting to the SMTP server.
EmailServiceConfig.EnableSsl No false Specify whether the SmtpClient uses Secure Sockets Layer (SSL) to encrypt the connection.
EmailServiceConfig.SmtpSslMode No UseStartTlsIfSupported Specify which mode the SmtpClient uses for the Secure Sockets Layer (SSL) connection. Supported Modes are UseStartTlsIfSupported, UseStartTls, OnConnect, and Manual. For more information, refer to the Dovetail knowledgebase article on Rulemanager and TLS / SSL
EmailServiceConfig.UserName No The username to use when connecting to the SMTP server. Some SMTP Servers require authentication.
EmailServiceConfig.Password No The password to use when connecting to the SMTP server. Some SMTP Servers require authentication.
EmailServiceConfig.Timeout No 100 Sending an email will timeout if the send is not completed after this many seconds.
EmailServiceConfig.SignOutgoingEmails No false When true RuleManager will look for a valid digital certificate for the sending email address. If found the outgoing email will be digitally signed using the certificate.


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.

Parameter Name Required Default Description
EmailServiceConfig.
Mode
Yes, if sending email using MsGraph SMTP Specify which mode Rulemanager uses for sending email. Supported Modes are SMTP, and MsGraph. If using the MsGraph API, this must be set to MsGraph
EmailServiceConfig.
MsGraphUserName
Yes, if EmailServiceConfig.Mode is set to MsGraph Username for the email account
EmailServiceConfig.
MsGraphClientId
Yes, if EmailServiceConfig.Mode is set to MsGraph Azure application client ID
EmailServiceConfig.
MsGraphClientSecret
Yes, if EmailServiceConfig.Mode is set to MsGraph Azure application client secret
EmailServiceConfig.
MsGraphTenantId
Yes, if EmailServiceConfig.Mode is set to MsGraph Azure application tenant ID


SMS settings

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

Parameter Name Required Default Description
Sms.EmployeeSmsField No beeper 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.
Twilio.From No Your Twilio phone number used to send SMS messages.
Twilio.AccountSid No Your Twilio SID
Twilio.AuthToken No Your Twilio Authentication Token


Slack settings

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

Parameter Name Required Default Description
Slack.AuthToken No Your Twilio Authentication Token. For more info, refer to the Slack Notifications section
Slack.MemberField No x_slack_member_id Field on table_user where an employee's Slack Member ID is stored. For more info, refer to 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.

Parameter Name Required Default Description
S3.AWSId No Your AWS ID Your Amazon Access Key ID
S3.AWSSecret No Your AWS secret Your Amazon Secret Access Key
S3.Bucket No Your S3 Bucket S3 bucket where files will be downloaded from
S3.Region No us-east-1 When creating a bucket if you select any region beside "US Standard" you will need to configure this setting with the correct region string.
S3.KeyPrefix No agent-images A prefix represents a set of keys in the S3 bucket that allows applications to organize and browse their keys hierarchically, similar to how a file system organizes files into directories.
S3.DownloadURLLifeSpan No 5500 days Maximum value is "5500 days"


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:

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
Logger Name Description
FChoice.RuleManager Logs for the RuleManager processes
FChoice Dovetail SDK logging details
Spring Spring is an application framework used internally by RuleManager. Typically these logs are not needed by customers.


log4net Appenders
Appender Name Description
VerboseRollingFileAppender Verbose logging information saved to a rolling log file.
WarningAndErrorsRollingFileAppender A rolling log file that contains only warnings and errors.
SmtpAppender Warnings and errors will be sent to the appropriate email address, such as an administrator. Be sure to set the to element to a valid email address
ConsoleAppender When running RuleManager in console (command-line) mode, warnings and errors will be displayed in the console.


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:

azure application

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

Azure Application API Permissions

RuleManager needs the "Microsoft Graph - Mail.Send" API permission in order to read and process email.

If you are using the same application for receiving incoming email with Dovetail Carrier, the "Microsoft Graph - Mail.ReadWrite" permission is also needed.

Example:

azure application api permissions

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


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:

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

Configuration Item Rule Properties

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

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:

Examples:

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:

Edit Rule Property

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:

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 Real Time Messaging API (RTM) 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="SlackSettings.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" />

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:

Property Paths

Additional details regarding rule property paths


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:


Property Expansion in Rule Conditions

Rules for property expansion in business rule conditions:

For example:

Property Operator Value Comments
Site Name starts with Dovetail Software The condition evaluator will expand the property "Site Name" to its actual value, and compare it to the literal string "Dovetail Software".
Site Name starts with [My Property] The condition evaluator will expand the property "Site Name" to its actual value, then expand the property "My Property" to its actual value, and compare the two. If "My Property" is not defined as a property, then the Site Name property will be compared to the literal string "[My Property]" (including the square brackets).
Unknown Property starts with foo bar The condition evaluator will expand the property "Unknown Property" to its actual value, and compare it to the literal string "foo bar". If "Unknown Property" is not defined as a property, then it will expand to an empty string, and the empty string will be compared to the literal string "foo bar".

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:

The following operators are NOT supported in constraints:

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 Green Check Green Check  
Sending outgoing email (via Log Email or Business Rule notifications) Green Check Green Check RuleManager works with any SMTP mail server (it does not require Outlook).
HTML emails Green Check Red X See HTML Emails
Commitment warning and expiration notifications Green Check Green Check  
Business Rule action types:      
  •  
Message Green Check Green Check  
  •  
Command Line Green Check Green Check  
  •  
Carrier Message Green Check Red X Requires Dovetail Carrier
  •  
Service Message/Run Service Red X Green Check  
Business Rule notification methods:      
  •  
Email Green Check Green Check 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 Green Check Green Check
  •  
Tone Pager Blue Exclamation Green Check
  •  
Digital Pager Blue Exclamation Green Check
  •  
Text Pager Blue Exclamation Green Check
  •  
None Green Check Green Check
  •  
Forward to my Supervisor Green Check Green Check
  •  
SMS Green Check Red X
  •  
Slack Green Check Red X
Notifications based on "Normal Business Hours" and "After Hours" Green Check Green Check  
Notifications based "High", "Medium", and "Low" Urgency Green Check Green Check  
Repeating Business Rule Notifications Green Check Green Check  
Create Activity Log on Action Green Check Green Check  
Business Rule Event Creation Times: Green Check Green Check  
  •  
Event Creation Green Check Green Check  
  •  
Contract Response Green Check Green Check  
  •  
Subcase Commit Green Check Green Check  
  •  
Subcase Warning Green Check Green Check  
  •  
Commitment Time Green Check Green Check  
  •  
Commitment Warning Green Check Green Check  
  •  
Renew Notification Green Check Green Check  
  •  
Quote Expiration Date Green Check Green Check  
  •  
Earliest Service End Date Green Check Green Check  
  •  
Support Program Response Green Check Green Check  
  •  
Process/Action Duration Red X Green Check  
  •  
Clarify Defined Green Check Green Check  
Business Rule Calendars:      
  •  
Elapsed Time Green Check Green Check  
  •  
Customer Business Hours Green Check Green Check  
  •  
Support Business Hours Green Check Green Check  
  •  
Customer Spt Prog Hours Green Check Green Check  
  •  
Internal Spt Prog Hours Green Check Green Check  
  •  
Process Instance Red X Green Check  
User Defined:      
  •  
Properties Green Check Green Check  
  •  
Recipient Alias Green Check Green Check  
  •  
Object Types Green Check Green Check  
  •  
Events Green Check Green Check  
  •  
Event Creation Times Green Check Green Check  
  •  
Calendars Green Check Green Check  
Trend Tracker Blue Exclamation Green Check 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 Green Check Red X Requires Dovetail Carrier and Dovetail Agent applications
Tskmgr.exe (Clarify Task Manager) Blue Exclamation Green Check RuleManager does not ship with a task manager executable. However, RuleManager can call on the Amdocs task manager executable (tskmgr.exe).
ClearBasic Scripts Blue Exclamation Green Check RuleManager does not ship with any ClearBasic scripts. However, RuleManager can call on the Amdocs cbbatch executable to execute ClearBasic scripts.
Service Manager Executables Blue Exclamation Green Check RuleManager does not ship with any Service Manager executables. However, RuleManager can call on the Amdocs Service Manager executables.
Report Execution Red X Green Check  
Support for Custom Function-based Rule Properties Green Check Red X  
Support for Configuration Item Rule Properties Green Check Red X  
Holiday support in Business Calendar calculations Green Check Red X  
Legend
Supported Supported
Unsupported Unsupported
See comments for explanation See comments for explanation

Specific Differences

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


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.

Amdocs Rulemanager Dovetail RuleManager
If the calendar of the action cannot be found, then the action is not processed. If the calendar of the action cannot be found, then Elapsed Time is used for calculating the action escalation time.

Case Insensitive Property Names

Amdocs Rulemanager Dovetail RuleManager
On Oracle databse systems, property names (table_prop_name.prop_name) are case sensitive.
This allows seemingly duplicate property names to be defined, which can lead to confusion.For example, for the subcase object (obj_type = 24), two different properties can be defined:
  • Site Name
  • site name

This can lead to confusion as to which one is actually being evaluated.
Property names are treated as case insensitive. RuleManager will use the first one it finds in the database, regardless of the case of the property name.
For example, for the subcase object (obj_type = 24), two different properties can be defined:
  • site name
  • Site Name

RuleManager will use the first one it finds in the database.

Condition Evaluation

Amdocs Rulemanager Dovetail RuleManager
When RuleManager reads a scheduled action timebomb from the table it re-evaluates its conditions. If the conditions have changed and are no longer true, the timebomb is ignored and deleted and any other timebombs created by the same rule are deleted. If the timebomb is a repeating timebomb it is not fired and the timebomb is removed. As would be expected, it the condition is re-established, the timebombs do not reappear.

For example, consider a rule in that has three actions when a case is created with severity equal to Urgent:
  • Notify me in 24 hours
  • Notify my supervisor in 48 hours
  • Notify the owner every 20 minutes for the next 24 hours

When a case is created with severity equal to Urgent, three timebombs get created, one for each of the actions. If I accept this case and lower the severity to medium, when the 20 minute mark happens all three timebombs are deleted from the database. Of course if I say "oops - misset the Severity" - and change it back to Urgent, the timebombs do not get remade (A nice way to prevent your supervisor from being notified :-) )
Rather than future timebombs being deleted, the conditions will be re-evaluated at the expiration time of these future timebombs.

Conside the same rule example to the left.

When a case is created with severity equal to Urgent, three timebombs get created, one for each of the actions. If I accept this case and lower the severity to medium, when the 20 minute mark happens, the rule condition evaluations will occur, which will evaluate to false, and the notification will not occur.

If I say "oops - misset the Severity" - and change it back to Urgent, the timebombs will still be there, thus 20 minutes later the owner notification will happen, as will the 24 hour and 48 hour notifications.

Email from Address

Amdocs Rulemanager Dovetail RuleManager
When an email is sent from the system, Rulemanager uses a commitment template (com_tmplte) to determine the format and details of the actual email. These templates can be configured to specify a from address.

For example, when sending an email out, the send_email_about_obj com_tmplte is used.
This template looks like:

TO: , FR: RE: Regarding Case Number

Notice that the com_tmplte has FR: token in it.

When the Amdocs Rulemanager sends an email, it does not interpret the FR: token as a From token - instead, it simply includes the FR: token and value in the email body.

In order for Amdocs Rulemanager to send email, it connects to a Microsoft Outlook email client, and it connects as a particular mail account user. Whenever Amdocs Rulemanager sends email, it uses that mail account user as the from address. For example, if the Outlook mail account is rulemanager@company.com, then all emails (including Log Emails, Commitment Escalations, and Business Rule Actions) will have a from address of rulemanager@company.com.

So, putting it all together, a Log Email sent from a case will look something like:

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.

Notice that FR: sender_login_name is included in the body, and the from address is always from the rulemanager email address.
RuleManager has the ability to honor the FR: token in the template or not. It can behave exactly as Amdocs Rulemanager does, or it can function as many customers prefer.

For example, assuming the following configuration settings:

EmailServiceConfig.UseDefaultFromEmailAddressForAllMessages = false
EmailServiceConfig.DefaultFromEmailAddress = rulemanager@company.com

Then a Log Email sent from a case will look something like:

TO: customer@company.com, cc_customer@company.com
CC:
FROM: sender_email_address@my_company.com
SUBJECT: regarding Case Number 12345
BODY:

This is the actual message body typed in by the user.

Notice that the from address is the actual sender of the email, and the body does not include FR: sender_login_name.

Of course, if you prefer to have it the "old" way, you can.

For example, assuming the following configuration settings:

EmailServiceConfig.UseDefaultFromEmailAddressForAllMessages = true
EmailServiceConfig.DefaultFromEmailAddress = rulemanager@company.com

Then a Log Email sent from a case will look something like:
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.

Notice that the from address is the rulemanager email address, and the body does not include FR: sender_login_name.

Process Manager

Amdocs Rulemanager Dovetail RuleManager
As of Clarify version 12, Amdocs added a new product to their ClarifyCRM suite: Process Manager. Process Manager allows customers to automate their business logic. These processes can be invoked via RuleManager, using a business rule. These business rules use a new message type: Run Service. In addition, then can use a Business Rule Event Creation Time of Process/Action Duration and a Business Rule Calendar of Process Instance. Integration with the Amdocs Process Manager is not supported, nor are its associated constructs.

Business Rule Actions with a Message Type of Run Service are not loaded from the database, and thus are essentially ignored.

Business Rule Event Creation Times of Process/Action Duration will be logged as an error, and that particular rule action will be ignored.

Business Rules using a calendar of Process Instance will be defaulted to Elapsed Time. An error will also be logged in this situation.

Email Attachments

Amdocs Rulemanager Dovetail RuleManager
Amdocs Rulemanager does not have functionality. RuleManager includes attachments for emails initiated via a LogEmail action. The application taking that action, such as Dovetail Agent or the Clarify Client, is responsible for relating the LogEmail (table_email_log) to the attachment(s) (table_doc_inst). Because RuleManager will only attach files that it has access to, we recommend that the path to the attachment is a UNC path such as "\server\path\file.ext". If RuleManager cannot access an attachment, the email will still be sent without the attachment. RuleManager will log an error when this situation occurs. Refer to the logging section for more information on logging configuration.

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.