Wprowadzenie
Aby wyeksportować obiekty do zewnętrznych aplikacji z konfigurowalnej aplikacji typu Lista, dla każdej takiej aplikacji należy opracować aplikację o typie Usługa RPC i o zastosowaniu Usługa REST. Dokument opisuje sposób tworzenia tej aplikacji i łączenia jej z powiązaną aplikacją typu Lista.
Grupa docelowa
- Deweloperzy
Definicje pojęć
Zgodność z REST – REST to skrót od Representational State Transfer. Zgodność z REST oznacza, że aplikacje i usługi sieciowe komunikują się ze sobą w prosty sposób. W tym celu wykorzystuje się np. HTTP i zdefiniowane przy jego pomocy operacje. Usługa sieciowa jest bezpośrednio dostępna poprzez URI, a wszystkie informacje znajdują się w HTTP. Gwarantuje to, że żaden stan aplikacji nie musi być przechowywany ani na kliencie, ani na serwerze.
Usługa sieciowa obsługuje komunikację między różnymi aplikacjami działającymi na różnych platformach. Usługa sieciowa to aplikacja, którą można jednoznacznie zidentyfikować za pomocą Uniform Resource Identifier (URI). Bezpośrednia interakcja odbywa się za pośrednictwem wiadomości opartych na xml.
Opis
Usługa sieciowa zgodna z REST może być wywoływana przez klientów REST, w tym przez przeglądarki.
Dzięki takiej usłudze sieciowej obiekty, które są wyszukiwane w konfigurowalnej aplikacji typu Lista, mogą być również wyszukiwane przez aplikację zewnętrzną. Wyszukiwanie może odbyć się na dwa sposoby:
- Aplikacja zewnętrzna bezpośrednio z systemu zapytuje o obiekty przy użyciu URI zgodnym z REST.
- Obiekty są zapisywane w pliku zgodnym z REST przy użyciu aplikacji w tle, który jest przechowywany w Repozytorium Wiedzy. Aplikacja zewnętrzna może uzyskać dostęp do pliku w Repozytorium Wiedzy.
Połączenie z konfigurowalną aplikacją typu Lista
Usługa sieciowa zgodna z REST jest automatycznie łączona z odpowiednią konfigurowalną aplikacją typu Lista, jeśli podstawowe wyszukiwania są zgodne. Umożliwia to wysyłanie zapytań do URI usługi REST w aplikacji typu Lista lub wywoływanie aplikacji w tle. Więcej informacji można znaleźć w rozdziale Połączenie usługi sieciowej zgodnej z REST i aplikacji typu Lista.
Podstawa eksportu zgodnego z REST
Eksport zgodny z REST opiera się na wyszukiwaniu konfigurowalnej aplikacji typu lista. W przeciwieństwie do konfigurowalnej aplikacji typu Lista, wyszukiwanie szczegółowe nie jest brane pod uwagę. Eksportowane są tylko te obiekty, które odpowiadają kryteriom wyszukiwania z wyszukiwania głównego. Do filtrowania dostępne są tylko pola filtra z wyszukiwania głównego.
Formaty plików
Usługa sieciowa zgodna z REST wspiera następujące formaty plików:
- XLS (MS Excel)
- CSV
- XML
- HTML
Format pliku HTML można dostosować za pomocą konwersji XSLT. W tym celu należy utworzyć plik XSLT i zapisać go w Repozytorium Wiedzy pod następującą nazwą:
- Plik XSLT specyficzny dla języka i eksportu: kstore://<A>/Documents/CockpitDataSource/html/<S>-<L>.xslt
- Plik XSLT specyficzny dla eksportu: kstore://<A>/Documents/CockpitDataSource/html/<S>.xslt
- Plik specyficzny dla języka, ale niezależny od eksportu XSLT: kstore://<A>/Documents/CockpitDataSource/html/Global-<L>.xslt
- Plik XSLT niezależny od eksportu: kstore://<A>/Documents/CockpitDataSource/html/Global.xslt
Wyjaśnienie znaczenia symboli zastępczych:
- <A> – obszar roboczy (obszar roboczy repozytorium dla wyszukiwania, które nie jest ustawione dla baz danych OLTP w obiekcie deweloperskim lub bieżący obszar roboczy OLTP).
- <S> – pełna nazwa wyszukiwania używanego w usłudze sieciowej zgodnej z REST.
- <L> – symbol języka (np. de dla niemieckiego).
Przykład pliku XSLT można znaleźć w obiekcie deweloperskim typu plik: com.cisag.sys.services.datasource.Html-transform.
Wywołanie usługi sieciowej zgodnej z REST
Usługa sieciowa zgodna z REST eksportuje obiekty z konfigurowalnej aplikacji typu Lista. Jest ona wywoływana przez oprogramowanie klienckie za pośrednictwem protokołu HTTP GET i parametryzowana za pomocą URI usługi REST. Oprócz wywoływanej usługi sieciowej zgodnej z REST, URI usługi REST zawiera również parametry kontrolujące format i zakres eksportowanych obiektów.
Zwrot wywołania HTTP zawiera obiekty zapytania z aplikacji typu lista w żądanym formacie pliku, pod warunkiem, że zwrócony został kod HTTP 200. W przeciwnym razie występuje błąd.
Tworzenie URI usługi REST w aplikacji typu Lista
URI usługi REST dla usługi sieciowej zgodnej z REST można utworzyć za pomocą akcji Kopiuj link z kryteriami wyszukiwania w konfigurowalnym kokpicie. URI zawiera kryteria wyszukiwania z konfigurowalnej aplikacji typu Lista.
Format URI usługi REST
URI usługi REST tworzone są zgodnie z następującym schematem.
- Zapis z wykorzystaniem bazy danych OLTP jako ciąg zapytania (query string): https://<sas>/services/rest/<service>/search.<extension>?<query> zapis z wykorzystaniem bazy danych OLTP w ścieżce: https://<sas>/services/<oltp>/rest/<service>/search.<extension>?<query>
Wyjaśnienie znaczenia symboli zastępczych:
- <sas> – host i port serwera aplikacji systemu ERP
- <oltp> – nazwa bazy danych OLTP, do której należy uzyskać dostęp. Jeśli dostęp do bazy danych OLTP nie jest wymagany, podawana jest wartość none.
- <service> – nazwa obiektu deweloperskiego aplikacji serwisowej
- <extension> – rozszerzenie pliku zgodnie z żądanym formatem wyjściowym (np. „xls” dla MS Excel, „ csv”, „xml”, „ htm;”)
- <query> Query-Strings – aby określić bazę danych OLTP w ciągu zapytania, należy użyć „oltp=<oltp>“. Ponadto ciągi zapytań opisane poniżej są używane do eksportu z aplikacji typu lista.
Ciągi zapytań
Ciągi zapytań opisane w artykule Interfejs dla programowalnych usług webowych są dostępne dla usług sieciowych zgodnych ze standardem REST.
Parametryzacja źródła danych odbywa się za pomocą następujących ciągów zapytań:
| Ciąg zapytania | Opis |
| Filter_<column> | Ciąg zapytania dla kolumny <column>. Kolumna musi mieć możliwość filtrowania. Używana jest techniczna nazwa kolumny. Parametr może zostać podany kilkukrotnie (dla różnych kolumn). |
| SortOrder | Wyliczenie kolumn do posortowania (techniczna nazwa kolumny) i odpowiedni kierunek sortowania (ASC lub DESC), każda oddzielona spacją.
Przykład: name ASC date DESC |
| DisplayColumns | Wyliczenie kolumn do wyeksportowania w wybranej kolejności (techniczna nazwa kolumny), oddzielonych spacją.
Jeśli parametr nie zostanie podany, wyświetlane są wszystkie kolumny. |
| PrintColumnHeader | Nagłówki kolumn są wyświetlane, jeśli ten parametr nie ma wartości lub ma wartość: true.
Nagłówki kolumn nie są wyświetlane, jeśli parametr nie został określony lub został określony z wartością false. |
| PrintSpecialParts | Z wartością UNIT_SEPARATED jednostka lub waluta jest określona w oddzielnej kolumnie dla kolumn typu danych Ilość lub Kwota. Stanowi ona również wartość domyślną.
Z wartością ONE_COLUMN wartości są wyświetlane w kolumnie. |
Tworzenie usług sieciowych zgodnych z REST
Aplikacja usługi sieciowej
Zakres funkcjonalny usługi sieciowej zgodnej z REST zależy wyłącznie od zastosowanego wyszukiwania. W związku z tym – przy użyciu istniejącej funkcji wyszukiwania – opracowanie usługi sieciowej zgodnej z REST jest bardzo proste.
Wymagane są następujące obiekty deweloperskie:
- Aplikacja
Aplikacja o typie usługa RPC ze specjalnym użyciem REST service i wprowadzonym wyszukiwaniem.
- Klasa javy usługi sieciowej
- Wyszukiwanie (wprowadzone do usługi sieciowej)
Klasa javy powinna mieć taką samą nazwę jak aplikacja. Klasa Service Bean wymagana dla programowanej usługi sieciowej jest zawarta w nadrzędnej com.cisag.pgm.services.datasource.DataSourceService jako klasa wewnętrzna. Klasa javy musi być zaimplementowana jak w poniższym przykładzie:
public class XExport extends DataSourceService {
public XExport() { super();
}
}
Klasa XExport nie może deklarować własnych metod public lub protected. Są one przeznaczone dla przyszłych rozszerzeń.
Połączenie usługi sieciowej zgodnej z REST i aplikacji typu lista
Aby konfigurowalna aplikacja typu lista mogła umożliwiać eksport za pomocą usługi sieciowej zgodnej z REST i aby dostępne było okno dialogowe Kopiuj link z kryteriami wyszukiwania, to samo wyszukiwanie musi zostać wprowadzone w obiekcie deweloperskim aplikacji typu lista oraz w obiekcie deweloperskim aplikacji usługi RPC. Wyszukiwanie nie może być wprowadzone dla więcej niż jedenej aplikacji usługi RPC. W przeciwnym wypadku w aplikacji typu lista dostępna jest tylko jedna z usług sieciowych zgodnych z REST.
Ponadto wyszukiwanie wprowadzone dla aplikacji musi używać tego samego prefiksu deweloperskiego i, jeśli jest to wymagane, pochodzić z tego samego APP co aplikacja. Należy zauważyć, że warunki te nie są weryfikowane w aplikacji: Obiekty deweloperskie.
Search-Hooks
Na zachowanie funkcji wyszukiwania można wpływać za pomocą następującego hooka:
com.cisag.pgm.search.SearchHook
Jest on wywoływany zarówno z poziomu aplikacji typu Lista oraz z poziomu usługi sieciowej zgodnej z REST. Dla każdego wyszukiwania można użyć jednej implementacji hooka.
Więcej informacji można znaleźć w JavaDoc tej klasy.
Renderery i formatery
Renderery i formatery są używane do generowania danych w odpowiednim formacie pliku. Daną kolumnę można wygenerować do postaci pliku, jeśli
- istnieje renderer lub formater lub
- kolumna bazuje na typie danych string.
Dla renderera wykorzystywana jest jednak jedynie implementacja interfejsu TextRenderer i ToolTipRenderer
Należy pamiętać, że renderer i formater są wywoływane przez usługę sieciową zgodną z REST w sesji innej niż sesja dialogowa. Jeśli kolumna nie może zostać wygenerowana do postaci pliku, zamiast tego generowana jest wartość błędu. W formacie pliku CSV jest to ciąg znaków „#####”.
Uprawnienia
Każda usługa sieciowa zgodna z REST jest aplikacją, dla której można przypisać uprawnienia w systemie. Do nawiązania połączenia wymagane jest uprawnienie pozwalające na otwarcie aplikacji.
