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
• sss represents alpha numeric
• fff represents java syntax: http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

Outbound Instruction Type

Outbound Instruction Type - Login (L)

Must be the first instruction sent from the application after connecting to the relay. It is used to establish identity and confirm a proper login.

Required fields supplied by application

I: A universally unique string identifying the process. Multiple runs of the same application should have the same ID (I). If an application were to be shut down and restarted, the ID (I) should not change.

Optional parameters supplied by application

Optional parameters are used to provide metrics about the application.

PL: Used to supply a fully qualified java class name to an AMI relay plugin. The class must implement the com.vortex.agent.AmiPlugin interface

O: Used to supply options about the current session. The following options are available and can be used in conjunction by comma delimiting:

• QUIET - AMI will not send any information back to the client (statuses, etc). Note execute commands (E) will still be send to the client
• LOG - Force AMI relay  to log data to / from this session (default file = AmiSession.log)
• UNIX - Force AMI to not send \r on messages
• WINDOWS - Force AMI to send \r on messages
• TTY - teletype terminal (for UNIX) is for interactively working with AMI backend

Example

In the below example, we see the optional attributes APP, MEM and STAT are supplied to shed light on the application name, memory used and status. Note that string values are surrounded in quotes. The options are forcing ami to use UNIX formatting (no \r) and force logging at the ami relay.

L|I="12n3f321g19"|APP="SOR"|MEM=12000|STAT="OKAY"|O="UNIX,LOG"

Outbound Instruction Type - Status (S)

Used to update or add metrics about the application.

Optional parameters supplied by application

Optional parameters are used to provide metrics about the status.

Example

In the below example, notice not all metrics need be supplied for a particular status update. Note that a new metric (MSG) was added in the 3rd instruction and the environment status was deleted in the 2nd.

S#1@1374353639915|MEM=13000|env="Prod"

S#2@1374353639925|MEM=15500|STAT="BAD"|env=null

S#3@1374353639955|STAT="OKAY"|MSG="Back to normal" 

Outbound Instruction Type - Object (O)

Used to create facts about an object.

Required fields supplied by application

T: Object type for grouping objects

Optional parameters supplied by application

I: A unique string ID for the object used for updating the object later. Subsequent messages with the same object ID (I) and same running process ID (I) provided in the login (L) will cause an update.

E: Expires on; negative for how far into the future from the time of message receipt in AMI center and positive numbers are exact dates in the future based on Epoch time. Units are milliseconds

A: Associated alert ID (DEPRECATED)

Example

In the below example, an "Order" object is created. This object has some custom parameters (|qty=1223|filled=13222|status="OverFill") and a lifespan of 100 seconds (E=-100000L).

O|I="Order1374"|T="Order"|qty=1223|filled=13222|status="OverFill"|E=-100000L

Outbound Instruction Type - Command Definition (C)

Used to create a command that will allow the user to right click on an application or object, and perform a command it.

Required fields supplied by application

I: Command ID

N: Name that is displayed to user in the right-click context menu. Note: Use periods (.) to create submenus

Example

N="order.cancel": will place the cancel command under the order menu

Optional parameters supplied by application

L: Permissions Level of 0 means remove command, and any other number is used for entitlements as part of the AMI entitlement engine.

A: Configuration for input form described in JSON format. See appendix for JSON Form layout

W: An expression that will determine which rows the command will be available at a row/node level.  You may also reference user-specific variables:

• user.username - login name of user that is executing the command
• user.xxxxx - a property, associated with the user's entitlements that are prefixed w/ amivar_.

Example

If the user has an attribute in the entitlements server "amivar_group=sales" then the variable user.group will have the value sales

T: An expression that will determine which rows the command will be available at a panel level.  You may also reference user-specific variables and panel specific variables:

• user.username - login name of user that is executing the command
• user.xxxxx - (see W clause for details)
• panel.title -The title name of the panel
• panel.types - A comma (,) delimited list of types (T) shown in the panel
• panel.visualization - The type of visualization. Visualizations include: table, form, treemap, chart, chart_3d
• panel.id - The ID of the panel (shown above the panel configuration button). To edit the panel ID, open the panel's Settings menu

H: Help, gets displayed in the top of the display box.

P: Priority for display in the menu. Commands with a higher priority are listed in the context menu above those with lower priority, 0 = highest priority, 1 = 2^nd highest, etc.

E: Enabled where (expression)

Example

E="Quantity==300"; the command will only be enabled where the Quantity = 300

F: Fields; returns the values of specified fields.

Example

Using a command with the following parameter: F="Price" will return:

E@1414512334864|C="Test"|I="8vJfyRmzkir7EwkQIpnnrA"|U"david"|V="[{"O":"23","Price":70.0},{"O":"24","Price":95.0},{"O":"25","Price":60.0},{"O":"26","Price":50.0}]"J

M: Multiple; constrains the number of rows that can be selected when running the command. The syntax is n-m where n is min and m is max. If m is not supplied than there is no upper limit.

Example

• "0" = available when no records are selected.
• "1" = available only when a single record is selected (default).
• "0-1" = available when no records or a single record is selected.
• "1-" = available when one or more records are selected.
• "3-5" = available when 3, 4, or 5 records are selected.

S: Style of the menu item in JSON

Example

s='{"separator":"TOP|BOTTOM|BOTH"}' will add a separator between the commands

C: Declare what Condition(s) will cause command to be evaluated, comma (,) delimited list. Options include:

• "now" = Immediately (when the command is declared)
• "now" = Immediately (when the command is declared)
• "user_click" = when the user clicks on a row (this is the default)
• "user_close_layout" = when the user closes a layout
• "user_open_layout" = when the user opens a layout (or logs in w/ a default layout assigned)

Example

C='now,user_open_layout' will cause the command to be run on all current sessions and any new sessions that are created.

X: Execute AmiScript when the command is evaluated and the various criteria are met. See AmiScript User Guide for details

Example

In the below example, a command is created to allow a user to bust all orders for an app and a single order. With the bst2 command the user must supply a comment.

C|I="bst"|N="Bust Every Order"|H="this is used to bust all orders"|L=2|W'T=="__CONNECTION"'

C|I="bst2"|N="Bust This Order"|H="this is used to bust an order"|L=1|T='panel.types=="Orders" || panel.types=="Executions"'|W='qty>0 && user.canbust=="true"'| A='{"form":{"inputs":[{"label": "Comment","var":

Outbound Instruction Type - Response to Execute Command (R)

Respond to a request by the relay to execute a command. Please see section on "Inbound Instruction type - Execute Command (E)" as these work in conjunction.

Required fields supplied by application

I: An ID uniquely identifying the command as sent from the relay's execute command (E). This ID is generated by AMI and the application must use this ID when sending a response.

S: The status of the command. 0 = Okay, 1 = Close dialog box, 2 = Leave dialog box open, 3 = Close dialog box and modify data

M (optional): A string message to send to source that requested command be run

X (optional): Execute AmiScript on the user session that requested command be run. See AmiScript User Guide for details

Example

The below example is a potential response to the sample in the execute command example found in the "Inbound Instruction type - Execute Command (E)" section.

R#13@1374353639915|M="Order missing: OR-11323"|I="ad5462sf55"|S=2

The following example is a potential response to a command on an object where the quantity=300 and must be changed to 200:

R|I="2yXxPizK5oi02hp7jpgZJ5"|S=3|Quantity=200|M="Quantity Modified"

Outbound Instruction Type - Delete an Object (D)

This is a simple command for deleting objects that have not expired.

Required fields supplied by application

I: A unique string ID for the object. Each new object must have a unique object ID (I) for scope of the running process ID (I). For deleting an object, the same object ID (I) must be supplied.

T: To delete an object, the object type must be supplied.

Example

In the below example, an "order" object is deleted:

D|I="ad5462sf55"|T="order"="order"

Outbound Instruction Type - Exit (X)

Notify the relay of a clean shutdown. The relay will close the socket after receiving this message.

Optional parameters supplied by application

Optional parameters are used to provide metrics about the application at time of shutdown.

Example

In the below example, notice not all metrics need be supplied for a particular status update.

X#1@1374353639915|STAT="GOODBYE"