REST-Webservices 

Einführung

Auf dem XTEND-Server stehen den Entwicklern von AJAX-Anwendungen zwei Arten von REST-Webservices zur Verfügung, die direkt per HTTP-Abfrage aus dem Browser aufgerufen werden können.

  • Aufruf eines X3-SOAP-Webservice über eine XTEND- Schnittstelle Aufruf eines
  • Skriptservers

Diese Services stehen lediglich den XTEND-Anwendungen zur Verfügung.

Die Engine verarbeitet nur REST-Abfragen mit einer über das Cookie (oder den URL-Parameter) JSESSIONID zugeordneten XTEND-Sitzung.

Die XTEND-REST-Services sind nur auf dem XTEND-Server verfügbar.

Sie kapseln den Aufruf des X3-SOAP-Webservice.

Die zur Übergabe der Parameter (Schlüssel und Daten) und zur Ergebnisrückgabe (Daten und Meldungen) ausgetauschten REST-Datenstrukturen entsprechen denen der SOAP-Services.

Nur das Austauschprotokoll mit dem Client unterscheidet sich davon.

X3-SOAP-Webservices

In diesem Absatz werden die verfügbaren X3-SOAP-Webservices und die zugehörigen Datenstrukturen allgemein beschrieben.

Zur Verwendung der XTEND-REST-Services sind Kenntnisse der X3-SOAP-Webservice unerlässlich.

Aufrufparameter

Obligatorische Parameter
  • Aufrufkontext CAdxCallContext callContext
    umfasst die X3-Benutzerdaten und den Verbindungspool, von dem die Abfrage verarbeitet wird
  • Name, unter dem der Webservice String publicName veröffentlicht wurde (bei der Veröffentlichung definiert)

public CAdxCallContext {
    // X3-Sprachcode
    String codeLang;
    // X3-Benutzercode
    String codeUser;
    // X3-Passwort
    String password;
    // Alias des Verbindungspools auf dem Webservice-Server
    String poolAlias;
    // Konfigurationsparameter (query string)
    String requestConfig;
}

Der Parameter adxwss.optreturn=JSON/XML der Abfrage string requestConfig gibt den Ergebnistyp an (per Default XML).

Der Webservice-Server ermittelt automatisch bei der Eingabe das XML- oder JSON-Format.

JSON-Optionen

Im JSON-Format stehen Optionen zum Filtern der vom Webservice zurückgegebenen Daten zur Verfügung.

Diese Optionen werden übergeben:

  • entweder in der Abfrage string requestConfig im Parameter adxwss.optjson
    requestConfig=adxwss.optreturn=JSON&adxwss.optjson={"OPTIONS":"noGoups"}
  • oder als JSON-Parameter des Objekts oder Unterprogramms im Attribut "_JSONOPT"
    Siehe Beispiel für die JSON-Aufrufparameter

Die JSON-Option ist ein JSON-Objekt, das mindestens eines der folgenden Attribute umfasst.
{
    OPTIONS:["nolabels","noclobs","nogroups","norows"],
    LANG:"FRA",
    EXCLUDEGRP:["GRP1","GRP2"],
    INCLUDEGRP:["GRP1","GRP2"],
    EXCLUDEFLD:["FLD1","FLD2"],
    INCLUDEFLD:["FLD1","FLD2"]
}

OPTIONEN

noGroups
    Keine Veröffentlichungsgruppen als Rückgabe
    Jeder Unterprogrammparameter und jeder Objektattributparameter ist eine String-Tabelle

noRows
    Keine Zeilen in Tabellen mit dim > 1
    Jeder Unterprogrammparameter und jeder Objektattributparameter ist eine String-Tabelle

noLabels
    Keine Labels für die Lokalen Menüs

noClobs
    Die Clob-Attribute werden nicht zurückgegeben

Die Spalte OPTION akzeptiert eine Parametertabelle oder einen einzelnen Parameter (String)

EXCLUDEGRP
    Schließt die genannten Gruppen aus

INCLUDEGRP
    Schließt die enthaltenen Gruppen ein

EXCLUDEFLD
    Schließt die genannten Attribute aus

INCLUDEFLD
    Schließt die genannten Attribute ein

Die Attribute INCLUDE* und EXCLUDE* akzeptieren String-Tabellen und Strings

X3-Schlüsselobjektparameter

Parameter CAdxParamKeyValue objectKeys für die X3-Objektmethoden, die Schlüssel benötigen (Read / Query etc.).

Dabei handelt es sich um eine Tabelle Spaltencode / Wert.

public class CAdxParamKeyValue{
    private String key;
    private String value;
}

Datenparameter

Die X3-Objektparameter String objectXml und String inputXml umfassen die Unterprogrammobjektdaten oder -parameter im XML- oder im JSON-Format.

Das JSON-Format wurde für AJAX-Anwendungen hinzugefügt.

Beispiel für das Format beim Aufruf eines Webservice für die Anmeldung AXTDLOGIN an die Website ASAMPLE.

JSON-Parameter

JSON-Option in den Aufrufparametern: nogroups, norows
{
    _JSONOPT:{OPTIONS:["nogroups", "norows"]},
    AXPARCOD:["SITCOD", "USRLANG"],
    AXPARVAL:["FDBTEST", "FRA"],
    AXUSERCODE:"DIS001",
    AXPWD:"adonix"
}

XML-Parameter

<PARAM>
    <TAB ID="AX_PAR">
        <LIN NUM="1">
            <FLD NAME="AXPARCOD">SITCOD</FLD>
            <FLD NAME="AXPARVAL">FDBTEST</FLD>
        </LIN>
        <LIN NUM="2">
            <FLD NAME="AXPARCOD">USRLANG</FLD>
            <FLD NAME="AXPARVAL">FRA</FLD>
        </LIN>
    </TAB>
    <GRP ID="AXLOG_PAR">
        <FLD NAME="AXUSERCODE">DIS001</FLD>
        <FLD NAME="AXPWD">adonix</FLD>
    </GRP>
</PARAM>

Datenparameterstruktur Unterprogramm

Die Attribute <FLD NAME="FieldName"> stehen für die Unterprogrammparameter und sind der Veröffentlichungsgruppe zugeordnet.

Die Veröffentlichungsgruppen sind in den Webservice-Daten der Unterprogrammdaten definiert.

Sie werden durch den Knoten <GRP ID="IdGroup"> (eindimensionale Parameter) bzw. <TAB ID="IdGroup"> (mehrdimensionale Parameter) repräsentiert.

Die Spalten derselben Tabellengruppe mit demselben Index sind im Knoten <LIN> gebündelt.

In die JSON-Parameter wird dieselbe Struktur übernommen, die Verwendung von Veröffentlichungsgruppen ist jedoch nicht obligatorisch.

XML-Unterprogramm

<PARAM>
    <GRP ID=’GRP1’>
        <FLD NAME=’CHAMP’>Valeur</FLD>
    </GRP>
    <TAB ID=’GRP2’>
        <LIN>
            <FLD NAME=’CHAMP1’>Valeur1</FLD>
            <FLD NAME=’CHAMP2’>Valeur1</FLD>
        </LIN>
        <LIN>
            <FLD NAME=’CHAMP1’>Valeur1</FLD>
            <FLD NAME=’CHAMP2’>Valeur2</FLD>
        </LIN>
    </TAB>
</PARAM>

JSON-Unterprogramm

/*--- Ohne die Gruppen ---*/
{
    CHAMP:"Valeur",
    CHAMP1:["Valeur1","Valeur2"],
    CHAMP2:["Valeur1","Valeur2"]
}
/*--- Mit den Gruppen ---*/
{
    GRP1:{
        CHAMP:"Valeur"
    },   
    GRP2:[
        {
            CHAMP1:"Valeur1",
            CHAMP2:"Valeur1"          
        },
        {
            CHAMP1:"Valeur2",
            CHAMP2:"Valeur2"       
        }
    ]
}

X3-Objektdatenparameterstruktur

Dieselbe Struktur wie bei den Unterprogrammen, jedoch richtet sich die Benennung der Gruppennamen nach der Position im Maskenblock.

Im JSON-Modus müssen die Gruppennamen nicht angegeben werden.

Es wird dem Entwickler überlassen, den Gruppennamen anzugeben. Dies wird er tun, wenn er ein X3-Objektattribut verwenden möchte, dessen Name nicht alleine für die Identifizierung ausreicht.

Ein X3-Objekt kann mehrere Attribute desselben Namens umfassen.

Beispiel für den SOH-Befehl
    SOH4_1 (Befehlszeile) entspricht dem 1. Block in der 4. Maske.

XML-Objekt

<PARAM>
    <GRP ID="SOH0_1">
        <FLD NAME="BPCORD">DIS001</FLD>
        <FLD NAME="SOHTYP">WEB</FLD>   
        <FLD NAME="SALFCY">ASN</FLD>
    </GRP>
    <GRP ID="SOH2_1">
        <FLD NAME="STOFCY">ASN</FLD>
    </GRP>
    <TAB ID="SOH4_1">
        <LIN>
            <FLD NAME="ITMREF">CUB100</FLD>
            <FLD NAME="QTY">50</FLD>
        </LIN> 
        <LIN>
            <FLD NAME="ITMREF">CD100</FLD>
            <FLD NAME="QTY">10</FLD>
        </LIN>
    </TAB>
</PARAM>

JSON-Objekt

{
    BPCORD:"DIS001",
    SOHTYP:"WEB",
    SALFCY:"ASN",
    STOFCY:"ASN",
    ITMREF:["CUB100","CD100"],
    ITMREF:["50","10"]
}

Services

/*--------------- Aufruf eines UNTERPROGRAMMS ---------------*/
public CAdxResultXml run(
    CAdxCallContext callContext,
    String publicName,
    String inputXml) throws Exception;
   
/*--------------- Aufruf eines X3-Unterobjekts---------------*/
public CAdxResultXml save(
    CAdxCallContext callContext,
    String publicName,
    String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml delete(
    CAdxCallContext callContext,
    String publicName,
    CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml read(
    CAdxCallContext callContext,
    String publicName,
    CAdxParamKeyValue[] objectKeys) throws Exception;  
//------------------------------------------
public CAdxResultXml query(
    CAdxCallContext callContext,
    String publicName,
    CAdxParamKeyValue[] objectKeys,
    int listSize) throws Exception; 
//------------------------------------------
public CAdxResultXml modify(
    CAdxCallContext callContext,
    String publicName,
    CAdxParamKeyValue[] objectKeys,
    String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
    CAdxCallContext callContext,
    String publicName,
    String actionCode,
    CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
    CAdxCallContext callContext,
    String publicName,
    String actionCode
    String objectXml) throws Exception;
}

Ergebnis

Der Aufruf eines Webservice gibt immer ein CAdxResultXml-Ergebnisobjekt zurück, das folgende Elemente umfasst:

  • Daten des Unterprogrammobjekts- oder der Unterprogrammparameter im XML- oder im JSON-Format
    String resultXml
  • Fehlermeldungen, Warnungen und Hinweise der Anwendung
    CAdxMessage messages
  • technische Hinweise zur Ausführung des Unterprogramms
    CAdxTechnicalInfos technicalInfos

X3-Anwendungsfehler werden nicht als Ausnahmen zurückgegeben.

Das JSON-Format ignoriert Parameter vom Typ Blob, die Binärdaten enthalten.

public class CAdxResultXml{
    public CAdxMessage[] messages;
    public String resultXml;
    public int status;
    public CAdxTechnicalInfos technicalInfos;
}
public class CAdxMessage {
    public String message;
    //"1":Information - "2":Warning - "3":Erreur
    public String type;
}

Beispiel für das Ergebnis nach dem Aufruf eines Webservice für die Anmeldung AXTDLOGIN an die Website ASAMPLE.

JSON-Ergebnis

JSON-Optionen: norows und nogroups

{
AXPARCOD:["SITCOD","USRLANG"],
AXPARVAL:["FDBTEST","FRA"]
AXUSERCODE:"DIS001",
AXPWD:"adonix",
AXUSERPROF:"B2B",
AX3SOL:["SOLPAIE","X3V5","XTENDV2"],
AX3FLDR:["PAIE","X3TESTV5","DEMOFRA"],
AX3LANG:["FRA","FRA","FRA"],
AX3USER:["XTEND","JPJ1","OG"],
AXLOGCOD:["NAME","FIRSTNAME","EMAIL","PHONE"],
AXLOGVAL:["DALBO","Frédéric","../FCT/mailto:fdb@sg.com","0001020304"]
SHIPADR1:["Sage Lyon new","Sage MGE","Sage PARIS"],
SHIPCITY:["LYON","Echirolles","PARIS"],
SHIPZIP:["69443","38130","75834"]
}

XML-Ergebnis

<RESULT>
    <TAB DIM="20" ID="AX_PAR" SIZE="2">
        <LIN NUM="1">
            <FLD NAME="AXPARCOD" TYPE="Char">SITCOD</FLD>
            <FLD NAME="AXPARVAL" TYPE="Char">FDBTEST</FLD>
        </LIN>
        <LIN NUM="2">
            <FLD NAME="AXPARCOD" TYPE="Char">USRLANG</FLD>
            <FLD NAME="AXPARVAL" TYPE="Char">FRA</FLD>
        </LIN>
    </TAB>
    <GRP ID="AXLOG_PAR">
        <FLD NAME="AXUSERCODE" TYPE="Char">DIS001</FLD>
        <FLD NAME="AXPWD" TYPE="Char">adonix</FLD>
        <FLD NAME="AXUSERPROF" TYPE="Char">B2B</FLD>
    </GRP>
    <TAB DIM="10" ID="AXLOG_X3" SIZE="3">
        <LIN NUM="1">
            <FLD NAME="AX3SOL" TYPE="Char">SOLPAIE</FLD>
            <FLD NAME="AX3FLDR" TYPE="Char">PAIE</FLD>
            <FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
            <FLD NAME="AX3USER" TYPE="Char">XTEND</FLD>
        </LIN>
        <LIN NUM="2">
            <FLD NAME="AX3SOL" TYPE="Char">X3V5</FLD>
            <FLD NAME="AX3FLDR" TYPE="Char">X3TESTV5</FLD>
            <FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
            <FLD NAME="AX3USER" TYPE="Char">JPJ1</FLD>
        </LIN>
        <LIN NUM="3">
            <FLD NAME="AX3SOL" TYPE="Char">XTENDV2</FLD>
            <FLD NAME="AX3FLDR" TYPE="Char">DEMOFRA</FLD>
            <FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
            <FLD NAME="AX3USER" TYPE="Char">OG</FLD>
        </LIN>
    </TAB>
    <TAB DIM="50" ID="AXLOG_RES" SIZE="4">
        <LIN NUM="1">
            <FLD NAME="AXLOGCOD" TYPE="Char">NAME</FLD>
            <FLD NAME="AXLOGVAL" TYPE="Char">DALBO</FLD>
        </LIN>
        <LIN NUM="2">
            <FLD NAME="AXLOGCOD" TYPE="Char">FIRSTNAME</FLD>
            <FLD NAME="AXLOGVAL" TYPE="Char">Frédéric</FLD>
        </LIN>
        <LIN NUM="3">
            <FLD NAME="AXLOGCOD" TYPE="Char">EMAIL</FLD>
            <FLD NAME="AXLOGVAL" TYPE="Char">fdb@sg.com</FLD>
        </LIN>
        <LIN NUM="4">
            <FLD NAME="AXLOGCOD" TYPE="Char">PHONE</FLD>
            <FLD NAME="AXLOGVAL" TYPE="Char">0001020304</FLD>
        </LIN>
    </TAB>
    <TAB DIM="20" ID="LOGINSHIP" SIZE="3">
        <LIN NUM="1">
            <FLD NAME="SHIPADR1" TYPE="Char">Sage Lyon new</FLD>
            <FLD NAME="SHIPCITY" TYPE="Char">LYON</FLD>
            <FLD NAME="SHIPZIP" TYPE="Char">69443</FLD>
        </LIN>
        <LIN NUM="2">
            <FLD NAME="SHIPADR1" TYPE="Char">Sage MGE</FLD>
            <FLD NAME="SHIPCITY" TYPE="Char">Echirolles</FLD>
            <FLD NAME="SHIPZIP" TYPE="Char">38130</FLD>
        </LIN>
        <LIN NUM="3">
            <FLD NAME="SHIPADR1" TYPE="Char">Sage PARIS</FLD>
            <FLD NAME="SHIPCITY" TYPE="Char">PARIS</FLD>
            <FLD NAME="SHIPZIP" TYPE="Char">75834</FLD>
        </LIN>
    </TAB>
</RESULT>

XTEND-REST-Webservices

Funktionsweise

Hier die verschiedenen Verarbeitungsschritte einer REST-Abfrage:

1. Empfang der HTTP-Abfrage durch das AJAX-Servlet des XTEND-Servers

2. Suche nach der zugehörigen XTEND-Sitzung

Über das Cookie oder den Parameter der JSESSIONID-Abfrage
-> Fehler, wenn keine Sitzung gefunden wurde

3. Analyse der URL, um die Adresse der XTEND-Website und den Servicetyp abzuleiten

Pro XTEND-Sitzung können mehrere Websites geöffnet sein
-> Fehler, wenn keine Website gefunden wurde

4. Ausführung des Serverskripts oder Aufruf des X3-SOAP-Webservice

Verarbeitung des Serverskripts

1. Lesen des Zugriffspfads in der URL

2. Lesen und Kompilieren des JavaScript-Skripts

3. Ausführung des Skripts

      • Das Skript kann auf die Sitzungsdaten zugreifen und X3-SOAP-Webservices aufrufen.
Für die Rückgabe der Antwort wird die Print-Anweisung des Skripts verwendet (XML, JSON, HTML)

Verarbeitung des Aufrufs des X3-SOAP-Webservice.
1. Lesen des XTEND-Schnittstellencodes in der URL

Die Schnittstelle enthält eine Referenz auf einen SOAP-Webservice

      • -> Fehler, wenn die Schnittstelle in der Website nicht deklariert ist
      • 2. Aufbau der Aufrufparameter
      • Die XML- bzw. JSON-Daten werden aus dem Abfragecode gelesen

Die Schlüssel werden aus dem 'Query String' gelesen

      • Der erwartete Ergebnistyp (XML oder JSON) wird aus dem HTTP-Header xtd-accept gelesen

3. Aufbau des Aufrufkontexts für den SOAP-Webservice

Der Eingabepunkt (URL) ist durch die XTEND-Website gegeben (Webservice-Pool der Website oder der Schnittstelle)

      • X3-Benutzercode, Passwort und Sprache sind durch die XTEND-Sitzung gegeben
        4. Aufruf des SOAP-Webservice
      • 5. Aufbau des Ergebnisses

Die Meldungen werden im HTTP-Header übergeben

xtd-msg-error, xtd-msg-warning,xtd-msg-info

Die XML- bzw. JSON-Daten werden vom SOAP-Webservice zurückgegeben und unverändert in den Abfragecode übernommen

URL-Format
http://host:port/xtend/ajax/x3sol/x3folder/xtdsite/type/id[/méthode][?Paramètres]

HTTP-Methoden POST und GET
x3sol

    X3-Lösungscode
x3folder

    X3-Ordnercode
xtdsite     XTEND-Website-Code Typ     INT
für den Aufruf einer XTEND- Schnittstelle     SCRIPT für den Aufruf eines XTEND-

Skriptservers
id
    Schnittstellencode
    oder

    Zugriffspfad auf das Skript im Skriptverzeichnis des Servers der XTEND-Website
Methode
    X3-Objektmethodencode     QUERY, R Read, S Save, MModify, D

Delete
Parameter

    •     Query String kann umfassen:
    • Schlüsselfelder eines X3-Objekts
    • Parameter einer Auswahlliste links
JSON-Optionen über den Schlüssel _JSONOPT, wenn diese nicht in den Parametern übergeben werden

Beispiele
Skript

    http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/SCRIPT/ajaxTest1.js
Unterprogramm    

http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/AXTDLOGIN
X3-Objekt - Read  
  http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/R?FRMCOD=0901000002

    &_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D
Auswahlliste links X3-Objekt  
  http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*

    &_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Datenversand Alle anderen Datenparameter neben dem Abfragestring werden im Code

der HTTP-Abfrage übergeben.

  • Das Aufrufparameterformat der XTEND-Schnittstellen ist über den ContentType der HTTP-Abfrage gegeben.
    application/json
  • Die Datenstruktur muss dem erwarteten Format entsprechen
    application/xml
  • Die XML-Daten müssen dem erwarteten Format entsprechen
    application/x-www-form-urlencoded

In diesem Fall wird die Liste der Felder / Werte als JSON-Objekt betrachtet, das dem erwarteten Format entspricht Per Default ist der ContentType application/json.

Das Datenformat beim Aufruf eines Skriptservers muss application/jsonlauten

Ergebnis

Beim Aufruf von XTEND-Schnittstellen kann ein XML- oder JSON-Rückgabeformat verlangt werden (application/xml bzw. application/json). Hierfür ist der entsprechende HTTP-Header xtd-Accept zu belegen.

Per Default ist der Mime-Type application/xml.

Die Abfrage gibt die Unterprogrammparameter oder die X3-Objektdaten im geforderten Format zurück.

Das vom Serverskript zurückgegebene Datenformat ist frei wählbar.

Anwendungsmeldungen

Die Anwendungsmeldungen werden in den drei hierfür vorgesehenen HTTP-Headern zurückgegeben.

xtd-msg-error

Enthält die Fehlermeldungen

xtd-msg-warning

Enthält die Warnungen

xtd-msg-info

Enthält die Hinweise

Eine X3-Anwendungsfehlermeldung wird wie eine Ausnahme behandelt

Ausnahmen

Die X3-Anwendungsfehler und die Kompilierungs- / Ausführungsfehler der Serverskripte werden als HTTP-Fehler600zurückgegeben.

Die JAVA-Ausnahmen werden als HTTP-Fehler 500zurückgegeben.

Der Abfragecode umfasst eine Beschreibung (ContentType=text/plain) des Fehlers, die sich nach dem Ausnahmetyp richtet.

X3-Fehlermeldungen sind im HTTP-Header xtd-msg-error enthalten.