You can specify users in your ServiceNow instance who will receive email notifications about errors and other events within the DataSync application, including errors with the DataSync Agent. To configure notifications within your Perspectium solution, navigate to PerspectiumControl and Configuration > TroubleshootingError Notification.

Perspectium notifications are created as ServiceNow email notifications in order to send emails natively through the instance and some notifications use notification email scripts for the email's subject and body content. See email notifications and notification email scripts for more information.

(info) NOTE: Since these notifications use built-in ServiceNow functionality, you are able to view and change the notifications and their content from the default behavior. However this is only recommended for advanced users as changes may cause the notifications to not function properly. 

The following notifications are included with the Perspectium Core app:

NameDescription
Perspectium ErrorNotification when there is an error in the Perspectium Logs. When the DataSync application encounters an issue and logs an error, you can use this notification to be notified . An example of an email created is as follows:

Subject: Perspectium Error: perspectium - psp.out.replicator.queue_name 

Body:

The following error has occurred:

Instance: perspectium

Name: psp.out.replicator.queue_name

Value: 2020-10-28 20:08:26: Error getting metrics for queue psp.out.replicator.testqueue on https://<server>.perspectium.net/ 

Perspectium Agent Error 

Notification when the DataSync Agent encounters errors processing records. A psp_error_script notification email script is included with a formatted email to display issues with the Agent.

The Agent will send back batches of errors and this notification will create an email that contains a list of records that resulted in errors, including the table the record belongs to, the record sys_id and the Agent's error message. 

(info) NOTEThis feature will NOT work if the Agent has <skip_report/> configured as the feature is dependent on the Agent sending back errors as part of its reporting capabilities. Using <skip_report/> will disable the Agent's reporting capabilities.

You can control the error messages sent back by the DataSync Agent to your instance using the <error_batch_size> and <receipt_send_interval> configurations, as error messages are sent back when the batch size or the send interval has been reached, whichever comes first. For example, if the <error_batch_size> is 10 and the <receipt_send_interval> is 5, then an error message will be sent back when there are 10 errors or 5 minutes have passed, whichever occurs first. Meshlets currently will send errors based on the batch they process each time i.e. if a batch of records has 3 errors, those 3 errors will be sent back in one error message.

An example of an email created when errors occurred processing records is as follows:

Subject: Perspectium Agent (psp_test_agent) Errors

Body:

Dear DataSync Agent user,

Errors have occurred in the Agent when attempting to process the following records:


Table: incident, Record: 72c645032f431010744b90bcf699b67c

Error: SubscribeException: Invalid sys_id


Table: incident, Record: 72c645032f431010744b90bcf699b67d

Error: SubscribeException: Invalid sys_id


With Iodine 7.0.8+ of the DataSync Agent and Iodine 7.0.5+ of Perspectium Core for ServiceNow, the Agent will also send back notifications of other issues the Agent encounters on startup as well.

These issues include:

  • Not being able to validate the Agent's configurations on start up (such as bad database credentials or ServiceNow instance credentials)
  • Not meeting the minimum requirements to start up the Agent
  • When the server the Agent is running on has 10% of the disk space minimum requirements left (for example if the minimum requirements is 100GB and the server now has only 10GB left). This is the scenario where the Agent started with enough disk space to meet its minimum requirements but after running for some time, the disk space has gone down to a critical level and is meant as a warning before the Agent is unable to run at all because of no disk space left.

(info) NOTE: Notifications on these additional issues require the Agent to have a valid <message_connection> in order to publish error messages back to MBS and that your Perspectium Core app is configured to read from its default queue (psp.out.servicenow.<instance_name>) on the same MBS. This would be generally be set up by default when you install the Perspectium Core app and configure both the Agent and the Perspectium Core app on your ServiceNow instance. 

Example emails created when the Agent encounters errors include:

Subject: Perspectium Agent (psp_test_agent) Errors

Body:

Dear DataSync Agent user,

Errors have occurred in the Agent:

Agent does not meet minimum requirements for starting. Check Agent logs for more information.



Subject: Perspectium Agent (psp_test_agent) Errors

Body:

Dear DataSync Agent user,

Errors have occurred in the Agent:

SQLException: Cannot create PoolableConnectionFactory (Could not create connection to database server. Attempted reconnect 3 times. Giving up.) java.sql.SQLException: Cannot create PoolableConnectionFactory (Could not create connection to database server. Attempted reconnect 3 times. Giving up.)



Subject: Perspectium Agent (psp_test_agent) Errors

Body:

Dear DataSync Agent user,

Errors have occurred in the Agent:

Agent had errors in validating agent.xml configurations on start up. Check Agent logs for more information.


Perspectium Meshlet Error

Notification when the DataSync Meshlet encounters errors processing records. A psp_error_script notification email script is included with a formatted email to display issues with the Meshlet.

Meshlets will send back batches of errors and this notification will create an email that contains a list of records that resulted in errors, including the table the record belongs to, the record sys_id and the Meshlet's error message. Meshlets currently will send errors based on the batch they process each time i.e. if a batch of records has 3 errors, those 3 errors will be sent back in one error message.

An example of an email created when errors occurred processing records is as follows:

Subject: Perspectium Meshlet (psp_meshlet) Errors

Body:

Dear Meshlet user,

Errors have occurred in the Meshlet when attempting to process the following records:


Table: incident, Record: 72c645032f431010744b90bcf699b67c

Error: DataSyncListenerService: Record not found


Table: incident, Record: 72c645032f431010744b90bcf699b67d

Error: DataSyncListenerService: Record not found


Perspectium Connection Error

Notification when the DataSync app has connection issues with the Perspectium Integration Mesh. That is, when the application attempts to connect to the Mesh to post messages being shared and if applicable, when it tries to fetch messages being subscribed.. See below for configuration options (batching and interval) related to this notification. 

An example of an email created for this notification is as follows:

Subject: Perspectium Connection Error

Body:

Errors connecting to the Perspectium Integration Mesh:

PerspectiumReplicator.fetchFromQueue:Error fetching from queue psp.out.servicenow.instance_name on https://<instance_name>.perspectium.net/: Connection refused.

See Perspectium Logs on instance dev00000 for more information.

Perspectium Table Compare Discrepancies

Notification when Table Compare executes and there are discrepancies between the instance and the database the Agent is saving records into. The psp_table_compare_script notification email script is included with a formatted email to display these discrepancies.

Each time a Table Compare is executed and there are discrepancies found, this notification will create an email that details the discrepancies. 

An example of an email created is as follows:

Subject: Perspectium Table Compare Discrepancies

Body:

Discrepancies found in the DataSync Agent database:


Table Compare e84d1fd6db80641024df4870399619aa found discrepancies. There were 1 missing records and 0 additional records. Missing records will be reshared and additional records will be removed.

Perspectium Situation

Notification when a situation has occurred multiple times. The default value of is specified in the Conditions field of the When to send tab of the notification:

The following templates are included:

NameDescription
Perspectium Old Message AlertSituation when there is a message in a ready state in the outbound table that is "old" (created greater than 10 minutes ago by default) and has not been sent. This is generally due to the scheduled job not sending messages to the Integration Mesh because the job is not running properly or has issues connecting.
Perspectium Queue Monitoring AlertSituation when running queue monitoring. This includes alerts you set up as well as errors getting queue information from the Integration Mesh.

These templates are situations that will occur multiple time and cause a notification. For example, once there are 6 Perspectium Old Message Alert situations that occur, the notification will then be sent if you subscribe to this notification. An example of an email created for this notification is as follows:

Subject: Perspectium Situation Triggered: Perspectium Old Message Alert 

Body:

Situation: messages that have been sitting in a outbound for more than the specified time


Subscribe to a notification


To subscribe to a Perspectium notificaton and receive emails when an event occurs, follow these steps:

Enable email sending

Navigate to System Mailboxes > Administration > Email Properties. In the upper left-hand corner of the form, check the Yes | No box under Email sending enabled to allow emails to be sent from your ServiceNow instance.

Select the notification to subscribe to

Navigate to PerspectiumControl and Configuration > TroubleshootingError Notification and open the notification you want to subscribe to.

Choose users who will receive error notification emails

Click the Who will receive tab. Then, click >  or next to Users to start adding users who will receive the notification emails.

(info) NOTEThe users that you specify to receive email notifications for must have an email entered in the Email field of their User Profile (Username Profile).

Save your notification changes

In the bottom left-hand corner of the form, click Submit or Update to save your changes for users to start receiving email notifications.


Perspectium Connection Error configuration options


To avoid temporary short term connection issues (i.e. there was a single connection issue and the app was able to connect on the next attempt to share data to the Mesh), you can configure how frequently the Perspectium Connection Error notification should check for issues and how many times the issues occur before sending a notification.

To configure this notification, follow these steps:

Set your notification batch size and timing

Navigate to Perspectium > Control and Configuration > Properties > General Settings. Scroll to the section labeled Send notification emails in batches of. In the box underneath this label, type a number to indicate the minimum number (batch) of connection errors before sending a notification. Next, scroll to the section labeled Send notification emails about connection errors in batches every and choose a time interval to send batched notifications in. This interval controls how often the application should check for connection issues. The default values are batches of 5 and every 30 minutes to trigger a notification.

For example, with the default batch size of 5 and an interval of 30 minutes, every 30 minutes the app will check if there are more than 5 connection issues and if so, send a notification.

Finally, click Save at the bottom of the page to save your Perspectium properties. Once these two properties are setup, your notifications will be emailed in batches at the specified intervals to the users you configured in Step #3.