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 used to 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 packets are 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.
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.
1 of 5 11/15/2011
The AMIE Model
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
25. inform_transaction_complete
The types and their contents are determined by the AMIE XML schema3. 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 transaction4.
Each packet has a state. AMIE defines 3 states for a packet: in-progress, completed, or failed.
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
document Implementing 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.
2 of 5 11/15/2011
The AMIE Model
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 outgoing request_project_create packet for this transaction5:
Type request_project_create
Version 1.0
Packet ID 1
Expected Reply notify_project_create
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.
3 of 5 11/15/2011
The AMIE Model
AMIE would send this packet to Y who would create a transaction record to mirror X’s transaction
record6:
Originating Site X
Local Site Y
Remote Site X
Transaction ID 12345
Y would also create an incoming request_project_create packet:
Type request_project_create
Version 1.0
Packet ID 1
After processing the request_project_create, Y would create an outgoing notify_project_create
packet:
Type notify_project_create
Version 1.0
Packet ID 17
Expected Reply data_project_create
AMIE would send this packet to X, which would create an incoming notify_project_create packet:
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
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.
4 of 5 11/15/2011
The AMIE Model
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.
5 of 5 11/15/2011