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: '[email protected]',
  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.

Links

• Website

License

Copyright 2009 - today, AdmiralCloud AG, Mark Poepping