Signal Messages
A Signal message is sent by reporters into Syntinel to generate an alert to one or more channels.
Class Diagram
JSON Schmea
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "reporterId" ],
"properties": {
"name": { "type": "string" },
"description": { "type": "string" },
"maxReplies": { "type": "integer" },
"reporterId": { "type": "string" },
"routerId": { "type": "string" },
"routerType": { "type": "string" },
"template": { "type": "string" },
"arguments": { "type": "object" },
"cues": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": { "type": "string" },
"template": { "type": "string" },
"arguments": { "type": "object" },
"description": { "type": "string" },
"resolver": {
"type": "object",
"required": [ "name" ],
"properties": {
"name": { "type": "string" },
"config": { "type": "object"},
"notify": { "type": "boolean"}
}
},
"inputs": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "type"],
"properties": {
"name": { "type": "string" },
"description": { "type": "string" },
"type": { "type": "string" , "pattern": "^number|text|boolean|choice|multichoice|button|link$"},
"defaultValue": { "type": "string" },
"values": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
}
},
"actions": {
"type": "array",
"items": {
"type": "object",
"required": ["type"],
"properties": {
"name": { "type": "string" },
"id": { "type": "string" },
"description": { "type": "string" },
"type": { "type": "string" , "pattern": "^number|text|boolean|choice|multichoice|button|link$"},
"defaultValue": { "type": "string" },
"values": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
},
"defaultAction": { "type": "string" }
}
}
},
"defaultCue": { "type": "string" },
"defaultCueTimeout": { "type": "integer" },
"includeId": { "type": "boolean" }
}
}
Field Descriptions
Signal
| Field | Type | Required | Description |
|---|---|---|---|
| reporterId | String | Yes | The unique Id registered with Syntinel for this reporter. It helps determine message destination(s). |
| routerId | String | No | Id to use when searching the custom routing table for alternative message destinations. |
| routerType | String | Conditional | Required if RouterId provided. The qualifier for what type of id was passed in. |
| name | String | No | The name of the signal message. Usually displayed in the "header" of the message. |
| description | String | No | A description of the signal message. Usually displayed in the "header" of the message. |
| maxReplies | Integer | No | (Not Yet Implemented) The maximum number of valid replies allowed for this signal message. |
| cues | Dictionary of CueOption | No | A list of possible replies to the signal message. These are usually displayed in their own sections after the message "header". |
| defaultCue | String | No | (Not Yet Implemented)The key value of the cue option to take by default. |
| defaultCueTimeout | Integer | No | (Not Yet Implemented)The amount of time (in seconds) to wait before executing the defaultCue. |
| includeId | Boolean | No | Flag to indicate whether the SignalId should be included in the display of the message. (Default Value = true) |
| template | String | No | The Template Id to be used for this Signal. (TemplateType = Signal) |
| arguments | Dictionary of Objects | No | The arguments to be passed into the template for completing the Signal. |
CueOption
| Field | Type | Required | Description |
|---|---|---|---|
| <key> | String | Yes | A unique identifier for this instance of a cue option. It is the key value of the dictionary object. |
| name | String | No | A name to identify the particular cue option. This value is usually displayed in the title of the message section for this cue. |
| description | String | No | A description for this particular cue option. This value is usually displayed in the title of the message section for this cue. |
| resolver | Resolver | No | The resolver to be called when action is taken on this Cue. |
| inputs | List of SignalVariable | No | (Not Yet Implemented)A list of items to display in the message which don't necessarily trigger an action, but provide additional input on the action taken. |
| actions | List of SignalVariable | No | A list of possible actions that can be taken on a Cue. |
| defaultAction | String | No | (Not Yet Implemented)The default action to take when this cue is selected and no action has been specified. |
| template | String | No | The Template Id to be used for this Cue. (TemplateType = CueOption) |
| arguments | Dictionary of Objects | No | The arguments to be passed into the template for completing the Cue. |
Resolver
| Field | Type | Required | Description |
|---|---|---|---|
| name | String | Yes | The name of the resolver to call. |
| config | Object | No | Config parameters to be passed into the resolver. This can be any valid JSON object, as long as it can be serialized. |
| notify | Boolean | No | Flag to indicate that status notifications should be sent back to the original channels that received the Signal message. (*Default Value = false) |
SignalVariable
| Field | Type | Required | Description |
|---|---|---|---|
| name | String | No | The name for the input or action that is to be displayed. |
| id | String | No | An id for this action. This will be returned with the value selected by the subscriber. (Default Value = "action") |
| description | String | No | A description for the input or action that is to be displayed. |
| type | Choice of VariableType | Yes | The type of action or input object to display. |
| defaultValue | String | Maybe | The default value for this action or input. Depending on the "type" field, this may be a required value. |
| values | Dictionary of String | Maybe | Possible values for the action or input. Depending on the "type" field, this may be a required value. |
VariableType
Enumeration of Variable Types
- number (Not Yet Implemented)
- text (Not Yet Implemented)
- boolean (Not Yet Implemented)
- choice
- multichoice (Not Yet Implemented)
- button
- link (Not Yet Implemented)
Examples
Sample Signal Message
A sample ec2 utilization monitor that sends alerts when an instance has been up for more than 7 days, and allows the subscriber to take action against the ec2 instance directly from the Signal message.
The logic for actually interacting with the ec2 instance would be in the lambda function "my-lambda-function" resolver.
{
"name": "Utilization",
"description": "EC2 Utilization Montior",
"maxReplies": 1,
"reporterId": "_default",
"routerId": "MyId",
"routerType": "MyIdType",
"cues": {
"ec2Usage": {
"name": "EC2 Usage",
"description": "Server [i-888888888888] has been running for 7 days. Would you like to take action against it?",
"resolver": {
"name": "AWSLambda",
"config": {
"name": "my-lambda-function",
"region": "us-east-1"
}
},
"actions": [
{
"name": "Perform Action",
"id": "ec2-action",
"description": "Choose action to take against EC2 instances.",
"type": "choice",
"values": {
"stop": "Stop Instance",
"terminate": "Terminate Instance",
"reboot": "Reboot Instance",
"hibernate": "Stop and Hibernate Instance"
},
"defaultValue": "stop"
},
{
"name": "Ignore Alert",
"id": "signal-action",
"description": "Ignore this alert.",
"type": "button",
"defaultValue": "ignore"
},
{
"name": "Disable Alert",
"id": "signal-action",
"description": "Disable this alert.",
"type": "button",
"defaultValue": "disable"
}
],
"defaultAction": "ec2-action"
}
},
"defaultCue": "ec2Usage",
"defaultCueTimeout": 4320,
"includeId": true
}
Result In Teams :
Result In Slack :
Sample Signal Using A Signal Template
Same as the "Sample Signal Message" above, except the entire Signal message (except for required fields like reporterId) is stored as a template.
Signal :
{
"reporterId": "_default",
"template": "ec2-utilization",
"arguments": {
"instance": "i-8675309JENNY",
"notify": false
}
}````
Template Record:
````json
{
"_id": "ec2-utilization",
"_type": "Signal",
"parameters": {
"instance": [
{
"path": "cues.ec2.description",
"replace": "INSTANCE_ID"
},
{
"path": "cues.ec2.resolver.config.instances[0]"
}
],
"notify": [
{
"path": "cues.ec2.resolver.notify"
}
]
},
"template": {
"name": "Utilization",
"description": "EC2 Utilization Montior",
"includeId": true,
"maxReplies": 1,
"cues": {
"ec2": {
"actions": [
{
"defaultValue": "stop",
"description": "Choose action to take against EC2 instances.",
"id": "ec2-action",
"name": "Perform Action",
"type": "choice",
"values": {
"hibernate": "Stop and Hibernate Instance",
"reboot": "Reboot Instance",
"stop": "Stop Instance",
"terminate": "Terminate Instance"
}
},
{
"defaultValue": "ignore",
"description": "Ignore this alert.",
"id": "signal-action",
"name": "Ignore Alert",
"type": "button"
},
{
"defaultValue": "disable",
"description": "Disable this alert.",
"id": "signal-action",
"name": "Disable Alert",
"type": "button"
}
],
"defaultAction": "ec2-action",
"description": "Server [INSTANCE_ID] has been running for 7 days. Would you like to take action against it?",
"inputs": [
{
"defaultValue": "Default Comment Value Here",
"description": "Choose action to take against EC2 instances.",
"id": "comment",
"name": "Enter Comment",
"type": "text"
}
],
"name": "EC2 Usage",
"resolver": {
"config": {
"instances": [
"i-888888888888"
]
},
"name": "Echo",
"notify": true
}
}
},
"defaultCue": "ec2",
"defaultCueTimeout": 4320
}
}
Result In Teams :
Result In Slack :
Sample Signal Using A Cue Template
Same as the "Sample Signal Message" above, but only the Cue portion of the messages is being stored as a template. This is used when you want to build a portion of a message to be used across multiple Signal messages (or templates).
Signal :
{
"name": "Utilization",
"description": "EC2 Utilization Montior",
"maxReplies": 1,
"reporterId": "_default",
"includeId": true,
"cues": {
"ec2Usage": {
"template": "ec2Usage",
"arguments": {
"instance": "i-8675309JENNY",
"notify": true
}
}
},
"defaultCue": "ec2Usage",
"defaultCueTimeout": 4320
}
Template Record:
{
"_id": "ec2Usage",
"_type": "CueOption",
"parameters": {
"instance": [
{
"path": "description",
"replace": "INSTANCE_ID"
},
{
"path": "resolver.config.instances[0]"
}
],
"notify": [
{
"path": "resolver.notify"
}
]
},
"template": {
"actions": [
{
"defaultValue": "stop",
"description": "Indicates action to take against EC2 instances.",
"name": "Choose Action",
"id": "ec2-action",
"type": "choice",
"values": {
"hibernate": "Stop and Hibernate Instance",
"reboot": "Reboot Instance",
"stop": "Stop Instance",
"terminate": "Terminate Instance"
}
},
{
"defaultValue": "ignore",
"description": "Ingore this alert.",
"id": "signal-action",
"name": "Ignore Alert",
"type": "button"
},
{
"defaultValue": "disable",
"description": "Disable this alert.",
"id": "signal-action",
"name": "Disable Alert",
"type": "button"
}
],
"defaultAction": "signal-action",
"description": "Server [INSTANCE_ID] has been running for 7 days. Would you like to take action against it?",
"name": "EC2 Active",
"resolver": {
"name": "AWSLambda",
"config": {
"name": "my-lambda-function",
"region": "us-east-1"
}
}
}
}
Result In Teams :
Result In Slack :
Simple Alert
Sends a simple notification to the channels, displaying a main message and 2 "sub-messages". There are no actions to be taken on this Signal message.
{
"name": "Main Name",
"description": "Main Description",
"reporterId": "_default",
"cues": {
"cue1": {
"name": "Cue Name",
"description": "Cue Description"
},
"cue2": {
"name": "Cue2 Name",
"description": "Cue2 Description"
}
}
}
Result In Teams :
Result In Slack :
