Realtime Messaging API

AMI Backend Interface

Goal

The 3Forge Application Monitoring Interface (AMI) provides applications with a simple mechanism for connecting to the 3Forge Relay. 3Forge AMI's consolidated GUI lets users:

• View the application's health statistics
• Receive and manage objects though a simple workflow procedure
• Interact with applications to call routines inside the application

Conventions

• This document is written from the perspective of the application. "Outbound" is the application sending data, and "inbound" is the Application receiving data.
• All key words are in a "courier" font.
• Trailing text is indicated with an ellipses or "...".
• Special ASCII chars are qualified inside parenthesis.
• Brackets "[]" indicate optionally supplied data.
• Examples are in blue.

Overview

This interface is an extension of the 3Forge AMI product. Applications interact with AMI through the relays only, and not the central server nor the front end servers. Each AMI relay, upon startup, establishes a server socket on a well-known configurable port. As each application starts up, it should connect to the server socket of the relay running on its local host. Multiple applications can connect to one relay.

Applications then interact with the relay by sending and receiving "instructions." Instructions are well-defined, atomic, sequential and transactional messages. The first instruction an application sends after connecting must be a login (L) instruction. Following that, applications can send instructions arbitrarily and should listen for incoming instructions. Optionally, applications can send a logout (X) message to initiate a graceful shutdown.

Instruction Format

This protocol is designed to be flexible, compact and human readable. Each instruction must have a type and may contain a sequence number and timestamp. The general format for each message is: TYPE[#SEQNUM][@NOW][|PARAMS...]\n

TYPE: The type of message. Please see following sections for details on each type.

Valid outbound types are:

• L (login)
• S (status)
• S (alert) DEPRECATED
• O (object)
• C (command definition)
• R (response to execute command)
• D (delete objects)
• X (exit)
• H (help)
• P (pause)
• D (delete objects)

Valid inbound types are:

• M (status message)
• E (execute command)

SEQNUM: (optional) The sequence number of the instruction. If supplied, the first instruction (Login) must have a sequence number of 0, the following message must have a sequence number of 1, and so on. This sequence number will be used when AMI is ack-ing.

NOW: (optional) Current time in milliseconds since the UNIX epoch. This will aid AMI in determining if there is a lag.

PARAMS: (optional) Should be in the format key=value|key2=value|... where entries are pipe (|) delimited and keys are unique.

Notes:

• Backslashes (\), quotes ("), single quotes ('), (\n,\r,\t,\f,\b)  must be escaped via backslash (\).
• Unicode within strings must be expressed in 4 digit hex notation such as: \uFFFF
• Keys must be alphanumeric.
• All 1 and 2 letter fully upper case keys are reserved.
• Values that are not numeric must be surrounded in quotes.
• \n: Each instruction must end with a linefeed (0x0A) or linefeed + carriage (0x0A0x0D).
• The Syntax determines the parameter type, please note some types have multiple syntaxes:

Type	Syntax	Example	Notes
Integer	nnn	-234	Whole numbers default to integer
Long	nnnL	234L
Double	nnn.nnnD	123.123D	Decimal if optional
Float	nnnF	123F	Decimals in a number default to float
	nnn.nnn	123.123	Decimals default to float
String	"sss"	"what"	Quotes must be escaped with a backslash (\)
Enum	'sss'	'this'	Quotes must be escaped with a backslash (\)
UTC	nnnT	1422059533454T	Unix epoch
	"sss"T(fff)	"20140503"T(yyyyMMdd)	Uses date format (fff) to parse string (sss) to a utc
JSON	"sss"J	"{this:\"that\"}J	Base 64 UU Encoded
Binary	"ssss"U	"12fs1323"U	Base UUEncoded
Boolean	true false	true	Case sensitive
Null	null	Null

• nnn represents 0-9. Numbers must be base 10 and can be signed