The AMIE Model

Overview

The AMIE model consists of two sites and an agreed upon set of transactions that the two sites will use to send account management data to each other. A transaction consists of packets of data sent between the two sites. The site sending a packet is called the local site and the packet is known to the sending site as an outgoing packet. The receiving site is called the remote site and the packet received is known to the receiving site as an incoming packet. The site that creates the transaction (and sends the first packet) is also called the originating site.

Transactions

Transactions have a number of properties. These are the local site, the remote site, the originating site, a transaction id, and a state. Once created, the first four properties do not change. The state changes over time.

The transaction id is usedto distinguish one transaction from another. The originating site chooses the transaction id without consulting the remote site. The only rule is that a transaction id created by one site may not be reused by that site for a different transaction.[1] Hence a transaction is identified by the originating site, the transaction id, the local site, and the remote site.

AMIE defines 3 states for a transaction:in-progress, completed, or failed. The initial state of a transaction is in-progress. It remains in that state until all packets have been processed. If all packets have been successfully processed, the transaction state becomes completed. If any of the packets causes a failure, the transaction state becomes failed.[2]

Packets

Transactions also have packets which contain account management data. Incoming packets are those packets received from the remote site. Outgoing packetsare those packets created by the local site to be sent to the remote site. Outgoing packets are created either when the transaction is created or as a reply to an incoming packet.

AMIE does not specify a pre-defined set of transactions. It specifies a set of packets which can be used within transactions, but the sites must agree on the packets that are used within transactions as well as the ordering of those packets.

A packet has a number of properties. These are type, version, packet id, and state. It also has a list of expected replies.

The following are the packet types that AMIE version “1.0” specifies:

  1. data_account_create
  2. data_project_create
  3. notify_account_create
  4. notify_account_inactivate
  5. notify_account_reactivate
  6. notify_project_create
  7. notify_project_modify
  8. notify_project_reactivate
  9. notify_project_resources
  10. notify_project_usage
  11. notify_user_modify
  12. notify_user_reactivate
  13. notify_user_suspend
  14. request_account_create
  15. request_account_inactivate
  16. request_account_reactivate
  17. request_project_create
  18. request_project_inactivate
  19. request_project_modify
  20. request_project_reactivate
  21. request_project_resources
  22. request_user_modify
  23. request_user_reactivate
  24. request_user_suspend
  1. inform_transaction_complete

The types and their contents are determined by the AMIE XML schema[3]. As of the writing of this document, the AMIE XML schema only specifies version “1.0”. However, in anticipation of newer versions, each packet must also specify its AMIE version, since the content of the packet depends on the version.

Each packet has a packet id which is chosen by the site that creates the packet. It has to be unique within the set of outgoing packets for a given transaction[4].

Each packet has a state. AMIE defines 3 states for a packet: in-progress, completed, or failed.

Each packet must also provide a list of expected replies. An expected reply is the type of packet that a site expects to receive from the remote site after the remote site has processed the packet. The expected reply list allows sites to determine which packets will be part of a transaction and the ordering of the packets within the transaction, rather than this being dictated by AMIE.

Every transaction is ended by an inform_transaction_complete packet. This packet indicates success or failure of the transaction (and the reason). A success inform_transaction_complete can only be sent if it is listed as one of the expected replies. A failure can be sent at any time.

Example

This shows a high-level of an example transaction. Two sites “X” and “Y” agree that a “project creation” transaction consists of the packets: request_project_create, notify_project_create, data_project_create. Assuming that site X originates the transaction, the flow of packets between the sites would be:

X / request_project_create /  / Y
X /  / notify_project_create / Y
X / data_project_create /  / Y
X /  / inform_transaction_complete / Y

X would create a transaction, with the following properties:

Originating Site / X
Local Site / X
Remote Site / Y
Transaction ID / 12345

X would then create an outgoingrequest_project_create packet for this transaction[5]:

Type / request_project_create
Version / 1.0
Packet ID / 1
Expected Reply / notify_project_create

AMIE would send this packet to Y who would create a transaction record to mirror X’s transaction record[6]:

Originating Site / X
Local Site / Y
Remote Site / X
Transaction ID / 12345

Y would also create an incomingrequest_project_createpacket:

Type / request_project_create
Version / 1.0
Packet ID / 1

After processing the request_project_create, Y would create an outgoingnotify_project_create packet:

Type / notify_project_create
Version / 1.0
Packet ID / 1[7]
Expected Reply / data_project_create

AMIE would send this packet to X, which would create an incomingnotify_project_createpacket:

Type / notify_project_create
Version / 1.0
Packet ID / 1

After processing the notify_project_create, X would create an outgoing data_project_create packet:

Type / data_project_create
Version / 1.0
Packet ID / 2
Expected Reply / inform_transaction_complete

AMIE would send this packet to Y, which would create an incoming data_project_create packet:

Type / data_project_create
Version / 1.0
Packet ID / 2

After processing the data_project_create, X would create an outgoing inform_transaction_complete packet:

Type / inform_transaction_complete
Version / 1.0
Packet ID / 3

This completes the transaction from the perspective of Y.

AMIE would send this packet to X, who would create an incoming inform_transaction_complete packet:

Type / inform_transaction_complete
Version / 1.0
Packet ID / 3

This would complete the transaction from the perspective of site X.

1 of 510/7/2018

[1] This rule can be relaxed slightly. The transaction id is used by both sites to track transaction state. Once the transaction is completed and sufficient time has passed, the transaction state can be deleted from both sites and a transaction id can be reused. However, this is outside the scope of AMIE state management. It is up to both sites to decide how long to retain transaction state. The main issue would be to prevent sending duplicate data.

[2]Both completed and failed are final states.

[3] Even though the packet types and content are specified as XML, sites do not generate XML files directly. They must implement an interface to their local account management system in perl, in particular, as methods calls that the AMIE system will make to get transaction and packet information and data. Implementing this interface is described in the documentImplementing AMIE.

[4] A local site can choose a packet id for an outgoing packet independently from the packet ids used by the remote site for the same transaction. In other words, the packet ids for outgoing packets are independent of the packet ids for incoming packets.

[5] The implementation would have an explicit mechanism to link the packet with the transaction, perhaps a key field in the transaction record and a foreign-key reference to it in the packet table. As this is an implementation detail, it is not shown in the example.

[6] Note that the local site is Y and that the remote site is X, which is the reverse of that for the transaction record at site X.

[7] Note that the packet id happens to be the same as for the incoming request_project_create. This is not required. It can be any positive integer, but it makes sense to start with 1. Also, packet ids for incoming packets are independent of packet ids for outgoing packets.