CCH KPI Monitoring : Administration

Administrator: Logging In

Once you have logged into KPI Monitoring, expand the 'Admin' branch and you’ll see a window like the following:

KPI Monitoring Admin Options (on left)


User Accounts: Roles & Users

Expand the 'User accounts' option and you’ll see options for 'Roles' and 'Users'. It’s important to understand the difference between these in KPI Monitoring:

Roles:  This controls what KPI Monitoring functions a person can access – such as creating events, viewing events, creating users, et cetera.

Users:  This controls what KPI Monitoring data a person can access – for example, user ‘A’ might have access to KPI Monitoring events for application #1, whereas user ‘B’ might have access to KPI Monitoring events for application #2.

Each KPI Monitoring user is assigned a specific role – and that role controls what KS options and functions that user can access within that person’s allowed data sets.

You can copy and paste both role and user records using the 'Copy' and 'Paste' buttons that appear at the top of each option.

Multi-Tenancy Access Rights

In a multi-tenancy environment, where a single KPI Monitoring installation is being used by multiple customers, there will typically be a single overall KPI Monitoring System Administrator who can grant access rights for all tenants. This 'KS Admin' will typically create individual customer-specific KS administrators, such as 'KS Tenant #1 Administrator', 'KS Tenant #2 Administrator' and so on. The KS System Administrator is responsible for specifying what data sets each tenant administrator has access to, as well as what system options each tenant administrator can access.

It then becomes the responsibility of the individual KS Tenant Administrators to create the user profiles for their respective users – controlling what KPI Monitoring functions each of their users can access.

Users: Roles

The “Roles” tab within the “Users” option controls the roles that this user is able to assign to others as well as the roles that this user is able to administer.

Users: Account Access

The “Accounts” tab controls which accounts (if any) a user can utilize in the configuration of KS events that use email, webcast, and SMS for the sending of alert messages, and that use SSRS for the generation of reports. This includes:

• Which email account(s) the user can select from
• Which webcast locations the user can select from
• Which SSRS reporting servers the user can select from
• Which SMS account(s) the user can select from.  

  Note:KPI Monitoring uses Twilio as its SMS Provider and users will need to purchase a Twilio subscription to send text-based alerts. Just two fields from Twilio (account SID and auth key) will need to be entered into KPI Monitoring

If you wish to allow a user to select from all email, webcast, texting locations, and SSRS servers, click in the checkbox next to “All Current and Future Accounts”.

Users: Appplication Access

This tab shows a list of all the applications (e.g., ERP, CRM, HR) that are currently configured to be monitored by KPI Monitoring. If you wish to allow a user access to all applications, click in the checkbox next to “All Applications”. Otherwise, place a checkmark next to only those applications whose data and events you wish the current user to be able to access. This is particularly important in multi-tenant implementations, as this allows you to ensure that each KPI Monitoring tenant has access to only those events created for their organization.

Users: Subscribers

This tab shows a list of all the alert recipients (“subscribers”) that are currently available to be maintained as well as selected (within an event) to receive alerts from KPI Monitoring. Note the following:

Subscribers may be individual people, groups of people, and “computers” – locations to which reports and files may be FTP’d.

The subscribers referred to here are “standard” subscribers, i.e., people or groups who may be selected from a list. An event may also deliver alerts to “advanced” subscribers; these are people who are associated with the triggered condition (such as “the customer” or “the salesperson assigned to that customer”.

If you wish to allow a user to configure as well as select (within events) all subscribers, click in the checkbox next to “All Subscribers”. Otherwise, place a checkmark next to only those subscribers whose data and events you wish the current user to be able to access.

Users: Connections

This tab shows a list of all the “connection” records (.NET data providers and ODBC and OLE/DB data sources currently configured within KPI Monitoring). If you wish to allow a user access to all of the “connection” records, click in the checkbox next to “All Connections”. Otherwise, place a checkmark next to only those connections whose configurations you wish the current user to be able to access and modify.

Email Account Creation

The following quick creation set-up steps will suffice for most organizations; please follow these steps and if you are not able to successfully test your email account upon completion, please follow the more detailed steps under “Account Creation”.

If you are using a web-based email account, it may need to be configured to "allow access for less secure applications." This is done to allow KPI Monitoring or other applications the ability relay mail through the email provider.

1. Go to KPI Monitoring Admin > Services > Email Accounts.
2. Click the Add button located at the top left of the window. The Email Account Editor module opens.
3. Click the appropriate Email Type: SMTP or OAUTH2.

SMTP Email Type

At the bottom of the module, select which email defaults to apply:

• Gmail
• Hotmail
• Yahoo
• Exchange
• Outlook 365

1. In the Email Account Description field, you may change the text BEFORE the first slash to reflect a description of the account, but it is critically important not to delete or change the remainder of the information.
2. In the Login Name, Mailbox or Profile Name field, enter your user ID. This ID is the full email address account name, for example: MyAccount@gmail.com.
3. In the Password field, enter the password for the email account.
4. Ensure the Active box is checked.

TLS and Authentication Methods:
For the TLS (Transport Layer Security) and Authentication methods, do not change the defaults.

In the SMTP/IMAP Internet Email Information section, enter in the following information:

• Outgoing Mail (SMTP) Server Name
• SMTP From Name (Required for Internet)
• SMTP Port (Optional)
• Incoming Mail (IMAP) Server Name
• IMAP Port (Optional)

Click Save.

0AUTH2 Email Type

Please note, if using OAUTH2 email type, the on-prem installation relies on a service in the cloud to connect to Microsoft. Users should use the Advanced Email Configuration for OAUTH2 for the client credentials workflow.

• Select the Email Type. Choose SMTP or OAuth2 from the dropdown menu.
• In the Email Account Description field, you may change the text BEFORE the first slash to reflect a description of the account, but it is critically important not to delete or change the remainder of the information.
• In the Login Name, Mailbox or Profile Name field, enter your user ID. This ID is the full email address account name, for example: MyAccount@gmail.com.
• Ensure the Active Box is checked.

Click the Test Connection button. If a green checkmark is visible, the connection is valid. Click the Reconnect button if the green checkmark is not visible.

Testing Email Accounts

1. Click on the Description area of the email account you just created so the line becomes highlighted.
2. Click the Perform Email Test button.
3. Enter the desired recipient email address and click OK.
4. Check the recipient email account to see if the test message has sent successfully.

Email Response System Options (Incoming)

This option refers to the ability for KPI Monitoring to monitor and respond to the content of incoming email messages, such as messages that are sent to an organization’s generic email accounts – e.g., info@KPI Monitoring.com, support@KPI Monitoring.com, et cetera.

The configuration and use of the Email Response System (ERS) is covered in a separate chapter of this manual – please refer to that chapter for details.

Events tab

On this tab, all events are listed with their associated applications. A green check mark indicates the events is active.

To update a sender account for an event, check the box in the Is Sender? column and then click the Update button to set the current email account as the sender on all events.

History tab

Lists the following information about the email account:

• Created By
• Created On
• Last Changed By
• Last Changed On

Error Log Reporting

Most of the options within KPI Monitoring can have “error reporting” turned on for enhanced details regarding any errors that KPI Monitoring is experiencing during event processing. The error logging level for the KPI Monitoring Portal is set in the “Portal” option within Application Settings; all other logging levels are set within the “Engine Modules” option.

Both the KS Portal and KS Service write text-based file logs on the server that can be used for troubleshooting any issues that might occur.

Number of Log Files to Retain

The number of backup log files retained is determined by the setting “Maximum Number of Backup Log Files to Keep” (in both the “Portal” and “Engine” tabs). Set this value to ‘1001’ to retain all log files.

Log File 'Rolling Style'

In both the Portal and Engine tabs, there is a setting for the “Log Based on Rolling Style” The “rolling style” determines how and when new log files are created.

Once – Each module has a single log file which will grow as data is added to it. The logs will be backed-up and replaced by a new file only when the KPI Monitoring Windows Service is stopped or when the KPI Monitoring web application in IIS is stopped and restarted. Older log files will have names such as KSService.1.log, KSService.2.log, et cetera.
Size – Each module creates a log file that is backed-up and replaced by a new file when the current log reaches the size configured in “Log File Maximum Size”. Older log files will have names such as KSService.1.log, KSService.2.log, et cetera.
Date – Log files are backed-up and replaced every day. The format of the log file name is determined based on the
settings of the “Log Date Pattern” and the “Log File Path” (see following sections). As an example, a portal log file from 10/1/2020 would have the name PubKSPortal-20201001.log
Composite – This is a combination of Size and Date styles described previously. A new log file is created when the size limit is reached or the date changes.

Log File 'Date Pattern'

The “Log Date Pattern” (set in both the Portal and Engine tabs) is the format of the date (for the file name) when used in the naming of log files.

Log File Paths and Names

KPI Monitoring uses the following settings to determine the locations and names of its log files:

Portal:  See the setting “Portal Log File Path”. The default name and location is:

C:\ProgramData\KPI Monitoring\KSLogs\PortalLogs\PubKSPortal.log

Engine: See the setting “Service Log File Path”. The default name and location is:

C:\ProgramData\KPI Monitoring\KSLogs\ServiceLogs\KSService.log

Log File Names for the Engine Modules

Within the “Engine” tab is a setting called “Individual Log Files for Engine Modules”.

This setting determines whether the Engine modules listed below will write a single log file for all the engine modules (set to ‘No’), or will write separate log files for each engine module (set to ‘Yes’).

If the “Individual Log Files for Engine Modules” setting is enabled, the following log files are created for the engine modules:

• KSService-Action.log
• KSService-ApplicationEvents.log
• KSService-Copy.log
• KSService-Email.log
• KSService-ERS.log
• KSService-Report.log
• KSService-Scheduler.log
• KSService-SMS.log
• KSService-Webcast.log

Logging Levels

Set the logging levels as follows:

• ERROR:  Only exceptions and errors that occur in the application will be logged. This is the default (and minimum) level of error reporting.
• WARN:  Errors and warnings are logged.
• INFO:  Informational messages are written to the error logs, in addition to errors and warnings. These include such items as parameters passed into a query or report.
• DEBUG:  This is the most detailed level of log reporting. Debug level diagnostics are written in addition to INFO, ERROR and WARN messages. These include query results, email message texts, and other detailed data.

In general, we recommend setting the log level to ERROR or WARN during normal processing.

To modify any of these settings, simply click in the corresponding “Value” field and type in your selection.  Those settings which have pre-defined values to choose from (such as a log level of “info”, “warn”, “error”, and “debug”) and will show a list button when you click in the “Value” field.

Engine Modules: 'Maximum Attempts'

If KPI Monitoring attempts to run an event and an error occurs, KPI Monitoring will attempt to “re-try” running the specific event component that failed. The number of times KPI Monitoring will attempt to re-try the failed process is referred to as “maximum attempts”. You can set the number of maximum attempts for the following event components in the “Engine Modules” tab:

• “Events”:  Event triggers
• “Email”:  Sending an email alert
• “SMS”:  Sending a text (SMS) alert
• “Webcast”:  Sending a webcast alerts
• “Reports”:  Generating an event’s reports and/or charts
• “Actions”:  Executing an event’s “actions”

The “Maximum Attempts for . . . “setting specifies how many times an operation is retried before the item is moved to the “Error” category in the KS monitor.

File Paths for KS EventPaks, Reports, Scripts and Other Objects

In addition to log file paths, several other KPI Monitoring file paths can be updated through Application Settings:

In the “Portal” Tab:

• Epak File Path: Where Eventpak files are built on the server before being downloaded to the client machine.
• Reports File Path: Where generated reports (Crystal & SSRS) are saved on the server.
• Scripts Path: Where Visual Basic script files are stored on the server.

In the “Engine” tab:

• Attachments Path: Where an event’s file attachments are generated / stored on the server before they are attached to emails or webcasts.
• Email Response Attachments Path: If KS is configured to monitor incoming email messages, this location is where received email attachments are saved on the server.
• Service Installed Path: This an information value only; it Indicates the path on the server where the KS Service is installed.

Automated Cleanup

The “Automated Cleanup” tab (within application settings) is used to schedule a job that removes the history of “completed” events from KPI Monitoring. The options are:
Scheduled Time:  The time of day (in AM/PM format) when this job runs. The default is 1:03 AM.
Keep Records for (Days):  The number of days of completed event history data to be retained in the KS database.
Schedule This Task: Whether the automated cleanup job is active. Un-checking this option means that the cleanup job will not run.

Please note that there is no option to do an ad-hoc submission of the automated cleanup job. However, “Schedule This Task” setting can be temporarily checked on to enable a single run of the job, after which the setting can be unchecked.

Linked Servers

KPI Monitoring can monitor information in a database via .NET database Provider, OLE/DB, ODBC, and REST API web service.

For some non-SQL databases, you’ll find it best to create a “link” between the target database and SQL Server. This is called a “linked server” and it optimizes retrieval and analysis for non-SQL databases that do not have a strong native database driver. A linked server has the following benefits:

• It reduces the amount of time to retrieve data.
• It enables calculations not supported by the database’s native driver.
• It creates single-field unique “keys” for each database table.

The process of using a linked server for a database is as follows:

1. You create a 64-bit ODBC source that points at your target database.
2. You use KPI Monitoring to create a linked Microsoft SQL Server database.
3. You connect KPI Monitoring to the linked database using the SQL database Provider.

Create a Linked Server

After you have created a 64-bit ODBC source that points at your target database, the next step is to create the Linked Server using the ODBC connection you created. Note that the linked server and database get created on the same SQL Server where KPI Monitoring’s database tables reside.

1. From the KS “Admin” option, select “Linked Servers”
2. Click on the “Add” button.
3. Enter a name for the linked database.
4. Select the ODBC source that points at your target database. Note that the list button for this field does not display the available 64-bit sources; you must manually type in the name of the 64-bit source.
5. Click on the “Create Linked Server” button.
6. Once you receive the message that the linked server has been created, click on the “Tables” tab within the Linked Server option. You’ll see a list of all the tables in the target database.

Although you can select specific tables for the linked server, we recommend checking the box titled “Link Checked Tables” to select ALL tables.

If your target database has multiple “entities” (e.g., companies), go to the field titled “Create an optional change tracking column” and type in the entity/company code of your first entity. (You’ll need to create one linked server per entity.)

Click on the “Link” button at the top of this window. Any tables that are not able to be linked will be detailed in the box at the bottom of the Linked Servers option.