= Howto AIPs =

== (1) Description ==

AIPs (Agent Interaction Protocol Diagrams) are a dialect of IPs (Interaction Protocols) as they are used by [http://www.fipa.org FIPA] and in [http://www.auml.org AUML]. As a special form of Sequence Diagrams (see [http://www.omg.org UML]), which are commonly used to model sequences of communication, AIPs (and IPs, too) can be used to model scenarios, i.e. sets of sequences.

== (2) Embedment in the PAOSE Development Process ==
[[ImageSvg(Paose-detailed-AIP.svg)]]

== (3) Usage ==

Start Renew and activate the palette for the diagram tools (Tools >> Diagram Drawing Tool >> toggle ; Ctrl-Shift-X). The tools function only correctly in a AIP drawing: File >> New Drawing and choose Diagram Drawing (*.aip). 

Some restrictions allow for faster drawing of AIP elements. ''Role Descriptors'' can be drawn anywhere, preferably at the top of the drawing. ''Activations'' (tasks) and ''Life Line Splits'' can be drawn exclusively underneath (south) of another drawing element. ''Life Lines'' are automatically added between the new element and the element above (north). 

Several handles can be used to draw ''Messages'' or ''Life Lines'' and the a new element at the same time. ''Actions'' and ''DC Exchanges'' are special inscriptions that can be attached to the ''Activations''. ''Message Arcs'' can be inscribed with the message content or an SL message. 

Generation of Petri net code (skeletons) from AIPs are possible via a menu command (Ctrl-G). See [wiki:Howto-AIPs#a4InscriptionsMessagesActions: below] for the meaning and syntax of inscriptions.



== (4) Inscriptions (Messages, Actions): ==
''(Text copied from Diagram/etc/README.diagram.)''
=== Messages: ===

Messages can start with action -- complete message inscription
{{{
 AIP:                                              Net: (NC-out inscription)
 ------------------------------------------>       |\
  action p2 = new SomeObject().toAclMessage(aid)         | \
                                                   |  \
                                                   |   \
                                                   |____\
                                                   action p2 = new SomeObject().toAclMessage(aid)
 
 }}}
Messages can have arbitrary inscriptions -- interpreted as content
{{{
 AIP:                                              Net: (NC-out inscription)
 ------------------------------------------>       |\
             slContent                             | \
                                                   |  \
                                                   |   \
                                                   |____\
                                                   action p2 = Sl0Creator.createActionRequest(
                                                             aid,
                                                             slContent)

}}}
Without inscriptions the standard will be inserted in NC out
{{{
 AIP:                                              Net: (NC-out inscription)
 ------------------------------------------>       |\
                                                   | \
                                                   |  \
                                                   |   \
                                                   |____\
                                                   action p2 = Sl0Creator.createActionRequest(
                                                             aid,
                                                             "content")
}}}

=== Actions: ===
Action inscriptions will be added to the sequence as raw text.  ":access(kb)" is already available.
{{{
 AIP:                                             Net: (NC-sequence inscription)

       |      |                                    
  -----------------------                         |-----------------------|
  | kb:ask("name",name) |                         |                       |
  -----------------------                         |-----------------------|
       |      |                                        :access(kb)
                                                     kb:ask("name",name)
                                                   
}}}                                                   
                                                   
                                                   
=== DC exchange: ===
DC inscriptions will be added to the NC-exchange description
{{{
 AIP:                                             Net: (NC-exchange description)
                                                  (dcNewExchange(.,.,.) channel)    
       |      |                                           /  \
  --------------------                                  /      \
  | RoleHelper.TEST  |                               RoleHelper.TEST                    
  --------------------                              /              \
       |      |                                    ------------------                               
}}} 
DC inscriptions leading with the keyword "simple" will be added to the NC-simple-exchange description
{{{
 AIP:                                             Net: (NC-simple exchange description)
                                                  (dcExchange(.,.) channel)    
       |      |                                           /  \
  ---------------------------                           /      \
  | simple RoleHelper.TEST  |                       RoleHelper.TEST                    
  ---------------------------                       /              \
       |      |                                    ------------------                               
   }}}