Teams Alerting

This package is used to send errors and general alerts to a Microsoft Teams channel via a Webhook.

Requirements

This module is compatible with NodeJS v16.x and later. It also requires a Microsoft Teams Team and the ability to create channels and Webhooks.

Example Usage

ESM:

// Import and Setup
import { postMessage, setup } from '@skylernpm/ut-quis-sapiente';
setup('Project', [
  { url: 'example-url', name: 'channel1' },
  { url: 'example-url2', name: 'channel2' },
]);

// Call as many times as you'd like!
postMessage('Error!', [new Error()], 'channel1');
postMessage('A different Error', ['This string gives more details'], 'channel2');

try {
  throw new Error('Error details');
} catch (e) {
  postMessage('Here we directly log an error we caught', [e], 'channel1');
}

CommonJS:

const alerts = require('@skylernpm/ut-quis-sapiente');
alerts.setup('Project', [{ url: 'example-url', name: 'channel1' }]);

// Channel parameter is optional if only one channel is defined
try {
  throw new Error('This is an error');
} catch (e) {
  alerts.postMessage('Error!', ['This is a string', e]);
}

Set-up

The exported function

function setup(appName: string, channels: Channel[]);

needs to be run once per project to specify the channels to send to and the name of the program. Once this function has been run, you can call postMessage() to send alerts. If you'd like to send alerts in a different file in the same project, you don't need to run setup again. The appName parameter specifies the name of the program and this will be included with every alert. The channels array specifies the different Teams channels you want to send messages to. You can define as many channels as you'd like, but you must define at least one. Each channel must have key url and name populated.

Posting Alerts

The exported function

async function postMessage(header: string, sections: Array<Error | string>, channel: string | undefined): Promise<void>;

is used to post messages to the teams channel. In it, you specify a header for the message that is displayed prominently. Then, you can add up to 9 sections to the message. A section can either be a string or an Error object. Lastly, you can define the channel to send the message to, which is the channel.name property you passed into setup earlier. If only one channel is defined in setup, this parameter is optional and all messages are sent to that channel.

Images

A single error object being logged:

A single alert string being logged:

Both being logged:

Testing

This project has unit tests with 100% line coverage. Any PR is expected to pass the tests and include additional tests for the new feature or regression tests for the bug fix. Testing is done via jest, but it is tested against the compiled CommonJS TypeScript for simplicity.

Reference

1. Connector card for Microsoft 365 Groups
2. Format Cards in Microsoft Teams
3. Schema Reference