Ac-support-connector NPM

AC Support Connector

This module sends unified support payloads to SQS. A dedicated service (not part of the connector) then processes those SQS messages and delivers the support messages to different channels (e.g. Teams, a helpdesk, etc)

Breaking changes

Version 1

platforms array is now required
channels are no longer supported, use platforms instead
use "text" for simple messages and "message" array for complex messages
level, service, project, etc are types in the message array (see example below)
messages with payload > 256kB will throw an exception (instead of truncating)

Prerequisites

Create a SQS queue (e.g. supportQueue) and use a policy that allows all (or selected) IAM users from the account to send messages to the queue:

{
      "Sid": "Statement1",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNTID:root"
      },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:eu-central-1:ACCOUNTID:supportQueue"
    }

The function itself uses the default AWS profile on the machine or a set profile. You can set the profile using export profile=PROFILE_NAME.

Usage

// Init during bootstrap

const supportConnector = require('ac-support-connector')

await supportConnector.init({
  serviceName: 'my-service',
  instanceId: 'abc123' // optional unique identifier (for the instance the service is running on)
  sqsQueue: 'mySupportList' // optional SQS queue name, if none set, defaults to 'supportQueue'
})

// now send logs like this

// SIMPLE MESSAGE
await supportConnector.createMessage({ 
  platforms: ['jsm']
  subject: 'Operation failed',
  text: 'The operation ABC failed due to missing parameter',
})

// COMPLEX MESSAGE
await supportConnector.createMessage({ 
  platform: ['jsm', 'teams'],
  subject: 'Operation failed',
  reporter: 'jane.doe@admiralcloud.com',
  message: [{
    type: 'text',
    content: 'The operation ABC failed due to missing parameter'
  }, {
    type: 'level,
    content: 'warn'
  }, {
    type: 'service',
    content: 'my-service'
  }, {
    type: 'instanceId',
    content: 'abc123'
  }, {
    type: 'project',
    content: 'playground-channel'
  }]
})

NOTE: If instanceId and service are set during init, they will be automatically added to message payload.

Parameters

Init

Parameter	Type	Usage
serviceName	string	Name of the service sending the support ticket
region	string OPTIONAL	AWS region
instanceId	string OPTIONAL	Unique identifier, if service runs on multiple machines
sqsQueue	string OPTIONAL	Name of AWS SQS queue. If not send, defaults to 'supportQueue'

Create Message

Parameter	Type	Usage
subject	string	Subject of the message
text	string	Text of the message
message	array	Array of objects with properties types and content*
block	integer	Seconds before the message is sent again (if the error occurs again). If Redis is not available, memory is used.

There is no limit to types in message array. Some of them have an effect when using ac-lambda-supportEventProcessor. Only type "text" must exist. Every type can be multiple times in the array.

Using message as array can help to "layout" your message, e.g. in Teams as nice message card.