Difference between revisions of "Realtime Messaging API"

From 3forge Documentation
Jump to navigation Jump to search
(Created blank page)
 
(Updated invalid param key for plugin and outdated interface package)
 
(74 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
= AMI Backend Interface =
  
 +
== Goal ==
 +
The 3Forge Application Management 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 "<span style="font-family: courier new; color: red;">courier</span>" font.
 +
* Trailing text is indicated with an ellipses or "...".
 +
* Special ASCII chars are qualified inside parenthesis.
 +
* Brackets "[]" indicate optionally supplied data.
 +
* Examples are in <span style="color: blue;">blue</span>.
 +
 +
== 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 (<span style="color: red;">L</span>) instruction. Following that, applications can send instructions arbitrarily and should listen for incoming instructions. Optionally, applications can send a logout (<span style="color: red;">X</span>) 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: '''<span style="font-family: courier new; ">TYPE[#SEQNUM][@NOW][|PARAMS...]\n</span>'''
 +
 +
TYPE: The type of message. Please see following sections for details on each type.
 +
 +
Valid ''outbound'' types are:
 +
 +
* <span style="font-family: courier new; color: red;">L</span> (login)
 +
* <span style="font-family: courier new; color: red;">S</span> (status)
 +
* <span style="font-family: courier new; color: red;">S</span> (alert) DEPRECATED
 +
* <span style="font-family: courier new; color: red;">O</span> (object)
 +
* <span style="font-family: courier new; color: red;">C</span> (command definition)
 +
* <span style="font-family: courier new; color: red;">R</span> (response to execute command)
 +
* <span style="font-family: courier new; color: red;">D</span> (delete objects)
 +
* <span style="font-family: courier new; color: red;">X</span> (exit)
 +
* <span style="font-family: courier new; color: red;">H</span> (help)
 +
* <span style="font-family: courier new; color: red;">P</span> (pause)
 +
* <span style="font-family: courier new; color: red;">D</span> (delete objects)
 +
 +
Valid ''inbound'' types are:
 +
 +
* <span style="font-family: courier new; color: red;">M</span> (status message)
 +
* <span style="font-family: courier new; color: red;">E</span> (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:
 +
 +
{| class="wikitable"
 +
!Type
 +
!Syntax
 +
!Example
 +
!Notes
 +
|-
 +
|Integer
 +
|''nnn''
 +
|<span style="color: blue;">-234</span>
 +
|Whole numbers default to integer
 +
|-
 +
|Long
 +
|''nnn''<span style="color: red;">L</span>
 +
|<span style="color: blue;">234L</span>
 +
|
 +
|-
 +
|Double
 +
|''nnn.nnn''<span style="color: red;">D</span>
 +
|<span style="color: blue;">123.123D</span>
 +
|Decimal if optional
 +
|-
 +
|Float
 +
|''nnn''F
 +
|<span style="color: blue;">123F</span>
 +
|Decimals in a number default to float
 +
|-
 +
|
 +
|''nnn.nnn''
 +
|<span style="color: blue;">123.123</span>
 +
|Decimals default to float
 +
|-
 +
|String
 +
|"''sss''"
 +
|<span style="color: blue;">"what"</span>
 +
|Quotes must be escaped with a backslash (\)
 +
|-
 +
|Enum
 +
|'<nowiki/>''sss''<nowiki/>'
 +
|<span style="color: blue;">'this'</span>
 +
|Quotes must be escaped with a backslash (\)
 +
|-
 +
|UTC
 +
|''nnn''T
 +
|<span style="color: blue;">1422059533454T</span>
 +
|Unix epoch
 +
|-
 +
|
 +
|"''sss''"<span style="color: red;">T</span>(''fff'')
 +
|<span style="color: blue;">"20140503"T(yyyyMMdd)</span>
 +
|Uses date format (fff) to parse string (sss) to a utc
 +
|-
 +
|JSON
 +
|"''sss''"<span style="color: red;">J</span>
 +
|<span style="color: blue;">"{this:\"that\"}J</span>
 +
|Base 64 UU Encoded
 +
|-
 +
|Binary
 +
|"''ssss''"<span style="color: red;">U</span>
 +
|<span style="color: blue;">"12fs1323"U</span>
 +
|Base UUEncoded
 +
|-
 +
|Boolean
 +
|<span style="color: red;">true false</span>
 +
|<span style="color: blue;">true</span>
 +
|Case sensitive
 +
|-
 +
|Null
 +
|null
 +
|<span style="color: blue;">Null</span>
 +
|
 +
|}
 +
*''nnn'' represents 0-9. Numbers must be base 10 and can be signed
 +
*''sss'' represents alpha numeric
 +
*''fff'' represents java syntax: '''<nowiki>http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html</nowiki>'''
 +
 +
= Outbound Instruction Type =
 +
 +
== Outbound Instruction Type - Login (<span style="font-family: courier new; color: red;">L</span>) ==
 +
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'''
 +
 +
<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 are used to provide metrics about the application.
 +
 +
<span style="font-family: courier new; color: red;">P</span>: Used to supply a fully qualified java class name to an AMI relay plugin. The class must implement the com.f1.ami.relay.AmiRelayPlugin interface.
 +
 +
<span style="font-family: courier new; color: red;">O</span>: Used to supply options about the current session. The following options are available and can be used in conjunction by comma delimiting:
 +
 +
* <span style="font-family: courier new; color: red;">QUIET</span> - AMI will not send any information back to the client (statuses, etc). Note execute commands (E) will still be send to the client
 +
* <span style="font-family: courier new; color: red;">LOG</span> - Force AMI relay  to log data to / from this session (default file = ''AmiSession.log'')
 +
* <span style="font-family: courier new; color: red;">UNIX</span> - Force AMI to not send \r on messages
 +
* <span style="font-family: courier new; color: red;">WINDOWS</span> - Force AMI to send \r on messages
 +
* <span style="font-family: courier new; color: red;">TTY</span> - 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.
 +
 +
<span style="font-family: courier new; color: red;">L</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="12n3f321g19"|APP="SOR"|MEM=12000|STAT="OKAY"|O="UNIX,LOG"</span>
 +
 +
== Outbound Instruction Type - Status (<span style="font-family: courier new; color: red;">S</span>) ==
 +
This has been deprecated
 +
 +
== Outbound Instruction Type - Object (<span style="font-family: courier new; color: red;">O</span>) ==
 +
Used to create an object (row) that gets inserted into AMI DB
 +
 +
'''Required fields supplied by application'''
 +
 +
<span style="font-family: courier new; color: red;">T</span>: Table name
 +
 +
'''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;">E</span>: 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
 +
 +
<span style="font-family: courier new; color: red;">A</span>: Associated alert ID (<span style="color: red;">DEPRECATED</span>)
 +
 +
'''Example'''
 +
 +
The below example inserts a record into the Order table. The key-value pair maps value to column, e.g. the first column is qty, and the value is 1223. The last column represents an AMI reserved column, E, that indicates the expiry time of this row.
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: red;">|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; ">="Order1374"|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; ">="Order"|qty=1223|filled=13222|status="OverFill"|E=-100000L</span>
 +
 +
== Outbound Instruction Type - Command Definition (<span style="font-family: courier new; color: red;">C</span>) ==
 +
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'''
 +
 +
<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
 +
 +
'''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'''
 +
 +
<span style="font-family: courier new; color: red;">L</span>: Permissions Level of 0 means remove command, and any other number is used for entitlements as part of the AMI entitlement engine.
 +
 +
<span style="font-family: courier new; color: red;">A</span>: Configuration for input form described in JSON format. ''See'' '''[[Description of AMI JSON Form definition fields.htm|appendix]]''' ''for JSON Form layout''
 +
 +
<span style="font-family: courier new; color: red;">W</span>: An expression that will determine which rows the command will be available at a row/node level.  You may also reference user-specific variables:
 +
 +
* <span style="font-family: courier new; color: red;">__USERNAME</span> - login name of user that is executing the command
 +
* <span style="font-family: courier new; color: red;">user.''xxxxx''</span> - a property, associated with the user's entitlements that are prefixed w/ amivar_.
 +
* To use legacy variables names such as <span style="font-family: courier new; color: red;">user.username</span>, set the following property: ami.web.support.legacy.amiscript.varnames=true
 +
'''Example'''
 +
 +
If the user has an attribute in the entitlements server "<span style="color: blue;">amivar_group=sales</span>" then the variable <span style="color: blue;">user.group</span> will have the value sales
 +
 +
<span style="font-family: courier new; color: red;">T</span>: 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:
 +
 +
* <span style="font-family: courier new; color: red;">__USERNAME</span> - login name of user that is executing the command
 +
* <span style="font-family: courier new; color: red;">user.</span>''<span style="font-family: courier new; color: blue;">xxxxx</span>'' - (''see'' '''W clause''' ''for details'')
 +
* <span style="font-family: courier new; color: red;">panel.title</span> -The title name of the panel
 +
* <span style="font-family: courier new; color: red;">panel.types</span> - A comma (,) delimited list of types (T) shown in the panel
 +
* <span style="font-family: courier new; color: red;">panel.visualization</span> - The type of visualization. Visualizations include: <span style="font-family: courier new; color: blue;">table, form, treemap, chart, chart_3d</span>
 +
* <span style="font-family: courier new; color: red;">panel.id</span> - The ID of the panel (shown above the panel configuration button). To edit the panel ID, open the panel's '''Settings''' menu
 +
<span style="font-family: courier new; color: red;">H</span>: Help, gets displayed in the top of the display box.
 +
 +
<span style="font-family: courier new; color: red;">P</span>: 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<sup>nd</sup> highest, etc.
 +
 +
<span style="font-family: courier new; color: red;">E</span>: Enabled where (expression)
 +
 +
'''Example'''
 +
 +
<span style="font-family: courier new; color: red;">E</span><span style="font-family: courier new; color: blue;">="Quantity==300"</span>; the command will only be enabled where the Quantity = 300
 +
 +
<span style="font-family: courier new; color: red;">F</span>: Fields; returns the values of specified fields.
 +
 +
'''Example'''
 +
 +
Using a command with the following parameter: <span style="font-family: courier new; color: red;">F</span><span style="font-family: courier new; color: blue;">="Price"</span> will return:
 +
 +
<span style="font-family: courier new; color: red;">E</span><span style="font-family: courier new; color: blue;">@1414512334864|</span><span style="font-family: courier new; color: red;">C</span><span style="font-family: courier new; color: blue;">="Test"|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="8vJfyRmzkir7EwkQIpnnrA"|</span><span style="font-family: courier new; color: red;">U</span><span style="font-family: courier new; color: blue;">"david"|</span><span style="font-family: courier new; color: red;">V</span><span style="font-family: courier new; color: blue;">="[{"O":"23","Price":70.0},{"O":"24","Price":95.0},{"O":"25","Price":60.0},{"O":"26","Price":50.0}]"J</span>
 +
 +
<span style="font-family: courier new; color: red;">M</span>: 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.
 +
 +
<span style="font-family: courier new; color: red;">S</span>: Style of the menu item in JSON
 +
 +
'''Example'''
 +
 +
<span style="font-family: courier new; ">s='{"separator":"TOP|BOTTOM|BOTH"}'</span> will add a separator between the commands
 +
 +
[[File:RTAPI.Multi.jpg]]
 +
 +
<span style="font-family: courier new; color: red;">C</span>: Declare what Condition(s) will cause command to be evaluated, comma (,) delimited list. Options include:
 +
 +
* "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'''
 +
 +
<span style="font-family: courier new; ">C='now,user_open_layout'</span> will cause the command to be run on all current sessions and any new sessions that are created.
 +
 +
<span style="font-family: courier new; color: red;">X</span>: Execute AmiScript when the command is evaluated and the various criteria are met. ''See'' '''AMI Script Doc''' in AMI Web under Help for details.
 +
 +
'''Example'''
 +
 +
<span style="font-family: courier new; color: red;">C</span><span style="font-family: courier new; color: blue;">|<span style="font-family: courier new; color: red;">I</span>="alert"|<span style="font-family: courier new; color: red;">X</span>='session.alert("hi");'|<span style="font-family: courier new; color: red;">C</span>="now"</span>
 +
 +
'''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.
 +
 +
<span style="font-family: courier new; color: red;">C</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="bst"|</span><span style="font-family: courier new; color: red;">N</span><span style="font-family: courier new; color: blue;">="Bust Every Order"|</span><span style="font-family: courier new; color: red;">H</span><span style="font-family: courier new; color: blue;">="this is used to bust all orders"|</span><span style="font-family: courier new; color: red;">L</span><span style="font-family: courier new; color: blue;">=2|</span><span style="font-family: courier new; color: red;">W</span><span style="font-family: courier new; color: blue;">='T=="__CONNECTION"'</span>
 +
 +
<span style="font-family: courier new; color: red;">C</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="bst2"|</span><span style="font-family: courier new; color: red;">N</span><span style="font-family: courier new; color: blue;">="Bust This Order"|</span><span style="font-family: courier new; color: red;">H</span><span style="font-family: courier new; color: blue;">="this is used to bust an order"|</span><span style="font-family: courier new; color: red;">L</span><span style="font-family: courier new; color: blue;">=1|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">='panel.types=="FEED:Orders" || panel.types=="FEED:Executions"'|<span style="font-family: courier new; color: red;">W</span>='qty>0 && user.canbust=="true"'|</span><span style="font-family: courier new; color: red;">A</span><span style="font-family: courier new; color: blue;">='{"form":{"inputs":[{"label": "Comment","var":
 +
"comment","required":true}]},"timeout":10000}'</span>
 +
 +
== Outbound Instruction Type - Response to Execute Command (<span style="font-family: courier new; color: red;">R</span>) ==
 +
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'''
 +
 +
<span style="font-family: courier new; color: red;">I</span>: 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.
 +
 +
<span style="font-family: courier new; color: red;">S</span>: The status of the command. 0 = Okay, 1 = Close dialog box, 2 = Leave dialog box open, 3 = Close dialog box and modify data
 +
 +
<span style="font-family: courier new; color: red;">M</span> (optional): A string message to send to source that requested command be run
 +
 +
<span style="font-family: courier new; color: red;">X</span> (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 (<span style="font-family: courier new; color: red;">E</span>)" section.
 +
 +
<span style="font-family: courier new; color: red;">R</span><span style="font-family: courier new; color: blue;">#13@1374353639915|</span><span style="font-family: courier new; color: red;">M</span><span style="font-family: courier new; color: blue;">="Order missing: OR-11323"|I="ad5462sf55"|</span><span style="font-family: courier new; color: red;">S</span><span style="font-family: courier new; color: blue;">=2</span>
 +
 +
The following example is a potential response to a command on an object where the quantity=300 and must be changed to 200:
 +
 +
<span style="font-family: courier new; color: red;">R</span><span style="font-family: courier new; color: blue;">|I="2yXxPizK5oi02hp7jpgZJ5"|</span><span style="font-family: courier new; color: red;">S</span><span style="font-family: courier new; color: blue;">=3|Quantity=200|</span><span style="font-family: courier new; color: red;">M</span><span style="font-family: courier new; color: blue;">="Quantity Modified"</span>
 +
 +
== Outbound Instruction Type - Delete an Object (<span style="font-family: courier new; color: red;">D</span>) ==
 +
This is a simple command for deleting objects that have not expired.
 +
 +
'''Required fields supplied by application'''
 +
 +
<span style="font-family: courier new; color: red;">I</span>: 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.
 +
 +
<span style="font-family: courier new; color: red;">T</span>: To delete an object, the object type must be supplied.
 +
 +
'''Example'''
 +
 +
In the below example, an "order" object is deleted:
 +
 +
<span style="font-family: courier new; color: red;">D</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="ad5462sf55"|</span><span style="font-family: courier new; color: red;">T</span>="order"</span>
 +
 +
== Outbound Instruction Type - Exit (<span style="font-family: courier new; color: red;">X</span>) ==
 +
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.
 +
 +
<span style="font-family: courier new; color: red;">X</span><span style="font-family: courier new; color: blue;">#1@1374353639915|STAT="GOODBYE"</span>
 +
 +
== Outbound Instruction Type - Pause (<span style="font-family: courier new; color: red;">P</span>) ==
 +
Used to create a pause in the connection for a specified period of time. This is used for testing scripts.
 +
 +
'''Required fields supplied by application'''
 +
 +
<span style="font-family: courier new; color: red;">D</span>: Delay
 +
 +
'''Example'''
 +
 +
This example pauses the application for 1 second:
 +
 +
<span style="font-family: courier new; color: red;">P</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">D</span><span style="font-family: courier new; color: blue;">=1000</span>
 +
 +
== Inbound Instruction Type - Status Message (<span style="font-family: courier new; color: red;">M</span>) ==
 +
For each outbound message, the relay will respond with a response instruction which will notify the application of the acceptance of rejection of the message. The message will contain the sequence number of the supplied outbound message. These messages will not contain a timestamp or a sequence number.
 +
 +
'''Parameters always supplied by relay'''
 +
 +
<span style="font-family: courier new; color: red;">S</span>: The status of the received instruction. A value of 0 indicates it was successfully processed by the relay; a value of 1 to 255 indicates an error.
 +
 +
<span style="font-family: courier new; color: red;">Q</span>: The sequence number of the instruction sent from the relay.
 +
 +
<span style="font-family: courier new; color: red;">M</span>: A human-readable message for the status.
 +
 +
'''Examples'''
 +
 +
In the following example, the login message was rejected due to a missing ID.
 +
 +
<span style="font-family: courier new; color: red;">M</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">Q</span><span style="font-family: courier new; color: blue;">=0|</span><span style="font-family: courier new; color: red;">S</span><span style="font-family: courier new; color: blue;">=1|</span><span style="font-family: courier new; color: red;">M</span><span style="font-family: courier new; color: blue;">="Missing required Fields: I"</span>
 +
 +
== Inbound Instruction Type - Execute Command (<span style="font-family: courier new; color: red;">E</span>) ==
 +
This will allow users to execute commands on the application. A timestamp and sequence number will always be included.
 +
 +
'''Parameters are always supplied by the relay'''
 +
 +
<span style="font-family: courier new; color: red;">I</span>: Unique ID as a string. This ID is generated by AMI
 +
 +
<span style="font-family: courier new; color: red;">C</span>: The ID of the command
 +
 +
<span style="font-family: courier new; color: red;">U</span>: User name of the person doing the command.
 +
 +
'''Parameters optionally supplied by relay'''
 +
 +
<span style="font-family: courier new; color: red;">O</span>: Associated object ID. This will be supplied if the command is executed on an object.
 +
 +
'''Examples'''
 +
In the following example we can see the user is running the command "cancel" with the arguments "OR-11323." The ID (I) of "f123f56a" will be unique for this process and should be included in the applications response.
 +
 +
<span style="font-family: courier new; color: red;">E</span><span style="font-family: courier new; color: blue;">#872@1374353639915|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="f123f56a"|</span><span style="font-family: courier new; color: red;">C</span><span style="font-family: courier new; color: blue;">="cancel OR-11323"|</span><span style="font-family: courier new; color: red;">U</span><span style="font-family: courier new; color: blue;">="JSmith"</span>
 +
 +
== Outbound Instruction Type - Alert (<span style="font-family: courier new; color: red;">A</span>) ==
 +
'''<<span style="color: red;">Deprecated but supported, use Object (O) instead</span>>'''
 +
 +
== Outbound Instruction Type - Help (<span style="font-family: courier new; color: red;">H</span>) ==
 +
Prints out general help
 +
 +
= Cheat Sheet =
 +
'''Valid outbound types ''and required parameters (<span style="color: green;">optional pre-defined parameters in green</span>)'''''
 +
 +
* <span style="font-family: courier new; color: red;">L</span> (login)
 +
** ''<span style="font-family: courier new; color: red;">I</span> (app ID)''
 +
** ''<span style="font-family: courier new; color: green;">O</span> <span style="color: green;">(session options)</span>''
 +
** ''<span style="font-family: courier new; color: green;">PL</span> <span style="color: green;">(plugin options)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">S</span> (status)
 +
* <span style="font-family: courier new; color: red;">A</span> (alert) <span style="color: red;">DEPRECATED</span>
 +
** ''<span style="font-family: courier new; color: red;">I</span> (alert ID)''
 +
** ''<span style="font-family: courier new; color: red;">L</span> (level)''
 +
** ''<span style="font-family: courier new; color: red;">T</span> (alert type)''
 +
** ''<span style="font-family: courier new; color: green;">E</span> <span style="color: green;">(expires on)</span>''
 +
** ''<span style="font-family: courier new; color: green;">U</span> <span style="color: green;">(user assignment)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">O</span> (object)
 +
** ''<span style="font-family: courier new; color: red;">I</span> (object ID)''
 +
** ''<span style="font-family: courier new; color: red;">T</span> (object Type)''
 +
** ''<span style="font-family: courier new; color: green;">E</span> <span style="color: green;">(expires on)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">C</span> (command definition)
 +
** ''<span style="font-family: courier new; color: red;">I</span> (command ID)''
 +
** ''<span style="font-family: courier new; color: green;">N</span> <span style="color: green;">(name)</span>''
 +
** ''<span style="font-family: courier new; color: green;">W</span> <span style="color: green;">(where - row level)</span>''
 +
** ''<span style="font-family: courier new; color: green;">T</span> <span style="color: green;">(where - panel level)</span>''
 +
** ''<span style="font-family: courier new; color: green;">L</span> <span style="color: green;">(permissions Level)</span>''
 +
** ''<span style="font-family: courier new; color: green;">A</span> <span style="color: green;">(form definition)</span>''
 +
** ''<span style="font-family: courier new; color: green;">H</span> <span style="color: green;">(help)</span>''
 +
** ''<span style="font-family: courier new; color: green;">P</span> <span style="color: green;">(priority)</span>''
 +
** ''<span style="font-family: courier new; color: green;">E</span> <span style="color: green;">(enabled)</span>''
 +
** ''<span style="font-family: courier new; color: green;">F</span> <span style="color: green;">(fields)</span>''
 +
** ''<span style="font-family: courier new; color: green;">M</span> <span style="color: green;">(multiple)</span>''
 +
** ''<span style="font-family: courier new; color: green;">S</span> <span style="color: green;">(style)</span>''
 +
** ''<span style="font-family: courier new; color: green;">C</span> <span style="color: green;">(condition)</span>''
 +
** ''<span style="font-family: courier new; color: green;">X</span> <span style="color: green;">(execute AmiScript)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">R</span> (response to execute command)  
 +
** ''<span style="font-family: courier new; color: red;">I</span> (Unique ID)''
 +
** ''<span style="font-family: courier new; color: red;">S</span> (status)''
 +
** ''<span style="font-family: courier new; color: green;">M</span> <span style="color: green;">(message)</span>''
 +
** ''<span style="font-family: courier new; color: green;">X</span> <span style="color: green;">(execute AmiScript)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">D</span> (delete object)
 +
** ''<span style="font-family: courier new; color: red;">I</span> (object ID)''
 +
** ''<span style="font-family: courier new; color: red;">T</span> (object Type)''
 +
 +
* <span style="font-family: courier new; color: red;">X</span> (exit)
 +
* <span style="font-family: courier new; color: red;">H</span> (help)
 +
* <span style="font-family: courier new; color: red;">P</span> (pause) only to be used in testing
 +
** ''<span style="font-family: courier new; color: red;">D</span> (delay)''
 +
 +
'''Valid inbound types ''and parameters always supplied <span style="color: green;">(occasionally supplied parameters in green)</span>'''''
 +
 +
* <span style="font-family: courier new; color: red;">M</span> (status message)
 +
** ''<span style="font-family: courier new; color: red;">S</span> (status)''
 +
** ''<span style="font-family: courier new; color: red;">Q</span> (sequence number)''
 +
** ''<span style="font-family: courier new; color: green;">M</span> <span style="color: green;">(message)</span>''
 +
 +
* <span style="font-family: courier new; color: red;">E</span> (execute command)
 +
** ''<span style="font-family: courier new; color: red;">I</span> (unique ID)''
 +
** ''<span style="font-family: courier new; color: red;">C</span> (a string command)''
 +
** ''<span style="font-family: courier new; color: red;">U</span> (user name)''
 +
** ''<span style="font-family: courier new; color: green;">O</span> <span style="color: green;">(associated object ID)</span>''
 +
 +
= Data Storage (Advanced) =
 +
'''Data sizes Overview.''' Each parameter added to an object  and application status message has a '''3 byte overhead''', plus additional bytes, depending on the data type. Please see the table below.
 +
 +
[[File:RTAPI.DataStorage.jpg|560x560px]]
 +
 +
'''Keys'''. The length of a key has virtually no impact on memory.  This is because all key names are indexed. Ami Supports up to 65,536 unique key names plus data types (T=). This is a hard limit per AMI center and going beyond that will result in data loss. For example, the following 2 messages would result in 5 unique keys. Note that when key names and types (T=) are repeated then they do not count as a new unique key.
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="</span><span style="font-family: courier new; color: blue;">Order"|quantity=100|symbol='ABC'|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="Ord123"</span>
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="</span><span style="font-family: courier new; color: blue;">"Execution"|quantity=50|symbol='XYZ'|price=45.3d|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="exec123"</span>
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="</span><span style="font-family: courier new; color: blue;">Execution"|quantity=150|symbol='DEF'|price=13d|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="exec456"</span>
 +
 +
= Enums (Advanced) =
 +
'''Clarification on Denoting Enums vs. Strings:''' Enums are surrounded using single quotes (') while strings are denoted using double quotes ("). For example (note the quote types):
 +
 +
<span style="font-family: courier new; color: blue;">O|T="sample"|my_enum='hello'|my_string="Hello there Mr. Jones"</span>
 +
 +
'''Enum Storage Methodology''': Using enums will dramatically reduce the cost of storing text that is often repeated. Instead of storing the ''actual'' value, just an index (binary number) is stored and regardless of how many times it is referenced only a single instance of the string is kept in a lookup table. The first 255 unique enum values received by the AMI central server will be indexed using a single byte index. The following 65,281 unique enum values received will be indexed using 2 bytes and the last 16,711,935 unique entries will use a 3 byte index. Be aware that the order in which unique enum values are introduced also determines the storage requirements for repeat entries.
 +
 +
'''Enum Scope''': The scope of a particular enum is for an AmiCenter. This means that the same index will be used regardless of application sending the enum, type of message it is in or parameter it is associated with. For example, the following will result in 3 enums (presuming these are the first 3 messages then all 3 of these would be indexed using a single byte):
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="Order"|symbol='ABC'|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="Ord123"|name='DEF'</span>
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="Execution"|name='ABC'|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="exec123"</span>
 +
 +
<span style="font-family: courier new; color: red;">O</span><span style="font-family: courier new; color: blue;">|</span><span style="font-family: courier new; color: red;">T</span><span style="font-family: courier new; color: blue;">="Execution"|symbol='DEF'|Orig='ZZZ'|</span><span style="font-family: courier new; color: red;">I</span><span style="font-family: courier new; color: blue;">="exec456"</span>
 +
 +
Note: Exceeding 16,777,216 unique enums will cause the Center to treat remaining Enums as Strings.
 +
 +
'''Understanding Cost:'''
 +
 +
The first instance of an enum has significant overhead verses a String, but following instances will usually have a highly reduced overhead.  
 +
{| class="wikitable"
 +
|Description
 +
|Enum Cost
 +
 +
(Best case)
 +
|String  Cost
 +
 +
(Best Case)
 +
|Enum Cost
 +
 +
(Worst  case)
 +
|String  Cost
 +
 +
(Worst Case)
 +
|-
 +
|First entry for a string
 +
|19 + (length x 2)
 +
|4 + length
 +
|21 + (length x 2)
 +
|7 + length * 2
 +
|-
 +
|repeat entries for string
 +
|'''4'''
 +
|4 + length
 +
|'''6'''
 +
|7 + length * 2
 +
|}
 +
''Notes: (1) The length variable is the number of characters in the string. (2) Costs are in bytes.''
 +
 +
From the table above you can see there is a large cost for the first entry for an enum, but additional entries have a highly reduced cost which is regardless of string size.
 +
 +
= JSON AMI Command Invocation User Form Definition =
 +
 +
=== Structure ===
 +
The below structure demonstrates how to construct a well-formed input user form. Forms have support for input fields which can contain any number of input arguments.  Note that a form definition with neither a '''<span style="font-family: courier new; color: red;">form</span>''' stanza nor a '''<span style="font-family: courier new; color: red;">timeout</span>''' stanza will result in no dialog and immediate execution of the command when the user selects the command.
 +
 +
[[File:RTAPI.JSONAMI.jpg|361x361px]]
 +
 +
'''Example'''
 +
 +
<span style="font-family: courier new; ">C|I="Test"|N="Testing Command"|L=3|H="This is a test"|W='T=="Test Executions" && __USERNAME=="jsmith" && Quantity>100'|M="0-1"|A='{"form":{"inputs":[{"label":"Symbol","required":true, "var":"symbol","type":"text"},{"label":"Reason","pattern":"[0-9a-z]+","required": true, "var": "reason","type":"textarea"},{"label":"Employee ID","required":true, "var":"ID","type":"text"},{"label":"Other","required": false, "var":"other","type":"textarea"},{"label": "Team","required": true, "var": "team","type":"select", "options":[{"value":"a","text":"A"},{"value":"b","text":"B"},{"value":"c","text":"C"}]},{"label": "Mode","required": true, "var": "mode","type":"select", "options":[{"value":"emergency","text":"Emergency"},{"value":"normal","text":"Normal"},{"value":"urgent","text":"Urgent"}],"enabled":true}],"buttons":[{"type":"cancel","label":"Ignore"},{"type":"submit","label":"Confirm"}],"width":500,"height":500},"timeout":100000}'</span>
 +
 +
 +
[[File:RTAPI.JSONAMIExample.jpg|431x431px]]
 +
 +
= Description of AMI JSON Form Definition Fields =
 +
{| class="wikitable"
 +
|'''Name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|'''Req.'''
 +
|-
 +
|<span style="font-family: courier new; ">form</span>
 +
|object
 +
|Object which identifies the form presented to the user
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs</span>
 +
|array
 +
|Array which lists the input widgets inside the form
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.label</span>
 +
|string
 +
|Label displayed next to the input
 +
|'''X'''
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.var</span>
 +
|string
 +
|key associate with the value that is sent to the back end
 +
|'''X'''
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.required</span>
 +
|boolean
 +
|If true, user must supply a non-blank value, default is false
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.pattern</span>
 +
|string
 +
|The pattern that the user-supplied value must match to
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.type</span>
 +
|String
 +
 +
(enum)
 +
|The type of user input, default is text. Permissible values:
 +
 +
   <span style="font-family: courier new; ">text</span> - regular, single line text input
 +
 +
   <span style="font-family: courier new; ">textarea</span> - multi-line text input
 +
 +
   <span style="font-family: courier new; ">select</span> - multi option select field
 +
 +
   <span style="font-family: courier new; ">hidden</span> - field is hidden from user
 +
 +
   <span style="font-family: courier new; ">password</span> - hides letters
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.value</span>
 +
|string
 +
|Reference a variable on selected record
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.options</span>
 +
|array
 +
|List of options, required & only applicable if type=select
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.options.value</span>
 +
|string
 +
|Value sent to backend if option is elected.
 +
|'''X'''
 +
|-
 +
|<span style="font-family: courier new; ">form.inputs.options.text</span>
 +
|string
 +
|Text displayed to user, if not supplied value is used
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.buttons</span>
 +
|Array
 +
|Array which lists the buttons at the bottom of the form
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.buttons.type</span>
 +
|string
 +
|The type of button.  Permissible values:
 +
 +
submit - submit the form to backend
 +
 +
cancel - cancel and close the form
 +
|'''X'''
 +
|-
 +
|<span style="font-family: courier new; ">form.buttons.label</span>
 +
|string
 +
|The text displayed on the button
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.width</span>
 +
|number
 +
|Width of form in pixels
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.height</span>
 +
|number
 +
|Height of form in pixels
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">form.labelWidth</span>
 +
|number
 +
|Width of the labels column in pixels
 +
|
 +
|-
 +
|<span style="font-family: courier new; ">Timeout</span>
 +
|number
 +
|Max time the user will wait for a response from the backend after submitting form, in milliseconds
 +
|
 +
|}

Latest revision as of 03:09, 24 May 2023

AMI Backend Interface

Goal

The 3Forge Application Management 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.

P: Used to supply a fully qualified java class name to an AMI relay plugin. The class must implement the com.f1.ami.relay.AmiRelayPlugin 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)

This has been deprecated

Outbound Instruction Type - Object (O)

Used to create an object (row) that gets inserted into AMI DB

Required fields supplied by application

T: Table name

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

The below example inserts a record into the Order table. The key-value pair maps value to column, e.g. the first column is qty, and the value is 1223. The last column represents an AMI reserved column, E, that indicates the expiry time of this row.

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

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 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:

  • __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_.
  • To use legacy variables names such as user.username, set the following property: ami.web.support.legacy.amiscript.varnames=true

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:

  • __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 = 2nd 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

RTAPI.Multi.jpg

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

  • "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 AMI Script Doc in AMI Web under Help for details.

Example

C|I="alert"|X='session.alert("hi");'|C="now"

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=="FEED:Orders" || panel.types=="FEED:Executions"'|W='qty>0 && user.canbust=="true"'|A='{"form":{"inputs":[{"label": "Comment","var": "comment","required":true}]},"timeout":10000}'

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"

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"

Outbound Instruction Type - Pause (P)

Used to create a pause in the connection for a specified period of time. This is used for testing scripts.

Required fields supplied by application

D: Delay

Example

This example pauses the application for 1 second:

P|D=1000

Inbound Instruction Type - Status Message (M)

For each outbound message, the relay will respond with a response instruction which will notify the application of the acceptance of rejection of the message. The message will contain the sequence number of the supplied outbound message. These messages will not contain a timestamp or a sequence number.

Parameters always supplied by relay

S: The status of the received instruction. A value of 0 indicates it was successfully processed by the relay; a value of 1 to 255 indicates an error.

Q: The sequence number of the instruction sent from the relay.

M: A human-readable message for the status.

Examples

In the following example, the login message was rejected due to a missing ID.

M|Q=0|S=1|M="Missing required Fields: I"

Inbound Instruction Type - Execute Command (E)

This will allow users to execute commands on the application. A timestamp and sequence number will always be included.

Parameters are always supplied by the relay

I: Unique ID as a string. This ID is generated by AMI

C: The ID of the command

U: User name of the person doing the command.

Parameters optionally supplied by relay

O: Associated object ID. This will be supplied if the command is executed on an object.

Examples In the following example we can see the user is running the command "cancel" with the arguments "OR-11323." The ID (I) of "f123f56a" will be unique for this process and should be included in the applications response.

E#872@1374353639915|I="f123f56a"|C="cancel OR-11323"|U="JSmith"

Outbound Instruction Type - Alert (A)

<Deprecated but supported, use Object (O) instead>

Outbound Instruction Type - Help (H)

Prints out general help

Cheat Sheet

Valid outbound types and required parameters (optional pre-defined parameters in green)

  • L (login)
    • I (app ID)
    • O (session options)
    • PL (plugin options)
  • S (status)
  • A (alert) DEPRECATED
    • I (alert ID)
    • L (level)
    • T (alert type)
    • E (expires on)
    • U (user assignment)
  • O (object)
    • I (object ID)
    • T (object Type)
    • E (expires on)
  • C (command definition)
    • I (command ID)
    • N (name)
    • W (where - row level)
    • T (where - panel level)
    • L (permissions Level)
    • A (form definition)
    • H (help)
    • P (priority)
    • E (enabled)
    • F (fields)
    • M (multiple)
    • S (style)
    • C (condition)
    • X (execute AmiScript)
  • R (response to execute command)  
    • I (Unique ID)
    • S (status)
    • M (message)
    • X (execute AmiScript)
  • D (delete object)
    • I (object ID)
    • T (object Type)
  • X (exit)
  • H (help)
  • P (pause) only to be used in testing
    • D (delay)

Valid inbound types and parameters always supplied (occasionally supplied parameters in green)

  • M (status message)
    • S (status)
    • Q (sequence number)
    • M (message)
  • E (execute command)
    • I (unique ID)
    • C (a string command)
    • U (user name)
    • O (associated object ID)

Data Storage (Advanced)

Data sizes Overview. Each parameter added to an object  and application status message has a 3 byte overhead, plus additional bytes, depending on the data type. Please see the table below.

RTAPI.DataStorage.jpg

Keys. The length of a key has virtually no impact on memory.  This is because all key names are indexed. Ami Supports up to 65,536 unique key names plus data types (T=). This is a hard limit per AMI center and going beyond that will result in data loss. For example, the following 2 messages would result in 5 unique keys. Note that when key names and types (T=) are repeated then they do not count as a new unique key.

O|T="Order"|quantity=100|symbol='ABC'|I="Ord123"

O|T=""Execution"|quantity=50|symbol='XYZ'|price=45.3d|I="exec123"

O|T="Execution"|quantity=150|symbol='DEF'|price=13d|I="exec456"

Enums (Advanced)

Clarification on Denoting Enums vs. Strings: Enums are surrounded using single quotes (') while strings are denoted using double quotes ("). For example (note the quote types):

O|T="sample"|my_enum='hello'|my_string="Hello there Mr. Jones"

Enum Storage Methodology: Using enums will dramatically reduce the cost of storing text that is often repeated. Instead of storing the actual value, just an index (binary number) is stored and regardless of how many times it is referenced only a single instance of the string is kept in a lookup table. The first 255 unique enum values received by the AMI central server will be indexed using a single byte index. The following 65,281 unique enum values received will be indexed using 2 bytes and the last 16,711,935 unique entries will use a 3 byte index. Be aware that the order in which unique enum values are introduced also determines the storage requirements for repeat entries.

Enum Scope: The scope of a particular enum is for an AmiCenter. This means that the same index will be used regardless of application sending the enum, type of message it is in or parameter it is associated with. For example, the following will result in 3 enums (presuming these are the first 3 messages then all 3 of these would be indexed using a single byte):

O|T="Order"|symbol='ABC'|I="Ord123"|name='DEF'

O|T="Execution"|name='ABC'|I="exec123"

O|T="Execution"|symbol='DEF'|Orig='ZZZ'|I="exec456"

Note: Exceeding 16,777,216 unique enums will cause the Center to treat remaining Enums as Strings.

Understanding Cost:

The first instance of an enum has significant overhead verses a String, but following instances will usually have a highly reduced overhead.  

Description Enum Cost

(Best case)

String  Cost

(Best Case)

Enum Cost

(Worst  case)

String  Cost

(Worst Case)

First entry for a string 19 + (length x 2) 4 + length 21 + (length x 2) 7 + length * 2
repeat entries for string 4 4 + length 6 7 + length * 2

Notes: (1) The length variable is the number of characters in the string. (2) Costs are in bytes.

From the table above you can see there is a large cost for the first entry for an enum, but additional entries have a highly reduced cost which is regardless of string size.

JSON AMI Command Invocation User Form Definition

Structure

The below structure demonstrates how to construct a well-formed input user form. Forms have support for input fields which can contain any number of input arguments.  Note that a form definition with neither a form stanza nor a timeout stanza will result in no dialog and immediate execution of the command when the user selects the command.

RTAPI.JSONAMI.jpg

Example

C|I="Test"|N="Testing Command"|L=3|H="This is a test"|W='T=="Test Executions" && __USERNAME=="jsmith" && Quantity>100'|M="0-1"|A='{"form":{"inputs":[{"label":"Symbol","required":true, "var":"symbol","type":"text"},{"label":"Reason","pattern":"[0-9a-z]+","required": true, "var": "reason","type":"textarea"},{"label":"Employee ID","required":true, "var":"ID","type":"text"},{"label":"Other","required": false, "var":"other","type":"textarea"},{"label": "Team","required": true, "var": "team","type":"select", "options":[{"value":"a","text":"A"},{"value":"b","text":"B"},{"value":"c","text":"C"}]},{"label": "Mode","required": true, "var": "mode","type":"select", "options":[{"value":"emergency","text":"Emergency"},{"value":"normal","text":"Normal"},{"value":"urgent","text":"Urgent"}],"enabled":true}],"buttons":[{"type":"cancel","label":"Ignore"},{"type":"submit","label":"Confirm"}],"width":500,"height":500},"timeout":100000}'


RTAPI.JSONAMIExample.jpg

Description of AMI JSON Form Definition Fields

Name Type Description Req.
form object Object which identifies the form presented to the user
form.inputs array Array which lists the input widgets inside the form
form.inputs.label string Label displayed next to the input X
form.inputs.var string key associate with the value that is sent to the back end X
form.inputs.required boolean If true, user must supply a non-blank value, default is false
form.inputs.pattern string The pattern that the user-supplied value must match to
form.inputs.type String

(enum)

The type of user input, default is text. Permissible values:

   text - regular, single line text input

   textarea - multi-line text input

   select - multi option select field

   hidden - field is hidden from user

   password - hides letters

form.inputs.value string Reference a variable on selected record
form.inputs.options array List of options, required & only applicable if type=select
form.inputs.options.value string Value sent to backend if option is elected. X
form.inputs.options.text string Text displayed to user, if not supplied value is used
form.buttons Array Array which lists the buttons at the bottom of the form
form.buttons.type string The type of button.  Permissible values:

submit - submit the form to backend

cancel - cancel and close the form

X
form.buttons.label string The text displayed on the button
form.width number Width of form in pixels
form.height number Height of form in pixels
form.labelWidth number Width of the labels column in pixels
Timeout number Max time the user will wait for a response from the backend after submitting form, in milliseconds