Esystem XML Interface version 0.3

XML szerkezete

Kliens üzenete a szerver felé

<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>

Szerver üzenete a kliens felé

<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>

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)

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

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

framename_element

A frame neve.

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

<framename>main</framename>

info_message_element

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

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

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

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

record_element

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

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

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 ametadata 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.

name_element

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

Azsession elementben szereplő mezőnevek nem egyezhetnek meg sem másiksession elemenetbeli sem bármely data elementbeli mezőnévvel

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

<name>beosztas</name>

value_element

A mező értéke.

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

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

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.

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 asession 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.

<type>text</type>

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

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.

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>

Példák

• XML Egyszerűsített lekérdezések
• XML Jelszó alapú bejelentkezés
• XML Raktárlekérdezés
• XML alapú rendelés cikktörzsből
• XML partner kezeles