Notify - Microsoft Teams

Microsoft Teams provides a mechanism for exposing its channels to a remote system via webhooks.

The most important thing to gather from the teams channel webhook set-up is the "WebHook URL".

System configuration

No configuration is required for Teams integration; you simply need to know the WebHook URL, which is used in database entries outlined in the section below.

Teams configuration

Teams must be configured in your notify.kts file. Here is an example configuration with connection details.

notify {
    gateways {
        teams("teams") {
            url = "https://some-teams-server-somewhere"
        }
	}
    
    // optionally include additional connections, including Microsoft Teams connections
}

Database configuration

NOTIFY_ROUTE

You need at least one NOTIFY_ROUTE entry set up to point to the GATEWAY record, so that NOTIFY records are routed as messages.

Field Name	Usage
ENTITY_ID	N/A
ENTITY_ID_TYPE	Always `GATEWAY`
GATEWAY_ID	This should match GATEWAY_ID in the corresponding GATEWAY record
NOTIFY_ROUTE_ID	This will be auto generated if left blank; best practice is to give it a unique value with respect to other records
TOPIC_MATCH	This can be anything, NOTIFY records target this via the TOPIC field, and messages are routed to all gateways with a matching TOPIC_MATCH value. In a simple/typical set-up, Genesis makes it match the GATEWAY_ID in the corresponding GATEWAY record

Here is an example NOTIFY_ROUTE entry:

==================================
NOTIFY_ROUTE
==================================
Field Name                               Value                                    Type
===========================================================================================
TIMESTAMP                                2022-03-16 08:47:59.968(n:0,s:3572)      NANO_TIMESTAMP
ENTITY_ID                                                                         STRING
ENTITY_ID_TYPE                           GATEWAY                                  ENUM[USER_NAME PROFILE_NAME GATEWAY]
GATEWAY_ID                               TestAlerts                               STRING
NOTIFY_ROUTE_ID                          000000000000001NRLO1                     STRING
TOPIC_MATCH                              TestAlerts                               STRING
-------------------------------------------------------------------------------------------

MS_TEAMS_NOTIFY_ROUTE_EXT

Field Name	Usage
URL	URL for the team webhook. Will default to the one configured on the gateway if not present.
NOTIFY_ROUTE_ID	Reference to a primary KEY in the NOTIFY_ROUTE table.

NOTIFY

Writing a record to this table, which correctly points to a TOPIC, will result in a message being sent to the Teams gateway.

Equally, EVENT_NOTIFY_INSERT can be used, as opposed to a direct table write (this is the encouraged form of interaction). This event allows for the same set of fields as the DbRecord. The input fields detailed below cater for either approach.

Field Name	Usage
APPLICATION_REF	N/A
BODY	The body of the message
DOCUMENT_ID	N/A
EXPIRY	N/A
HEADER	The first line of the message
NOTIFY_COMPRESSION_TYPE	N/A
NOTIFY_ID	Autogenerated Unique value
NOTIFY_SEVERITY	Severity of the alert. Value will be placed to right of header text in square brackets
SENDER	N/A
TOPIC	The TOPIC_MATCH value on the NOTIFY_ROUTE record you wish to target

Here is an example of using NOTIFY:

==================================
NOTIFY
==================================
Field Name                               Value                                    Type
===========================================================================================
TIMESTAMP                                2022-03-16 12:29:50.659(n:0,s:4063)      NANO_TIMESTAMP
APPLICATION_REF                                                                   STRING
BODY                                     This is my body                          STRING
DOCUMENT_ID                                                                       STRING
EXPIRY                                                                            DATETIME
HEADER                                   My Header                                STRING
NOTIFY_COMPRESSION_TYPE                                                           STRING
NOTIFY_ID                                000000000000001NTLO1                     STRING
NOTIFY_SEVERITY                          Information                              ENUM[Information Warning Serious Critical]
SENDER                                                                            STRING
TOPIC                                    TestAlerts                               STRING
-------------------------------------------------------------------------------------------

This example results in a Teams channel message, such as:

System configuration​

Teams configuration​

Database configuration​

NOTIFY_ROUTE​

MS_TEAMS_NOTIFY_ROUTE_EXT​

NOTIFY​