Difference between revisions of "Realtime Messaging API"
Tag: visualeditor-switched |
Tag: visualeditor |
||
| Line 141: | Line 141: | ||
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. | 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''' | + | === '''Required fields supplied by application''' === |
| − | |||
<span style="font-family: courier new; color: red;">I</span>: 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 (<span style="font-family: courier new; color: red;">I</span>) should not change. | <span style="font-family: courier new; color: red;">I</span>: 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 (<span style="font-family: courier new; color: red;">I</span>) should not change. | ||
| − | '''Optional parameters supplied by application''' | + | === '''Optional parameters supplied by application''' === |
| − | |||
Optional parameters are used to provide metrics about the application. | Optional parameters are used to provide metrics about the application. | ||
| Line 167: | Line 165: | ||
Used to update or add metrics about the application. | Used to update or add metrics about the application. | ||
| − | '''Optional parameters supplied by application''' | + | === '''Optional parameters supplied by application''' === |
| − | |||
Optional parameters are used to provide metrics about the status. | Optional parameters are used to provide metrics about the status. | ||
| Line 183: | Line 180: | ||
Used to create facts about an object. | Used to create facts about an object. | ||
| − | '''Required fields supplied by application''' | + | === '''Required fields supplied by application''' === |
| − | |||
<span style="font-family: courier new; color: red;">T</span>: Object type for grouping objects | <span style="font-family: courier new; color: red;">T</span>: Object type for grouping objects | ||
| − | '''Optional parameters supplied by application''' | + | === '''Optional parameters supplied by application''' === |
| − | |||
<span style="font-family: courier new; color: red;">I</span>: A unique string ID for the object used for updating the object later. Subsequent messages with the same object ID (<span style="font-family: courier new; color: red;">I</span>) and same running process ID (<span style="font-family: courier new; color: red;">I</span>) provided in the login (<span style="font-family: courier new; color: red;">L</span>) will cause an update. | <span style="font-family: courier new; color: red;">I</span>: A unique string ID for the object used for updating the object later. Subsequent messages with the same object ID (<span style="font-family: courier new; color: red;">I</span>) and same running process ID (<span style="font-family: courier new; color: red;">I</span>) provided in the login (<span style="font-family: courier new; color: red;">L</span>) will cause an update. | ||
| Line 203: | Line 198: | ||
Used to create a command that will allow the user to right click on an application or object, and perform a command it. | 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''' | + | === '''Required fields supplied by application''' === |
| − | |||
<span style="font-family: courier new; color: red;">I</span>: Command ID | <span style="font-family: courier new; color: red;">I</span>: Command ID | ||
<span style="font-family: courier new; color: red;">N</span>: Name that is displayed to user in the right-click context menu. Note: Use periods (.) to create submenus | <span style="font-family: courier new; color: red;">N</span>: Name that is displayed to user in the right-click context menu. Note: Use periods (.) to create submenus | ||
| − | '''Example''' | + | === '''Example''' === |
| + | <span style="font-family: courier new; ">N="order.cancel"</span>: will place the ''cancel'' command under the ''order'' menu | ||
| + | |||
| + | [[File:RTAPI.Name.jpg]] | ||
| − | + | === '''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'' '''[[Description of AMI JSON Form definition fields.htm|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, select the '''Edit Panel ID''' option from the panel menu. | ||
Revision as of 14:00, 17 March 2021
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, select the Edit Panel ID option from the panel menu.