Usługi sieciowe REST @ L.V. Expertise X3

Wprowadzenie

Serwer XTEND udostępnia programistom AJAX twa rodzaje usług sieciowych REST, które mogą zostać wywołane bezpośrednio z przeglądarki poprzez zapytanie HTTP.

Wywołanie usługi sieciowej SOAP X3 poprzez XTEND interfejs
Wywołanie skryptu serwera

Dostęp do powyższych usług mają wyłącznie aplikacje XTEND.

Mechanizm ten bierze pod uwagę wyłącznie te zapytania REST, które są powiązane z sesją XTEND poprzez plik cookie (lub ustawienia adresu URL) JSESSIONID.

Usługi XTEND REST są dostępne wyłącznie na serwerze XTEND.

Zawierają one w sobie wywołanie usług sieciowych SOAP X3.

Struktury danych REST wymieniane za transfer ustawień (klucze i dane) oraz zwrot wyników (dane i komunikaty) są takie same, jak w przypadku usług SOAP.

Inny jest tylko protokół wymiany z klientem.

Uwaga dotycząca usług sieciowych SOAP X3

Poniższa część przedstawia dostępne usługi sieciowe SOAP X3 Web wraz z powiązanymi z nimi strukturami danych.

Przed rozpoczęciem korzystania z usług XTEND REST wymagana jest znajomość usług sieciowych SOAP X3 Web.

Ustawienia wywołań

Ustawienia wymagane

Kontekst wywołania CAdxCallContext callContext
Zawiera on informacje dotyczące logowania do X3 oraz dane na temat puli połączeń realizujących zapytanie.
Nazwa publikacji usługi sieciowej String publicName zdefiniowana w momencie publikacji

public CAdxCallContext {
//kod języka X3
String codeLang;
//kod użytkownika X3
String codeUser;
//hasło X3
String password;
//Alias puli połączeń na serwerze usług sieciowych
String poolAlias;
//Ustawienia konfiguracji (ciąg zapytania)
String requestConfig;
}

Ustawienia adxwss.optreturn=JSON/XML zapytania string requestConfig wskazuje na rodzaj wyniku (domyślnie XML).

XML i JSON rozpoznawane są przez usługę sieciową automatycznie, w momencie wprowadzania.

Opcje JSON

Format JSON proponuje możliwe opcje mające na celu przefiltrowanie danych przesłanych przez usługę sieciową.

Opcje te są zdefiniowane:

w zapytaniu string requestConfig poprzez ustawienia adxwss.optjson
requestConfig=adxwss.optreturn=JSON&adxwss.optjson={'OPTIONS':'noGoups'}
lub w ustawieniach JSON obiektu bądź podprogramu poprzez pole '_JSONOPT'
Patrz: ustawienia wywołań JSON

Opcją JSON jest obiekt JSON posiadający co najmniej jedno z poniższych pól.
{
OPTIONS:['nolabels','noclobs','nogroups','norows'],
LANG:'ENG',
EXCLUDEGRP:['GRP1','GRP2'],
INCLUDEGRP:['GRP1','GRP2'],
EXCLUDEFLD:['FLD1','FLD2'],
INCLUDEFLD:['FLD1','FLD2']
}

OPCJE

noGroups
Grupy publikacji nie są zwracane
Każde ustawienie podprogramu lub pola obiektu stanowi Tabelę ciągu.

noRows
Brak wierszy w tabelach o wymiarze>1
Każde ustawienie podprogramu lub pola obiektu stanowi Tabelę ciągu.

noLabels
Lokalne menu nie zawierają etykiet

noClobs
Pola clob nie są odsyłane

Pole OPTION (OPCJE) dopuszcza zarówno tabelę ustawień jak i pojedyncze ustawienia (Ciąg)

EXCLUDEGRP
Wyklucza wspomniane grupy

INCLUDEGRP
Uwzględnia wspomniane grupy

EXCLUDEFLD
Wyklucza wspomniane pola

EXCLUDEFLD
Uwzględnia wspomniane pola

Pola INCLUDE* i EXCLUDE* dopuszczają zarówno Tabelę ciągów jak i pojedynczy Ciąg

Ustawienia kluczy obiektów X3

Ustawienia CAdxParamKeyValue objectKeys metod obiektów X3 wymagające stosowania kluczy (Odczyt/Zapytanie...).

Jest to tabela kodów Pola/wartości

klasy publicznej CAdxParamKeyValue{
private String key;
private String value;
}

Ustawienia danych

Ustawienia String objectXml obiektu X3 lub String inputXml zawierają dane obiektu lub ustawienia podprogramu w formacie XML lub JSON.

Format JSON został dodany na potrzeby aplikacji AJAX.

Przykład formatu wywołania usługi sieciowej logowania AXTDLOGIN na witrynie ASAMPLE.

Ustawienia JSON

Opcja JSON w ustawieniach wywołania: nogroups, norows
{
_JSONOPT:{OPTIONS:['nogroups', 'norows']},
AXPARCOD:['SITCOD', 'USRLANG'],
AXPARVAL:['FDBTEST', 'FRA'],
AXUSERCODE:'DIS001',
AXPWD:'adonix'
}

Ustawienia XML

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

Struktura ustawień danych podprogramu

Pola <FLD NAME='FieldName'> reprezentują ustawienia podprogramu i są dołączone do grupy publikacji

Grupy publikacji są zdefiniowane w rekordach usługi sieciowej powiązanej z rekordem podprogramu.

Są one reprezentowane przez węzły <GRP ID='IdGroup'> w przypadku ustawień o wymiarze 1 oraz <TAB ID='IdGroup'> w przypadku ustawień o wymiarze >1.

Węzeł <LIN> przegrupowuje pola w obrębie tej samej tabeli, posiadające taki sam indeks.

Ustawienia JSON używają tej samej struktury, nie wymagają jednak wykorzystywania grup publikacji.

Podprogram XML

<PARAM>
<GRP ID=’GRP1’>
<FLD NAME=’CHAMP’>Value</FLD>
</GRP>
<TAB ID=’GRP2’>
<LIN>
<FLD NAME=’CHAMP1’>Value1</FLD>
<FLD NAME=’CHAMP2’>Value1</FLD>
</LIN>
<LIN>
<FLD NAME=’CHAMP1’>Value1</FLD>
<FLD NAME=’CHAMP2’>Value2</FLD>
</LIN>
</TAB>
</PARAM>

Podprogram JSON

/*--- Bez grup ---*/
{
CHAMP:'Value',
CHAMP1:['Value1','Value2'],
CHAMP2:['Value1','Value2']
}
/*--- Z grupami ---*/
{
GRP1:{
CHAMP:'Value'
},
GRP2:[
{
CHAMP1:'Value1',
CHAMP2:'Value1'
},
{
CHAMP1:'Value2',
CHAMP2:'Value2'
}
]
}

Struktura ustawień danych obiektu X3

Wykorzystywana jest taka sama struktura, jak w przypadku podprogramu, jednak nazwy grup są zakodowane w zależności od zlokalizowania wybranych elementów na ekranie.

Tryb JSON nie wymaga określenia nazw grup.

Programista może sam zdecydować, czy chce określić nazwę grupy w przypadku używania pola obiektu X3, którego sama tylko nazwa nie wystarcza do jej identyfikacji.

W jednym obiekcie X3 może występować kilka pól o takiej samej nazwie.

Przykład kolejności SOH
SOH4_1 (wiersze kolejności) odpowiadają pierwszej sekcji czwartego ekranu

Obiekt XML

Obiekt JSON

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

Usługi

/*--------------- Wywołanie PODPROGRAMU ---------------*/
public CAdxResultXml run(
CAdxCallContext callContext,
String publicName,
String inputXml) throws Exception;

/*--------------- Wywołanie podOBIEKTU X3 ---------------*/
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;
}

Wynik

Wywołanie usługi sieciowej zwraca zawsze obiekt wyniku CAdxResultXml zawierający:

Dane obiektu lub ustawienia podprogramu w formacie XML lub JSON
String resultXml
komunikaty aplikacji o błędach, ostrzeżeniach i informacjach
CAdxMessage messages
informacje techniczne na temat wykonania podprogramu
CAdxTechnicalInfos technicalInfos

Błędy aplikacji X3 nie są zwracane jako wyjątki.

Format JSON nie uwzględnia ustawień typu BLOB, zawierających dane binarne.

public class CAdxResultXml{
public CAdxMessage[] messages;
public String resultXml;
public int status;
public CAdxTechnicalInfos technicalInfos;
}
public class CAdxMessage {
public String message;
//„1”:Informacja - „2”:Ostrzeżenie - „3”:Błąd
public String type;
}

Przykład wyniku wywołania usługi sieciowej logowania AXTDLOGIN na witrynie ASAMPLE.

Wynik JSON

Opcje JSON: norows i 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']
}

Wynik XML

<RESULT>
<TAB DIM='20' ID='AX_PAR' size="'2'><BR/"> <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'><BR/"> <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'><BR/"> <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'><BR/"> <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>

Usługi sieciowe XTEND REST

Zasada działania

Poniżej przedstawione zostały poszczególne kroki przetwarzania zapytania REST:

1. Przyjęcie zapytania HTTP przez serwlet ajax serwera XTEND

2. Odszukanie powiązanej sesji XTEND

poprzez cookie lub przez ustawienia JSESSIONID zapytania
-> Błąd w przypadku braku możliwości odnalezienia sesji

3. Analiza adresu URL w celu pozyskania informacji na temat witryny XTEND oraz typu usługi

W ramach sesji XTEND możliwe jest otwarcie jednocześnie kilku witryn
-> Błąd w przypadku braku możliwości odnalezienia witryny

4. Wykonanie skryptu serwera lub wywołanie usługi sieciowej X3 SOAP

Przetwarzanie skryptu serwera

1. Odczyt ścieżki dostępu z adresu URL

2. Odczyt i kompilacja skryptu JavaScript

3. Wykonanie skryptu

Skrypt ten umożliwia dostęp do danych sesji i wywołanie usług sieciowych X3 SOAP
Instrukcja wydruku skryptu służy do przesłania odpowiedzi (XML, JSON, HTML...)

Przetwarzanie wywołania usługi sieciowej X3 SOAP

1. Odczyt kodu interfejsu XTEND z adresu URL

Interfejs ten odnosi się do usługi sieciowej SOAP
-> Błąd jeżeli interfejs nie został zadeklarowany na witrynie

2. Tworzenie ustawień wywołania

Dane XML lub JSON są odczytywane z treści zapytania
Klucze są odczytywane z „Ciągu Zapytania”
Typ oczekiwanego wyniku - XML lub JSON - odczytywany jest z nagłówka HTTP xtd-accept

3. Tworzenie kontekstu wywołania dla usługi sieciowej SOAP

Entry point (adres URL) podany jest przez witrynę XTEND (pula usług sieciowych strony lub interfejsu)
Sesja XTEND podaje kod użytkownika X3 oraz hasło języka

4. Wywołanie usługi serwisowej SOAP

5. Tworzenie wyniku

Komunikaty przenoszone są do nagłówka HTTP
xtd-msg-error, xtd-msg-warning,xtd-msg-info
Dane XML/JSON przesłane przez usługę sieciową SOAP są przenoszone, bez zmian, do treści zapytania

Format adresu URL

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

Metoda HTTP POST lub GET

x3sol
Kod rozwiązania X3

x3folder
Kod folderu X3

xtdsite
Kod witryny XTEND

typ
INT wywołanie XTEND interfejs
SCRIPT wywołania XTEND skrypt serwera

identyfikator
Kod interfejsu
lub
Ścieżka dostępu do skryptu z uwzględnieniem katalogu skryptu serwera witryny XTEND

metoda
Kod metody obiektu X3
QUERY, R Odczyt, S Zapis, M Modyfikacja,D Usunięcie

Ustawienia
Ciąg zapytania, mogący zawierać:

Pola kluczy obiektu X3
Ustawienia lewej listy
Opcje JSON dostępne poprzez key _JSONOPT, o ile nie zostały one wykorzystane w ustawieniach danych

Przykłady

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

Podprogram
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/AXTDLOGIN

Obiekt X3 - Odczyt
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/R?FRMCOD=0901000002
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Lewa lista obiektów X3
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Wysyłanie danych

Ustawienia danych rodzaju inne niż te zawarte w ciągu zapytania są wykorzystywane w treści zapytania HTTP.

Format ustawień wywołania interfejsu XTEND podany jest w ContentType zapytania HTTP:

application/json
Struktura danych musi być zgodna z oczekiwanym formatem
application/xml
Dane XML muszą być zgodne z oczekiwanym formatem
application/x-www-form-urlencoded
W tym przypadku, lista pól/wartości traktowana jest jako obiekt JSON zgodny z oczekiwanym formatem

Domyślnym ContentType jest application/json

Obowiązkowym formatem danych wywołania skryptu serwera jest application/json.

Wynik

Podczas wywoływania interfejsu XTEND możliwe jest żądanie zwrotu w formacie XML (applcation/xml) lub JSON (application/json) przez określenie wartości xtd-Accept dedykowanego dla nagłówka HTTP.

Domyślnym rodzajem mime jest application/xml.

Zapytanie przesyła ustawienia podprogramu lub dane obiektu X3 w wymaganym formacie.

Format danych przesłanych w wywołaniu skryptu serwera jest dowolny.

Komunikaty aplikacji

Komunikaty aplikacji przesyłane są do trzech konkretnych nagłówków HTTP.

xtd-msg-error

Zawiera komunikaty o błędzie

xtd-msg-warning

Zawiera komunikaty o ostrzeżeniach

xtd-msg-info

Zawiera komunikaty informacyjne

Błąd aplikacji X3 przetwarzany jest jako wyjątek

Wyjątki

Błędy aplikacji X3 oraz błędy kompilacji/wykonania skryptów serwera przesyłane są w formie błędu HTTPo kodzie 600.

Wyjątki JAVA przesyłane są w formiebłędu HTTP o kodzie 500.

Treść zapytania zawiera opis (ContentType=text/plain) błędu, zależny od rodzaju wyjątku.

W przypadku błędu X3 nagłówek xtd-msg-error HTTP zawiera wiadomość o błędzie.