I-X Message Formats and Links to External Agents 18-Sep-2002
Austin Tate <a.tate@ed.ac.uk>, AIAI, University of Edinburgh 
----------------------------------------------------------------

Full details in I-X\doc\IX-Quick-Start-Guide.doc


External agents communicate with I-X process Panels (I-P2) via XML messages.  The main message types of interest are an "activity" message used to invoke a function or capability in another agent, and "report" messages which can be used by the externally invoked agent to give progress and completion reports.


Sample activity message

<?xml version="1.0" encoding="UTF-8"?>
<activity status="blank" priority="high" sender-id="IX-CFC" report-back="yes" ref="activity-19">
  <pattern>
    <list>
      <symbol>monitor-medical-situation</symbol>
      <symbol>ship</symbol>
      <symbol>HMAS-Coonawarra</symbol>
      <symbol>causalities</symbol>
      <symbol>moderate</symbol>
      <string>Lat:17.13</string>
      <string>Lat:40.75</string>
    </list>
  </pattern>
</activity>

Sample progress and (success or failure) completion report messages in response

<?xml version="1.0" encoding="UTF-8"?>
<report report-type="progress" priority="normal" sender-id="your-agent-name" ref="activity-19">
  <text>
    <string>Report text./string>
  </text>
</report>

<?xml version="1.0" encoding="UTF-8"?>
<report report-type="success" priority="normal" sender-id="your-agent-name" ref="activity-19">
  <text>
    <string>Done - 5 results available at http://mysite/results.html</string>
  </text>
</report>


For testing, and for demonstration uses, it is possible to add a sample activity item onto a process panel using the messenger and to send that activity to "me".  If the .props file for the relevant panel constians a property "external-capabilities" is set to include the agent name of the external capability, and specifies the verb/first symbol used in an activity pattern, then an "action" menu item entry for the activity item will include the option "Invoke <external-capability agent name>".  An example external-capabilities proprty entrty for use in an I-X .props file is:

external-capabilities=MCA:coordinate_plans,Adaptive-Agent-Organizations:find-max-utility-resource,Adaptive-Agent-Organizations:find_resource,Adaptive-Agent-Organizations:select_resource,UMD-Predict:take-feed,US-Medical-Monitor:monitor-medical-situation,US-Medevac-Team:handle-medical-situation,US-Medevac-Team:monitor-medical-situation,Arabello-Intel:provide

Note that multiple verbs are possible for a single agent.  The list should not contain spaces.

Selecting this option will send the activity message to that agent.  The agent can reposond at any time with progress or success/failure completion reports, and can send post-completion (information) messages after completion is desired.

I-P2 can at any time accept a range of message types - issue, activity, constraints/state, report and chat.  You can find out what teh XML for any message format looks like by using a panel's messenger tool to send the rerlewvant content to "me" (the current panel and then look at the Java console window to see or copy the relevant XML content produced).


Examples of Messages
_____________________________________________________________________


<?xml version="1.0" encoding="UTF-8"?>
<issue status="blank" priority="high" sender-id="IX-CFMCC">
  <pattern>
    <list>
      <symbol>consider</symbol>
      <symbol>this</symbol>
    </list>
  </pattern>
</issue>

<?xml version="1.0" encoding="UTF-8"?>
<activity status="blank" priority="normal" sender-id="IX-CFMCC" ref="activity-10" report-back="yes">
  <pattern>
    <list>
      <symbol>provide</symbol>
      <symbol>intel-feed</symbol>
      <symbol>submarine-contact-reports</symbol>
      <symbol>Binni-Coalition</symbol>
    </list>
  </pattern>
</activity>

<?xml version="1.0" encoding="UTF-8"?>
<activity status="blank" priority="normal" sender-id="IX-CFMCC" ref="activity-14" report-back="yes">
  <pattern>
    <list>
      <symbol>deploy</symbol>
      <symbol>ASW-Capable-Ships</symbol>
      <symbol>line</symbol>
      <symbol>17-degrees-latitude</symbol>
    </list>
  </pattern>
</activity>


Sample report backs... progress and (success or failure) completion

<?xml version="1.0" encoding="UTF-8"?>
<report report-type="progress" priority="normal" sender-id="IX-Arabello-HQ" ref="activity-10">
  <text>
    <string>Starting execution.</string>
  </text>
</report>

<?xml version="1.0" encoding="UTF-8"?>
<report report-type="success" priority="normal" sender-id="IX-Arabello-HQ" ref="activity-10">
  <text>
    <string>Completed.</string>
  </text>
</report>





