Creating, Managing, and Reviewing Notifications

In the Console, you can set up Notification Rules, which allow you to define a rule set that controls when a Notification is triggered with reference to an Event:

  • Event. Specify the system Event that the Notification will be sent for - for example, a Prepayment/Commitment created Event.

  • Calculation. Include a calculation that references the Event's fields. This allows you to define precisely the conditions that must be satisfied for the Notification to be triggered and sent when the specified Event occurs. For example, a Notification that will be sent only when a Prepayment created Event occurs and the Prepayment amount is equal to or greater that $5,000.

  • Always fire notification. If you want a Notification to be triggered simply by the Event occurring and with no further conditions having to be met, you can use a switch to implement this use case. No calculation is then required for the Notification Rule.

  • Active/Inactive. Switch the Notification on and off for the referenced Event.

Note: Notifications for Scheduled Events? As well as setting up Notifications for system-generated Events, you can also set up Notifications on the basis of any Scheduled Events you've created for your Organization. See Working with Scheduled Events for more details.

When you've created Notification Rules for Events, you can link them to Destinations you've created for integrations to complete your setup and create Notification Integration Configurations.

Important! Understanding a Notification Integration Configuration: When you link a Notification Rule you've configured for a system Event to an integration Destination, you create a Notification Integration Configuration. In m3ter, this can be understood as a special case of an Integration Configuration, one where the integration Destination is restricted to a webhook. This contrasts with the more commonly understood case, where the integration - for example, an outbound Bill Integration Configuration - is used for sending billing data for end-customer Accounts from m3ter to a 3rd-party invoicing system as Destination. For more details, see Creating and Managing Integration Configurations.

When you have completed the full setting up to create a Notification Integration Configuration, a Notification will be sent to a Destination if:

  • You have enabled the Notification Rule linked to the Destination to be active.

  • The system Event the Notification Rule references occurs.

  • Any calculation you've built into the Notification Rule is evaluated as true at the time the Event occurs.

After setting up your Notification Rules and enabled them as active in your production environment, any Events that cause Notifications to be triggered in accordance with those Rules are logged and recorded. You can then review and inspect these Notification Events as part of your routine operations.

This topic explains how to create a Notification Rule and link it to a Destination. How to view and manage your Notification Rules is also explained:

How to review the Events that have triggered Notifications according to your Notification Rules is explained:

Lastly, an example Notification payload is given in the last section:

Working with Notifications? Before you attempt to create and configure Notification Rules, we strongly recommend that you first review the previous topics in this section, which explain in detail the Events and Notifications framework and gives object definitions. See Key Concepts and Relationships and Object Definitions and API Calls.

Creating Notification Rules

To create a Notification Rule:

1. In the main Console navigation menu, select Notifications. The Notifications page opens and lists any existing Notification rules.

Warning! Note that if you've already set up Notification Rules with reference to any Events and these Events have triggered Notifications, the Events will be listed when you first open the Notifications page. In this case, select View all and the page adjusts to allow you to create a new Notification Rule.

2. Select Create Notification Rule. The Create page opens.

3. Enter a Name and Code.

  • Note that when you enter a Name and click in the Code field, a default code is entered based on the name you've entered, which you can then edit as required.

4. Enter a Description for the Notification Rule.

5. Use the Event drop-down list to select the Event you want to create the Notification Rule for. Note that this field is searchable - simply start to type in the name of the Event and the list will be filtered automatically as you type:

Tip: Scheduled Events? If you've created any custom Scheduled Events for your Organization, these will also be available for selection in the Event drop-down list.

6. If you want a Notification to be triggered simply by the selected Event occurring and with no further conditions having to be met, enable the Always fire notification switch. No calculation is then required for the Notification Rule and this part of the Create form will be disabled.

7. Use the Active switch to enable the Notification Rule for the selected Event. Default is disabled.

8. In the Calculation edit box, enter the calculation that defines the condition you want to apply for the Notification Rule to be triggered when the selected Event occurs:

  • Note that you must ensure you reference fields that are valid for the Event. For details on how to obtain the fields available for different Event types, see Event Fields.

  • For more details on creating calculations for Notification Rules, see Creating Calculations.

Tip: Add Calculation later? You can omit a calculation when you first create a Notification Rule and edit the rule later to add the required calculation.

9. When you've entered a calculation, in the Rule Calculation panel, select Test Calculation. The calculation is evaluated for correctness with respect to:

  • The fields you've referenced are valid ones for the selected Event type.

  • The syntax, functions, and operators you've used are valid for the m3ter calculation engine - see Creating Calculations.

10. Check the result of the calculation evaluation:

  • If the calculation is valid, Calculation passed will show True.

  • If the calculation is invalid, Calculation passed will show False:

In this example:

  • The Notification Rule is set to be Active.

  • Because we want to apply conditions for the Rule, we leave the Always fire notification switch in the default off position.

  • A calculation is used that references the new.amount field for a configuration.commitment.created Event.

  • The calculation has been tested and evaluated as True.

Tip: Can't Create or Update Notification Rule? If you enter an invalid calculation and the Test Calculation returns False, then the Create or Update buttons will be grayed out and disabled.

11. Select Create Notification Rule. The Notification Rule Details page opens:

You can now link the Notification Rule to a Destination to complete the setup - see the next section for details.

Linking Notification Rules to Destinations to Create Notification Integration Configurations

To complete your setup for a Notification, you can link a Notification Rule to a Destination you've created for integrations - see Creating and Managing Destinations for more details:

  • Note that only webhook Destinations can be created for integrations, but you can link your Notification Rules to these.

  • When you link a Notification Rule to an integration Destination, this creates a Notification Integration Configuration, which will then be listed under Integrations>Configurations in the Console.

  • If an Event of the type specified in a Notification Rule occurs and any conditions you've defined using the calculation in the Rule are satisfied, then the Notification is triggered and sent to the webhook Destination you've linked it to.

To link a Notification Rule to a Destination:

1. In the main Console navigation menu, select Notifications. The Notifications page opens and lists any existing Notification rules.

  • Note that if you have already set up Notification Rules with reference to any Events and these Events have triggered Notifications, the Events will be listed when you first open the Notifications page. In this case, select View all and the page adjusts to allow you to link a Notification Rule to a Destination.

2. Select the NAME hotlink text of the Notification Rule you want to link to an integration Destination. The Notification Rule Details page opens.

3. On the Destinations panel, select Link destination. A Select destinations dialog appears, which lists the integration Destinations created for your Organization.

4. Select the checkboxes for the Destinations you want to link the Notification Rule to and then select Confirm. The dialog closes and on the Destinations panel the selected Destinations are listed:

In this example:

  • A single Destination has been linked to a Notification Rule.

  • You can read off the details of the Destination.

  • If you have not yet created the Destination you want to link the Notification Rule to, you can select Create Destination. This takes you directly to the Create page where you can create a new integration Destination - see Creating and Managing Destinations.

5. If you want to review the Destination details, select the NAME hotlink text. The Destination details page open:

If you navigate to Integrations>Configurations, the new Notification Integration Configuration is listed:

You can then select the ENTITY TYPE hotlink text to open the Integration Details:

  • Note that the Entity ID here is the ID of the Notification Rule used to create the Notification Integration Configuration.

Tip: Reviewing and Managing Integration Configurations? See Creating and Managing Integration Configurations.

Tip: Review Integration Run Details for a Notification? For detail on how to do this, see Reviewing Notification Integration Runs.

Managing Notification Rules

To manage Notification Rules:

1. In the main Console navigation menu, select Notifications. The Notifications page opens and lists any existing Notification rules.

  • Note that if you have already set up Notification Rules with reference to any Events and these Events have triggered Notifications, the Events will be listed when you first open the Notifications page. In this case, select View all and the page adjusts to allow you to manage your Notification Rules.

2. If you want to make any editing changes to a Notification, select Edit:

3. Make your changes, and select Update.

4. If you want to view details of the Notification, select the NAME hotlink text. The Notification Rules Details page opens.

5. If you want to delete a Notification Rule, select Delete:

A confirmation dialog appears.

6. Select Yes to confirm the deletion.

Reviewing Events for Notifications

When you have created and configured Notifications Rules for system Events and enabled them as active in your production environment, you can review any Events that have triggered Notifications.

To review Notifications:

1. In the main Console navigation menu, select Notifications. The Notifications page opens and lists any Events that have caused a Notification to be triggered and sent:

In this example, two Events have triggered Notifications and the number of Notifications triggered by each Event is given under TRIGGERED EVENT COUNT, together with a LAST SEEN timestamp.

2. To review the Notification Rule that caused an Event to trigger a Notification, select the EVENT NAME hotlink text. The page adjusts to show the Notification Rule:

In this example, we've selected the configuration.commitment.created Event.

3. Select the NAME hotlink text of the Notification Rule. The Notification Rule Details page for the Rule opens and the Latest Events panel lists recent Events which triggered Notifications according to the Notification Rule:

Example Notification Payload

The following is an example of the payload sent on a webhook when a Notification is triggered. The example is for a Notification triggered by a billing.bill.updated Event:

1
{
2
"id": "758ecbcf-a9b3-4e01-bc78-c2a123aaac5c",
3
"eventName": "billing.bill.updated",
4
"eventTime": "2023-03-29T09:15:03.278Z",
5
"m3terEvent": {
6
"eventData": {
7
"calculation": "true",
8
"eventId": "f8962895-e08a-4da9-815b-1dd379095afe",
9
"notificationConfigurationId": "3f83afae-2479-4031-85f5-5dc929542d62",
10
"accountId": "75ac56d6-68d4-4975-9ea4-8638272b27e2",
11
"name": "Bill Update",
12
"eventName": "billing.bill.updated",
13
"description": "Testing billing notification",
14
"eventType": "Notification",
15
"id": "758ecbcf-a9b3-4e01-bc78-c2a123aaac5c",
16
"orgId": "e185ba31-428a-4ea8-9b13-aec98a287c85",
17
"notificationCode": "billing_notification"
18
},
19
"eventTime": "2023-03-29T09:15:03.278Z",
20
"eventName": "billing.bill.updated"
21
}
22
}
23

Next: Example - Notification Setup for Commitment Updated Event



Additional Support

Login to the Support portal for additional help and to send questions to our Support team.