====== Esystem XML Interface version 0.3 ======



===== XML szerkezete =====

==== Kliens üzenete a szerver felé ====
 
<file>
<esystem version'''0.3'>
  <click>
    <session>
      <record>
        <field>
          <name>mezőnév</name>
          <value>érték</value>
        </field>
        <field>
          <name>mezőnév</name>
          <value>érték</value>
        </field>
      </record>
    </session>
    <data>
      <record>
        <field>
          <name>mezőnév</name>
          <value>érték</value>
        </field>
        <field>
          <name>numfield</name>
          <value>0</value>
        </field>
      </record>
    </data>
  </click>
</esystem>
</file>

==== Szerver üzenete a kliens felé ====

<file>
<esystem version'''0.3'>
  <frame>
    <framename>main</framename>
    <choice>
      <choicename>form</choicename>
<click>
      <session>
        <record>
          <field>
            <name>mezőnév</name>
            <value>érték</value>
          </field>
          <field>
            <name>mezőnév</name>
            <value>érték</value>
          </field>
        </record>
      </session>
      <data>
        <record>
          <field>
            <name>mezőnév</name>
            <value>érték</value>
          </field>
          <field>
            <name>numfield</name>
            <value>0</value>
            <metadata>
              <type>text</type>
              <check>
                <regexp>^\d+$</regexp>
                <regexpmsg>Érvénytelen numerikus adat</regexpmsg>
                <req/>
              </check>
              <human>
                 <label>Szám</label>
                 <help>Numerikus mennyiség, kötelező</help>
              </human>
            </metadata>
          </field>
        </record>
      </data>
</click>
    </choice>
    <info_message>
      <msg>
         informacios uzenetek
      <msg>
    </info_message>    
    <result>
    <resultname>list</resultname>
      result specific content/elements...
    </result>
  </frame>
</esystem>

</file>

===== Leírás =====

==== esystem_element ====

Ez a gyökér element.

  * Választhatóan
    * Vagy tartalmaz 1 **click** elementet (kliens -> szerver) 
      * _Későbbi fejlesztés lehetőségét fenntartva a click element helyett más is előfordulhat    * vagy egy **frame** elementet (szerver->kliens)

| esystem |
| [[#click_element|click]] |

| esystem |
| [[#frame_element|frame]] |

==== click_element ====

Ebben egy virtuális kattintás szerepel.

  * opcionálisan tartalmaz 1 **session** elementet
  * opcionálisan tartalmaz 1 **data** elementet
  * opcionálisan tartalmaz 1 **header** elementet
  * opcionálisan tartalmaz 1 vagy több **line** elementet

| click |
| [[#session_element|session]] |

| click ||
| [[#session_element|session]] | [[#data_element|data]] |


==== frame_element ====

Egy virtuális kattintás eredményeképpen (vissza)kapott adatok

  * Tartalmaz egy **framename** elementet
  * Opcionálisan tartalmaz egy vagy több **choice** elementet
  * Opcionálisan tartalmaz egy **result** elementet
  * Opcionálisan tartalmaz egy **info_message** elemenetet


| frame ||
| [[#framename_element|framename]] | [[#result_element|result]] |

| frame |||||
| [[#framename_element|framename]] | [[#info_message_element|info_message]] | [[#result_element|result]] | [[#choice_element|choice]] | choice... |

==== framename_element ====

A frame neve.

Egyúttal jelzi a korábban, ilyen nevű; frame-ben érkező válaszok esetleges lejártságát.

<file>
<framename>main</framename>
</file>

==== info_message_element ====

<file>
    <info_message>
      <msg>
        <level>Info</level>
        <time>2009.10.29 15:24:02</time>
        <message>test xml</message>
      </msg>
    </info_message>

</file>

==== result_element ====


  * Kötelezően tartalmaz egy **resultname** elementet
  * Opcionálisan tartalmazhat egyéb elementeket, melyek szerkezete függhet a resultname értékétől

==== resultname_element ====

Az eredményoldal neve.

==== choice_element ====

Ez egy lehetséges választás frame-ben.

  * Kötelezően tartalmaz egy **choicename** elementet
    * Ez a név adott XML oldalaknál előre definiálva, dokumentálva van.
  * Kötelezően tartalmaz egy **click** elementet.
    ***Ez esetleg változhat/bővülhet**

| choice ||
| [[#choicename_element|choicename]] | [[#click_element|click]] |

==== session_element ====

Ebben az elementben vannak azok a paraméterek amik a kommunikációs session-re vonatkoznak (CGI session)

Ezeket az adatokat változtatás nélkül kell visszaküldeni az esystemnek, amennyiben az őt tartalmazó choice választása mellett dönt a kliens.

  * Kötelezően tartalmaz 1 **record** elementet

| session |
| [[#record_element|record]] |

==== data_element ====

Ebben az elementben vannak azok a paraméterek, amik a konkrét sessionhöz tartozó adatokat írják le.

Ezeket az adatokat a metadata szerinti szabályok szerint módosítva lehet visszaküldeni az esystemnek

  * Kötelezően tartalmaz 1 **record** elementet
    * _Esetleges további record elementek használata későbbi fejlesztés céljából elképzelhető, de jelenleg nem támogatott

| data |
| [[#record_element|record]] |

==== record_element ====

Ilyen elementben vannak az adatok összegyüjtve mezőnként

  * Kötelezően tartalmaz 1 vagy több **field** elementet

| record |
| [[#field_element|field]] |

| record ||
| [[#field_element|field]] | field... |

==== field_element ====

Ilyen elementben vannak a mezők leírva.

  * Kötelezően tartalmaz 1 **name** elementet
  * Kötelezően tartalmaz 1 vagy több **value** elementet
  * Opcionálisan tartalmazhat 0 vagy 1 **metadata** elementet
    * szerver->kliens irányú kommunikációnál várható, hogy létezik a**metadata** element
    * kliens->szerver irányú kommunikációnál a kliensnek nem kell ezt az elementet létrehoznia/visszaküldenie. Ha mégis megteszi, akkor a szerver azt figyelmen kívül fogja hagyni.

| field ||
| [[#name_element|name]] | [[#value_element|value]] |

| field ||||
| [[#name_element|name]] | [[#value_element|value]] | value... | [[#metadata_element|metadata]] |

==== name_element ====

A mező neve. /^[a-zA-Z0-9_]+$/  regexpre kell illeszkednie

Az**session** elementben szereplő mezőnevek nem egyezhetnek meg sem másik**session** elemenetbeli sem bármely 
**data** elementbeli mezőnévvel

A**data** elementben szereplő mezőnevek nem egyezhetnek meg ugyanabban a**data** elemenetben levő másik mezőnévvel és semmilyen mezőnévvel a 
**session** elementen belül

<file>
<name>beosztas</name>
</file>

==== value_element ====

A mező értéke. 

Általánosan itt bármilyen string szerepelhet, további megkötésekkel kapcsolatban a**metadata** element ad információt

<file>
<value>titkárnő segédje</value>
</file>

==== metadata_element ====

A metadata tartalmazza az API-t felhasználó program (illetve programot kezelő ember) felé azokat az információkat, ami segíthetik a mezők értékének kitöltését.

  * Tartalmaz egy **type** elementet
  * Tartalmazhat egy **check** elementet
  * Tartalmaz egy **human** elementet
  * Tartalmazhat továbbá bármilyen más valid XML struktúrát. 

| metadata |||
| [[#type_element|type]] | [[#check_element|check]] |  [[#human_element|human]] |

==== type_element ====

Ez adja meg a mező tipusát. Néhány tipus a teljesség igénye nélkül

  ***text** szöveges mező (egy sor)
  ***textarea** szöveges mező tetszőleges számú sortöréssel
  ***hidden** rejtett adat, úgy kell tekinteni mint a**session** element mezőit, módosítás nélkül vissza kell küldeni
  * További elementek lehetnek, melyek esetén a dokumentáció hiányosságát kell feltételezni.

<file>
<type>text</type>
</file>

==== check_element ====

A metadata ezen részében gépileg is feldolgozható adatok vannak, amik segítik a gépi interface-t abban, hogy szintaktikusan helyes adatokat rakjanak
a mezők értékébe.

  * Tartalmazhat egy **regexp** elementet
  * Tartalmazhat egy **regexpmsg** elementet
  * Tartalmazhat egy **req** elementet
  * Tartalmazhat egy **readonly** elementet

| check ||||
| [[#regexp_element|regexp]] | [[#regexpmsg_element|regexpmsg]] | [[req_element|req]] | [[#readonly_element|readonly]] |

==== regexp_element ====

Reguláris kifejezéssel történő adat megszorítás. A regexpet a perl regexpjének kell tekinteni.

==== req_element ====

Ha ez az element létezik, akkor a mező kitöltése kötelező, nem lehet üres

==== readonly_element ====

Ha ez az element létezik, akkor a mező értéke nem változtatható, azt módosítás nélkül kell visszaküldeni

==== regexpmsg_element ====

Ha a regexp nem illeszkedik, akkor ez az üzenet a mérvadó

==== human_element ====

Emberi olvasatra szánt segédinformációk

  * Tartalmazhat egy **label** elementet
  * Tartalmazhat egy **help** elementet

==== label_element ====

Ebben a mező neve olvasható.

==== help_element ====

Ebben a mezőről egy rövid segítség olvasható

===== Megjegyzés: =====

Kliens alkalmazások a szerver felé a az első ''Kliens üzenete a szerver felé'' üzenetet küldenek
Válaszul a második féle ''Szerver üzenete a kliens felé'' üzenetet kapnak.

szerver-szerver kommunikáció esetén előfordulhat hogy a két szerver egymás között az első 
''Kliens üzenete a szerver felé'' módon küld egymásnak adatot, és a választ is ugyanebben
a formában várják. De a rendszer ekkor is felkészült a hibakezelésre.
Hibás esetben a rendszer automatikusan a második fajta ''Szerver üzenete a kliens felé''
üzenetet küld.

===== Validálás =====

Az evir_test.xsd segítségével lehetett validálni az eVIR-nek küldendő csomagot.



<file xsd evir_test.xsd>
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="esystem">
    <xs:annotation>
      <xs:documentation>
        This is the root element of the communications between Esystem, and external programs.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:choice>
        <xs:element name="frame" type="frameType" />
        <xs:element name="click" type="clickType" />
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="frameType">
    <xs:sequence>
      <xs:element name="framename" type="xs:string" />
      <xs:element name="choice" minOccurs="0" maxOccurs="unbounded" type="choiceType" />
      <xs:element name="info_message" type="info_messageType" minOccurs="0" maxOccurs="1" />
      <xs:element name="result" type="resultType" minOccurs="0" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="choiceType">
    <xs:sequence>
      <xs:element name="choicename" type="xs:string" />
      <xs:element name="click" type="clickType" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="clickType">
    <xs:sequence>
      <xs:element name="session" type="sessionType" minOccurs="0" maxOccurs="1" />
      <xs:element name="data" type="dataType" minOccurs="0" maxOccurs="1" />
      <xs:element name="header" type="lineType" minOccurs="0" maxOccurs="1" />
      <xs:element name="line" type="lineType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="sessionType">
    <xs:sequence>
      <xs:element name="record" type="recordType" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="dataType">
    <xs:sequence>
      <xs:element name="record" type="recordType" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="lineType">
    <xs:sequence>
      <xs:element name="record" type="recordType" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="recordType">
    <xs:sequence>
      <xs:element name="field" type="fieldType" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="fieldType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" />
      <xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="unbounded" />
      <xs:element name="metadata" type="metadataType" minOccurs="0" maxOccurs="1" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="metadataType">
    <xs:sequence>
      <xs:any processContents='skip' minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="info_messageType">
    <xs:sequence>
      <xs:element name="msg" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="level" type="xs:string" />
            <xs:element name="time" type="xs:string" />
            <xs:element name="message" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="resultType">
    <xs:sequence>
      <xs:element name="resultname" type="xs:string" />
      <xs:element name="msg">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="info" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

</xs:schema>
</file>

===== Példák =====
  * [[spec:xml_pelda_egyszerusitett_lekerdezesek|XML Egyszerűsített lekérdezések]]
  * [[spec:xml_pelda_jelszavas_bejelentkezes|XML Jelszó alapú bejelentkezés]]
  * [[spec:xml_pelda_raktarlekerdezes|XML Raktárlekérdezés]]
  * [[spec:xml_pelda_rendeles_cikktorzsbol|XML alapú rendelés cikktörzsből]]
  * [[spec:xml_pelda_ujpartner|XML partner kezeles]]