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.
| 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). 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. It may contain Integrated Security=SSPI;Persist Security Info=True;Important: Before Integrated Security can be used a server set up procedure must be followed, see Integrated Security with Dovetail server applications for details. |
| fchoice.disableloginfromfcapp | Yes | false | Allows the RuleManager to use a single login for both the FCApplication and FCSession logins. |
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. |
| VolatileResourceExecutor. 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. |
| VolatileResourceExecutor. 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 | 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. |
| DovetailDatabaseSettings. ApplicationUsername |
Depends | emptyString | A valid Clarify username used by the application. Used only when Integrated Security is specified in fchoice.connectionstringMust have a value when Integrated Security is to be used |
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. |
| EmailServiceConfig. ParseMarkdownTimeoutMilliseconds |
No | 1000 | Parsing an email for markup will timeout if not completed after this many milliseconds. |
Email Failures
Sending an email may fail for a variety of reasons, and Rulemanager will handle failures differently, depending on the type of failure.Email Server Connectivity Failures
If Rulemanager can't connect to the mail server after a certain number of retries, Rulemanager will shutdown, as sending email is a critical function of the application. This is controlled by these settings:ApplicationEventExecutor.StopApplicationIfEmailServiceIsDownVolatileResourceExecutor.NumberOfRetriesVolatileResourceExecutor.RetryDelayMilliseconds
Temporary Failures
If Rulemanager can't send an email due to throttling by the mail server (typically MsGraph), then Rulemanager will retry, according to the retry settings. Refer to the MsGraph Retries - Additional Information section for additional details.Permanent Failures
There are a number of scenarios where sending an individual email can fail. As an example, if attempting to send to an invalid email address, such asfirst.last.@company.com, that will fail. This type of email failure should not retry (as it will never succeed), and it shouldn't cause Rulemanager to shut down.If such an error is detected, the time bomb for this send email action will be rescheduled to the far future (1/1/2999) in order to avoid retry attempts and to allow for investigation into the root cause. The
EmailNotDeliveredErrorMessageIndicators.config file defines which errors belong to this category.Each pattern in this file contains a string which will be compared against error messages received from the Send Email operation. If there is a match, Rulemanager will not retry the send action but log the error message and reschedule the time bomb to the far future. If a previously unknown error falls into this category (which could cause Rulemanager to shut down), then the specific error message can be added to the
EmailNotDeliveredErrorMessageIndicators.config file, so as to prevent a similar problem in the future. Note: Rulemanager needs to be restarted after any edits to config files.
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 | |
| MsGraphExecutor. NumberOfRetries |
No | 3 | This setting is not replacing the VolatileResourceExecutor.NumberOfRetries setting.Number of retry attempts if an MsGraph transient exception is detected. Maximum value is 3 (as MSGraph only allows 3 retries of the same operation). |
| MsGraphExecutor. RetryDelayMilliseconds |
No | 2000 | This setting is not replacing the VolatileResourceExecutor.RetryDelayMilliseconds setting.How long to wait between retries in case an MsGraph transient exception is detected. Note: if RetryAfter header is returned by MSGraph with a value greater than zero it will take precedence over the MsGraphExecutor.RetryDelayMilliseconds setting. |
| MsGraphExecutor. NumberOfReschedules |
No | 3 | Number of times the timebomb is to be rescheduled to a future date after all retry attempts in response to MsGraph transient exceptions are exhausted. |
| MsGraphExecutor. RescheduleDelaySeconds |
No | 120 | By how long the timebomb is to be rescheduled into the future after all retry attempts in response to MsGraph transient exceptions are exhausted. |
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.
| 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 Slack 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 |
| Slack.BaseURL | No | https://slack.com |
Base slack.com URL |
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:
- 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
| 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:
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.