How to Configure Planning Analytics Event Notification

You can get notifications for threads that are in a run state, threads in a wait state, database (instance) shutdowns, and more. For more information, see Set system resource thresholds and alerts in the Planning Analytics Workspace documentation.

To get event notifications from Planning Analytics Administration for Planning Analytics Local, follow the steps below.

1. Update the bootstrap.properties file with your email server settings.

2. Optional: Set SMTP_EMAIL_START_TLS_ENABLE=true and add the certificates to the TLS certificate store.

3. Set TM1 Server and Instance Level Notifications.

Step 1: Update the bootstrap.properties file

Collect your mail server settings from your system administrator and input them into the bootstrap.properties file located at

C:\Program Files\ibm\cognos\tm1_64\paa_agent\wlp\usr\servers\kate-agent

Navigate to the kate-agent folder;

C:\Program Files\ibm\cognos\tm1_64\paa_agent\wlp\usr\servers\kate-agent

Open the bootstrap.properties file with Notepad ++ and add your email server setting using the examples below.

SMTP_EMAIL_PORT=587

SMTP_EMAIL_AUTH=true  (if true, Username and Password are required below)

SMTP_EMAIL_HOST=example.com

SMTP_EMAIL_USERNAME=user@example.com

SMTP_EMAIL_PASSWORD=Analytics123

PAA_EMAIL_ADDRESS=noreply@example.com (this is the “from” email address)

SMTP_EMAIL_START_TLS_ENABLE=true

Step 2: Set SMTP_EMAIL_START_TLS_ENABLE=true and add the certificates to the TLS certificate store (Optional)

Default for SMTP_EMAIL_START_TLS_ENABLE is false. (SMTP_EMAIL_START_TLS_ENABLE=false)

Whether you need to configure certificates and set START_TLS_ENABLE=true depends on your email server configuration.

If you are using SMTP_EMAIL_START_TLS_ENABLE=true, you need to download two mail server certificates and import them into the PA certificate store.

Install OpenSSL

https://slproweb.com/products/Win32OpenSSL.html

Select the latest OpenSSL 'Light' version and click on the MSI to download and install, use all default values during the install.

Open Command Prompt, run as Administrator.

Execute this command, change example.com to your mail server.

openssl s_client -showcerts -starttls smtp -crlf -connect example.com:587

This command prints two certificates that begin with "-----BEGIN CERTIFICATE-----" and end with "-----END CERTIFICATE-----".

Scroll back up and copy the first BEGIN CERTIFICATE through END CERTIFICATE.

Paste into Notepad and save as {emailDomain}-1.cer and place in the C:\Program Files\ibm\cognos\tm1_64\paa_agent\wlp\usr\servers\kate-agent\resources\security directory

Do the same for the next BEGIN CERTIFICATE and END CERTIFICATE and copy.

Paste into Notepad and save as {emailDomain}-2.cer and place in the C:\Program Files\ibm\cognos\tm1_64\paa_agent\wlp\usr\servers\kate-agent\resources\security directory

Below, both files saved in the directory

Import Certs

Change directory to C:\Program Files\ibm\tm1_64\jre\bin

Run this command to import the first cert, replacing your .cer file name and your alias

keytool.exe -importcert -keystore "C:/Program Files/ibm/cognos/tm1_64/paa_agent/wlp/usr/servers/kate-agent/resources/security/server_store.p12" -storetype PKCS12 -trustcacerts -storepass applix -file "C:/Program Files/ibm/cognos/tm1_64/paa_agent/wlp/usr/servers/kate-agent/resources/security/email-smtp.us-east-1.amazonaws.com-1.cer" -alias email-smtp.us-east-1.amazonaws.com-1

Answer Y to trust the certificate.

Run this command to import the second cert:

keytool.exe -importcert -keystore "C:/Program Files/ibm/cognos/tm1_64/paa_agent/wlp/usr/servers/kate-agent/resources/security/server_store.p12" -storetype PKCS12 -trustcacerts -storepass applix -file "C:/Program Files/ibm/cognos/tm1_64/paa_agent/wlp/usr/servers/kate-agent/resources/security/email-smtp.us-east-1.amazonaws.com-2.cer" -alias email-smtp.us-east-1.amazonaws.com-2

Answer Y to trust the certificate.

Go to Windows Services and restart the IBM Planning Analytics Administration Agent service to pick up the changes.

Step 3 - Set TM1 Server and Instance Level Notifications

Set server level notifications

You can configure threshold settings that define system resource status by multiple metrics. You can also configure alerts to send notification to yourself and other users when any of the system resources reaches a critical state.

When you set threshold limits for the server, you define the parameters for the safe, concern, and critical states of these system resource metrics:

• Memory

• CPU

• Disk

These states are displayed on the Planning Analytics Monitoring dashboard. A green square indicates a resource in a safe state. A yellow square indicates a resource in a warning state. A red square indicates a resource in a critical state.

Current states of Memory, CPU and Disk usage are displayed in the Administration screen.

In the above example, Memory is at a critical state, CPU is safe and Disk is at a Warning state.

Note that you will receive an email only when a system resource reaches the Critical threshold.

For Planning Analytics Administration on Cloud, threshold and alert settings apply to your entire environment.

For Planning Analytics Administration Local, you must configure threshold and alert settings for every server and TM1 instance in your environment.

You can test by setting thresholds lower than actual usage to get an email notification.

Steps

Open the Planning Analytics Monitoring dashboard.

In Workspace click on the Administration card.

The Planning Analytics Monitoring dashboard.

Click the icon next to the system resources on the Planning Analytics Monitoring dashboard.

For each system resource, set the Warning threshold and Critical threshold.

When resource usage falls below the Warning threshold, the resource is in a safe state. When resource usage is at or above the Warning threshold, but below the Critical threshold, the resource is in a Warning state. When resource usage is at or above the Critical threshold, the resource is in a critical state.

You can set thresholds for the following system resources:

Memory usage

Measures system memory usage in GBs.

Default Warning threshold - 70 percent of installed system memory, expressed in GBs.

Default Critical threshold - 80 percent of installed system memory, expressed in GBs.

CPU usage

Measures CPU usage as a percentage of total CPU capacity on the system.

Default Warning threshold - 70

Default Critical threshold - 80

Disk usage

Measures disk usage as a percentage of all system disk storage. The default Concern at range for Disk Usage is 65 to 85.

Default Warning threshold - 65

Default Critical threshold – 85

If you want to be alerted by email when a resource reaches a critical state:

a) Select the Alert at critical condition option for the resource.

b) Enter the email addresses of the users to receive notification in the Notify email ID(s) box. When typing, you can separate addresses with a comma, space, tab, or enter. You can also paste a comma-delimited list of email addresses in this box.

Enter the email address here.

For Planning Analytics Administration on Cloud, notification emails are sent from administration@planning-analytics.ibmcloud.com.

For Planning Analytics Administration Local, notification emails are sent from the mail address specified by the PAA_EMAIL_ADDRESS property in the bootstrap.properties file for a given agent. The default value for this property is administration@planning-analytics.ibmcloud.com, but you can modify it to use an email address that is more relevant for your environment. See Install and configure the Planning Analytics Administration agent (local only) for details on the bootstrap.properties file.

c) Click Apply.

You can click Restore at any time to restore the default threshold and alert settings. Note that Restore also removes any email addresses from the Notify email ID(s) box.

Set Database (Instance) Level Notifications

Set threshold levels to get notifications for each TM1 instance on the server. You can get notifications for chore failures, threads that are in a run state, threads in a wait state, and more.

Steps

Open the Planning Analytics Monitoring dashboard.

In Workspace click on the Administration card.

The Planning Analytics Monitoring dashboard.

At the instance level, database health in indicated in two places within the Planning Analytics Monitoring dashboard. Under Databases, in the first screen showing each TM1 instance (above), the instance card’s top border will be green if all resources are safe and will be yellow if any resource is in a warning state and will be red if any resource is in a critical state.

Click on the instance card to see all resource states for the instance.

More health indicators appear in resources view.

To set the instance thresholds, click on the gear icon.

Click on Thresholds and alerts. For every condition you want to be notified, check the Alert at critical condition box and set the Warning and Critical threshold amounts.

Memory usage - measures database memory usage in GBs.

CPU usage - measures database CPU usage as a percentage of total CPU capacity on the system.

For the following database metrics, set the Critical threshold. When the metric value is at or above the Critical threshold, the database is in a critical state. Otherwise, the database is in a safe state.

Max thread wait time - measures the amount of time a thread waits to run, expressed in seconds.

Thread in run state - measures the duration of a thread in a run state, expressed in minutes.

Database unresponsive - measures the duration of a database in an unresponsive state, expressed in seconds.

Enter the email addresses of the users to receive notification in the Notify email ID(s) box. When typing, you can separate addresses with a comma, space, tab, or enter. You can also paste a comma-delimited list of email addresses into this box.

Enter the email address here.

When finished click Apply.

You can click Restore at any time to restore the default threshold and alert settings. Note that Restore also removes any email addresses from the Notify email ID(s) box.

For Planning Analytics Administration Local, notification emails are sent from the mail address specified by the PAA_EMAIL_ADDRESS property in the bootstrap.properties file for a given agent.

Conclusion

Follow the steps above to ensure responsible individuals can be notified of server and TM1 instance health issues. Setting these alerts will inform you of potential problems before they become a serious issue. This could help prevent potential system down time as you can fix issues before they become an issue. You should receive less calls from your users as you will likely know something is going on in your environment before they will.

Next Steps

We hope you found this article informative. Be sure to subscribe to our newsletter for data and analytics news, updates, and insights delivered directly to your inbox.

If you have any questions or would like PMsquare to provide guidance and support for your analytics solution, contact us today.