m3terDocs

On this page

Key Concepts and Relationships

This topic sets out the Events and Notifications framework and introduces the main configuration objects and their role.

Relationship Diagram

The following diagram shows the key concepts and their relationships in the Events and Notifications framework:

You can exploit this framework to quickly set up Notifications based on system Events. The following sections explain the role of the essential configuration components and how they are designed to work together.

Events and Event Types

There are several key points to note regarding Events and Event Types:

  • Events are tokens of Event Types. Any Notifications you set up act on actual Events.

  • Events are system generated. For example, when a new Prepayment/Commitment is created for an Account.

  • Events Types are available for main configuration and billing entities. For each entity three Event Types are available - when the entity is created, updated, or deleted.

  • Each Event Type offers a number of fields. This gives you wide-ranging flexibility when you set up the conditions on which a Notification will be triggered by the Event.

  • Real-time processing. Events are evaluated in real-time.

  • Evolving schemas. The Events system doesn’t statically hold schemas, they are dynamically updated assuming forward compatibility is kept.

Event Types are available for each of the following m3ter configuration entities. Three events are associated with each entity - whenever one of them is created, deleted, or updated:

  • Commitment

  • Account

  • Aggregation

  • Compound Aggregation

  • Meter

  • Meter Group

  • Plan Template

  • Plan

  • Plan Group

  • Plan Group Link

  • Pricing

  • Pricing Band

  • Product

  • Account Plan

  • Organization

  • Organization Configuration

  • Custom Field

  • Contract

  • Credit Reason

  • Transaction Type

Event Types are available for each of the following m3ter billing entities. Three events are associated with each entity - whenever one of them is created, deleted, or updated:

  • Bill

  • Bill Config

  • Bill Job

  • Balance

  • Balance Amount

Notification Rule

A Notification Rule allows you to control when a Notification is triggered with reference to an Event. You can:

  • Include a calculation that references Event fields. This allows you to precisely define the conditions on which the Notification is triggered with respect to the Event. For example, send a Notification when a new Commitment is created for an Account and the commitment amount is equal to or greater than $5000. See the following Creating Calculations section for more details.

When you have created a Notification Rule, you can link it to an integration Destination to complete the Notification setup - see the following section.

Integration Destination and Credentials

To complete a Notification setup, you must link a Notification Rule to an integration Destination. This allows you to specify the endpoint the Notification will be sent to:

  • Currently, only webhooks can be designated as the Destination. Other Destination types are planned for the near future.

  • You can specify credentials to be used with the destination:

    • Currently, only the M3TER_SIGNED_REQUEST credential format is supported.

    • If the Destination does not require credentials, these can be set to some dummy value.

Tip: More Details on Integration Destinations? See Creating and Managing Destinations.

Creating Calculations

The calculations you use in your Notification Configuration can reference Event fields. This powerful capability sits at the heart of the Events and Notifications feature, giving you wide-ranging flexibility to define the precise conditions for sending Notifications:

  • A calculation is a formula that will be evaluated to a boolean.

  • If the calculation evaluates to true, a Notification instance for this Event is created and is sent to the configured destination.

  • You can reference numeric, string, and boolean Event fields in a calculation.

  • The fields you can use in a calculation are those returned in the response to the List Events API call:

  • The syntax and available operators for creating calculations are the same as those that apply to Meter Derived Field calculations in m3ter. The key difference is that Notification calculations evaluate to a boolean, not to a string or number. For more details see Derived Fields - Examples and Syntax.

  • Note that in addition to the operators, variables, and functions listed as available for Derived Field calculation, for Notification calculations you can also use:

    • Operators

      • Logical AND

      • Logical OR

      • Boolean comparisons

        • ==

        • >=

        • <=

    • Variables

      • null

    • Functions

      • isnull()

Example Calculations

  • Only trigger the Notification for a single Account:

    • new.accountId == "df41d216-XXXX-470f-YYYY-79b16059a96f"

  • Trigger a Notification when the Amount Spent field (on a commitment) has exceeded 90%:

    • (new.amountSpent >= ((new.amount*100)/90)) AND ((old.amountSpent <= ((old.amount*100)/90)) OR (old.amountSpent == null))

    • Note that this has a check against the “old” value to ensure there is only 1 notification when crossing the 90% threshold.

Next: Object Definitions and API Calls