Kontekst żądania usług SOAP/REST

Info

W artykule opisano obiekty będące kluczowymi elementami żądań w komunikacji z bazą danych za pośrednictwem usług SOAP i REST. Obiekt Context jest wykorzystywany we wszystkich usługach i jest podstawą do analizy uprawnień użytkownika, jak i formy odpowiedzi. Powszechne wykorzystanie w rozwiązaniu HgDB sprawiło, że zaszła potrzeba wytworzenia pewnego rodzaju standardu komunikacji pomiędzy integrowanymi systemami. Tak powstał projekt Context and Case Request Transportable Objects Open API, który został wykorzystany między innymi do komunikacji pomiędzy Mercury DB (HgDB) 3.0 oraz Iron - POI Excel Serwer.

Definicja obiektu Context


Warstwy, w których użyty	Logic, Business
Rodzaj	Obiekt biznesowy
className/type	`Context`
Implementacja Java	`pro.ibpm.mercury.context.Context`
Implementacja DTO	`pro.ibpm.mercury.context.Context`
Definicja XML	hgdb-context-3.0.xsd

Obiekt kontekstu. Bardzo ważny element występujący w wywołaniu każdej usługi SOAP/REST (jako argument arg0 w API 2.0, w API 3.0 jako argument context). Jego zadanie to nie tylko informowanie o źródle/pochodzeniu wywołania żadania usługi, jego pola mają charakter sterujący i wpływają na sposób przetwarzania żądania, jak i odpowiedzi.

Lista i znaczenie poszczególnych pól/parametrów

Parametrów	Opis	Typ	Wymagany	Dozwolone wartości
appName	Nazwa aplikacji	`String`	Tak
appVersion	Wersja aplikacji	`String`	Tak
userName	Nazwa użytkownika	`String`	Tak
comment	Komentarz użytkownika (dlaczego wykonuje daną akcję)	`String`	Tak
maxResults	Maksymalna liczba wyników uzyskana w wyniku wyszukiwania danych. Dla zapytań złożonych jest to również maksymalna liczba wyników zwracanych w podzapytaniach.	`Integer`	Tak	Liczba całkowita z przedziału od 1 do 100000
queryTimeout	Definicja ewentualnego timeout’u operacji - liczba milisekund	`Integer`	Tak	Liczba całkowita większa od 0
locale	Definicja wersji językowej użytkownika. Skrót o konstrukcji `<kod_języka>_<kod_terytorium>` gdzie: `kod_języka` to kod języka ISO 639-1, `kod_terytorium` to kod UPS Code	`String`	Nie	Przykład: `pl_PL`
timeZone	Definicja strefy czasowej użytkownika	`String`	Nie	Przykład: `Europe/Belgrade`
userFullName	Dodatkowa informacja na temat użytkownika - pełna nazwa	`String`	Nie
eager4omdBuilder	Informacja, czy mają zostać przesłane tylko wymagane dane (minimum) - wartość `true`, czy też wszystkie możliwe, wartość `false`	`String`	Tak	`true` lub `false`
trustedData	Czy można ufać ustawionym danym? Flaga sterująca w sytuacji gdy ma dojść do aktualizacji danych o użytkowniku w systemie Mercury. Jak widać w kontekście przesyłana jest nazwa użytkownika i jego pełna nazwa – gdy ustawimy flagę na wartość `true` Mercury zaktualizuje pełną nazwę użytkownika do wartości podanej w kontekście.	`Boolean`	Tak	`true` lub `false`
ignoredCustomFields	Wykorzystywane w usługach biznesowych zapisu. Lista pól, których wartości mają być ignorowane podczas porównywania wersji obiektu. Flaga sterująca wykorzystywana w usługach biznesowych do identyfikacji typu sprawy.	`Set<String>`	Nie	Dozwolone wartości opisane są w artykule dotyczącym zapisu sprawy Zapis sprawy.
currentRole	Obecna rola użytkownika. Dane potrzebne do rejestracji zespołu w ramach którego użytkownik dokonuje zmian. Wartość parametru wymagana ze względu na Mechanizmu uprawnień.	`String`	Tak
userRoles	Lista ról użytkownika (nazwy). Na podstawie tej listy weryfikowane są uprawnienia do wykonywania operacji/wywoływanej usługi (zobacz artykuł dotyczący Mechanizmu uprawnień).	`Set<String>`	Tak
sourceOfRequest	Akronim aplikacji/źródła pochodzenia żądania akcji. Wymagany gdy usługa ma zidentyfikować nowy typ (`TypeCase`), obiekt grupy (`GroupCase`), czy też magazynu (`Store`). Podczas tworzenia takiego obiektu dodawana jest odpowiednia informacja związana z jego pochodzeniem.	`String`	Tak
~~rootTagName~~	Wykorzystywane w usługach biznesowych. Nazwa głównego tag’a dokumentu XML w którym zostanie umieszczona sprawa w postaci XML. Jeżeli nie jest ustawiony w odpowiedzi otrzymamy XML’a o tag’u głównym „variable”	`String`	Nie	Parametr przetarzały, obecnie niepotrzebny.
formats	Wykorzystywane w usługach biznesowych. Mapa formatów, której kluczami są nazwy parametrów systemu Mercury: 1. dla określenia formatu liczby: kluczem jest wartość `number.format.number` 2. dla określenia formatu płatności kluczem jest `number.format.currency` 3. dla określenia formatu daty używanej podczas komunikacji kluczem jest wartość `date.format.long` oraz `date.format.short`	`Map<String, String>` - zobacz poniższe przykłady definicji XML.	Nie
ignoreAlternateFields	Informacja, czy podczas budowania zapytania wyszukującego mają być ignorowane pola alternatywne - jeżeli ustawimy wartość `false` wyszukiwanie odbędzie się tylko po polach podstawowych. Domyślna wartość: `true`	`Boolean`	Nie	`true` lub `false`
decodeResult	Wykorzystywane w usługach biznesowych. Informacja, czy wynik, parametry sprawy, mają mieć zdekodowane wartości parametrów (wartości prezentacyjne). Przesyłane wartości odpowiadają obiektowi DecodeMethod, którego opis znajdziemy w niniejszej dokumentacji. Domyślna wartość: `DATE_AND_LOB`	`String`	Nie	Jedna z pośród wartości: `NOTHING`, `DATE_ONLY`, `LOB_ONLY`, `DATE_AND_LOB`, `ALL_WITHOUT_LOB`, `ALL`
decodeRequest	Wykorzystywane w usługach biznesowych. Informacja, czy wartości parametrów pojawiających się w żądaniu to wartości prezentacyjne. Przesyłane wartości odpowiadają obiektowi DecodeMethod, którego opis znajdziemy w niniejszej dokumentacji. Możliwe wartości jakie należy użyć zdefiniowane są w zależności od metod i usług, co zostanie zaznaczone podczas ich opisu. Domyślna wartość: `DATE_AND_LOB`	`String`	Nie	Jedna z pośród wartości: `NOTHING`, `DATE_ONLY`, `LOB_ONLY`, `DATE_AND_LOB`, `ALL_WITHOUT_LOB`, `ALL`
ignoreCaseHeaderInResponse	Wykorzystywane w usługach biznesowych. Informacja czy zwracane dane w warstwie biznesowej mają zawierać nagłówek sprawy - wykorzystywane np. podczas pobierania słowników składowanych jako sprawy. Domyślna wartość: `false`	`Boolean`	Nie	`true` lub `false`
cacheUsage	Informacja o sposobie wykorzystania pamięci podręcznych podczas realizacji zapytań wyszukiwania. Wartość domyślna to `TO_USE`	String	Nie	Jedna spośród wartości: `TO_USE`, `NONE`, `REFRESH`, `TO_REMOVE`
httpResponseCacheUsage	Wykorzystywane w usługach biznesowych. Dodatkowa przestrzeń pamięci podręcznej pozwala na przechowywanie całych wyników usług w jej przestrzeni, bez konieczności wykonania zapytania ani transformacji obiektów spraw do postaci XML, JSON. Domyślna wartość: `NONE`	`String`	Nie	Jedna spośród wartości: `TO_USE`, `NONE`, `REFRESH`, `TO_REMOVE`
defaultLuceneSortClause	Parametr opcjonalny. Domyślna klauzula sortowania wykorzystywana w przetwarzaniu wyniku zapytania do indeksu Lucene. Domyślnie przyjmuje wartość mrc_createDate ( w modelu 3.0, datę utworzenia sprawy). Przykład: code `DESC`	String	Nie	format wartości pola: `<nazwa_pola_ineksu>` `[ASC
viewDefinition	Wykorzystywane w usługach biznesowych. Lista pól (nazwy takie jak nazwy pól w indeksie Lucene), które zostaną zwrócone w wyniku zapytania do Indeksu. Pomocniczo w celu budowania tabeli wyników. Wartości pól muszą być przechowywane w indeksie Lucene.	`String`	Nie	Przykładowe użycie możemy znaleźć w artykule Wyszukiwanie spraw.
requestProperties	Wykorzystywane w usługach biznesowych. Dodatkowe parametry związane z przetwarzaniem wysłanego do usługi żądania.	`Map<String, String>`	Nie	Przykładowe użycie możemy znaleźć miedzy innymi w artykule dotyczącym zapisu sprawy Zapis sprawy.

Podstawowy przykład wykorzystania kontekstu

Aby skonstruować przykładowy obiekt typu Context zastosujmy następujące założenia:

Aplikacja, która wywołuje usługę przedstawia się jako BPM Proces Urlopowy w wersji 0.0.1.
Zewnętrzny system posiada własne mechanizmy uwierzytelniania, na podstawie których wie jak się nazywa użytkownik i jakie posiada role (wie do jakich grup użytkownik jest przypisany). Zakładamy zatem, że tym usługa jest wywoływana przez zewnętrzny system w imieniu uwierzytelnionego użytkownika o nazwie ttesteusz o jego pełnej nazwie Tadeusz Testeusz, który posiada następujące role: Dyrektor, CKBPM-Team, mrc-admin, mrc-user.
Wywołanie usługi zostało wymuszone podczas akcji, w trakcie której użytkownik pełni rolę Dyrektor
Przy założeniu, że wywoływana usługa systemu Mercury DB ma zrealizować zadanie modyfikacji wymagany jest komentarz do realizowanego zadania np. Zmiana nazwiska panieńskiego matki, na życzenie klienta
System zewnętrzny zidentyfikował następujące parametry językowe użytkownika ttesteusz: pl_PL
System zewnętrzny zidentyfikował następujące parametry dotyczące strefy czasowej użytkownika ttesteusz: Europe/Warsaw
Jako, że system zewnętrzny zidentyfikował wszystkie dane użytkownika, może on przekazać informację, do systemu Mercury DB, że dane mogą zostać uznane za zaufane i na ich podstawie, można zaktualizować jego dane. Ustawimy flagę trustedData na true.
W odpowiedzi, np. usługi wyszukiwania, parametry typu Date mają zostać przesłane w postaci prezentacyjnej w formacie yyyy-MM-dd HH-mm-ss. Pozostałe parametry mają zostać przesłane w postaci jakiej jak są zapisane w bazie danych.
W żądaniu (wywołaniu), np. usługi aktualizacji danych, parametry typu Date będą przesłane w postaci prezentacyjnej w formacie yyyy-MM-dd HH-mm-ss. Również obiekty typu LOB przesłane są w postaci prezentacyjnej, tzn. np. jako XML, a nie wskaźnik na obiekt LOB.
Maksymalna liczba wyników wyszukiwania/przetwarzana ustawiona zostanie na 1000

Przykładowa zawartość obiektu kontekstu, który zostanie przesłany do usługi:

XML dla usługi SOAP
JSON dla usługi REST

<context xmlns="http://business.dto.ws.hgdb.io/context"
	xsi:schemaLocation="http://business.dto.ws.hgdb.io/context http://hgdb.io/xsd/dto/hgdb-context-3.0.xsd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <appName>BPM Proces Urlopowy</appName>
 <appVersion>0.0.1</appVersion>
 <userName>ttesteusz</userName>
 <comment>Zmiana nazwiska panieńskiego matki, na życzenie klienta</comment>
 <maxResults>1000</maxResults>
 <queryTimeout>100000</queryTimeout>
 <locale>pl_PL</locale>
 <timeZone>Europe/Warsaw</timeZone>
 <userFullName>Tadeusz Testeusz</userFullName>
 <eager4omdBuilder>true</eager4omdBuilder>
 <trustedData>true</trustedData>
 <currentRole>Dyrektor</currentRole>
 <!--Zero or more repetitions:-->
 <userRoles>Dyrektor</userRoles>
 <userRoles>CKBPM-Team</userRoles>
 <userRoles>mrc-admin</userRoles>
 <userRoles>mrc-user</userRoles>
 <!--Tutaj wstawimy łańcuch zawierający nazwę hosta i akronim środowiska -->
 <sourceOfRequest>dev-bpm855-003.DEV</sourceOfRequest>
 <formats>
  <entry>
   <key>date.format.long</key>
   <value>yyyy-MM-dd HH-mm-ss</value>
  </entry>
 </formats>
 <decodeResult>DATE_ONLY</decodeResult>
 <decodeRequest>DATE_AND_LOB</decodeRequest>
 <ignoreCaseHeaderInResponse>false</ignoreCaseHeaderInResponse>
 <cacheUsage>TO_USE</cacheUsage>
 <httpResponseCacheUsage>NONE</httpResponseCacheUsage>
 <requestProperties />
</context>

{
    "appName": "mercury-ws-app",
    "appVersion": "0.0.1",
    "userName": "ttesteusz",
    "comment": "Zmiana nazwiska panieńskiego matki, na życzenie klienta",
    "maxResults": 1000,
    "queryTimeout": 100000,
    "locale": "pl_PL",
    "timeZone": "Europe/Warsaw",
    "userFullName": "Tadeusz Testeusz",
    "eager4omdBuilder": "true",
    "trustedData": true,
    "currentRole": "Dyrektor",
    "userRoles": [
        "Dyrektor",
        "CKBPM-Team",
        "mrc-admin",
        "mrc-user"
    ],
    "sourceOfRequest": "dev-bpm855-003.DEV",
    "formats": {
        "date.format.long": "yyyy-MM-dd HH-mm-ss"
    },
    "decodeResult": "DATE_ONLY",
    "decodeRequest": "DATE_AND_LOB",
    "ignoreCaseHeaderInResponse": false,
    "cacheUsage": "TO_USE",
    "httpResponseCacheUsage": "NONE",
    "requestProperties": {}
}

Po przesłaniu powyższego obiektu kontekstu do usługi zrealizowane zostaną następujące działania dodatkowe:

Zaktualizowane zostaną (jeżeli nie są aktualne) dane użytkownika (uzupełnione zostaną dane dotyczące pełnej nazwy użytkownika, jego ustawień językowych oraz strefa czasowa)
Zweryfikowana zostanie lista ról użytkownika. Jeżeli któraś z ról nie istnieje w systemie, zostanie ona automatycznie dodana.
Jeżeli kontekst zostanie wykorzystany podczas aktualizacji danych do historii zmian zostanie zapisany wprowadzony komentarz, dane użytkownika zmieniającego (jego nazwa) oraz informacja o tym jaką rolę pełnił podczas wprowadzania zmian.
Jeżeli kontekst zostanie wykorzystany podczas aktualizacji danych w usługach automatycznie wykrywających zależności, to dla nowych obiektów zapisana zostanie informacja o pochodzeniu obiektu.
Pole z identyfikatorem zewnętrznego kontekstu wspierać będzie identyfikację typów.
Jeżeli kontekst zostanie wykorzystany podczas aktualizacji danych w usługach biznesowych system pozwoli na poprawne zinterpretowanie wartości pól dat np. przesłana data 2017-01-01 23:34:21 zostanie rozkodowana i zapisana w bazie danych jako odpowiednia liczba milisekund.

Parametry żadania `requestProperties`

Parametr requestProperties jest wykorzystywany w usługach biznesowych do przesyłania dodatkowych informacji, które mogą być potrzebne podczas przetwarzania żądania. Przykładowe zastosowanie to przekazywanie dodatkowych parametrów, które nie są standardowo obsługiwane przez kontekst, ale są wymagane przez konkretną usługę. Poniżej lista parametrów, które mogą być przesyłane w tym parametrze. W miarę rozwoju systemu lista ta może być rozszerzana o kolejne parametry:

Nazwa parametru	Typ	Opis
saveRequestContext¹ .modifyComment	`String`	Komentarz modyfikacji żądania. Wykorzystywane w usługach biznesowych zapisu sprawy.
saveRequestContext¹ .saveCaseAsType	`String`	Wskazówka dla żądania zapisu sprawy. Nazwa typu/identyfikator typu pod jakim ma zostać zapisana sprawa. Wykorzystywane w
saveRequestContext¹ .valueIsNullIfFieldNotExisisInRequest	`Boolean`	Wskazówka dla żądania zapisu sprawy. Czy jeżeli pola nie istnieją w żądaniu zapisu sprawy (nie zostały przesłane pola obiektu), to ustawiać je na wartość pustą `null`. Domyślna wartość parametru jest odczytywana z konfiguracji systemu przechowywanej w pliku `mercury.properties`, parametr konfiguracyjny to `mercury`²`.saveRequestContext`¹`.valueIsNullIfFieldNotExisisInRequest.default`.
saveRequestContext¹ .forceChangeType	`Boolean`	Wskazówka dla żądania zapisu sprawy. Dodatkowym parametr przyjmujący jedną z wartości `true` albo `false`. Parametr pozwala albo zabrania na utworzenie nowej wersji typu dla sprawy jeżeli istnieje już wcześniej zdefiniowany. parametr z wartością domyślną, która w środowiskach developerskich byłaby ustawiona na `true`, a w środowisku produkcyjnym na `false`. Domyślna wartość parametru jest odczytywana z konfiguracji systemu przechowywanej w pliku `mercury.properties`, parametr konfiguracyjny to `mercury`²`.saveRequestContext`¹`.forceChangeType.default`.
saveRequestContext¹ .caseWithoutId	`Boolean`	Wskazówka dla żądania zapisu sprawy. Parametr wydający wskazówkę, że ewentualny identyfikator sprawy przesłany w żądaniu zapisu sprawy ma być zignorowany. Konsekwencją użycia dla spraw z typem bez klucza głównego będzie to, że za każdym zapisem sprawy będą dodawane. Dla spraw ze zdefiniowanym kluczem głównym sprawa będzie dodana tylko gdy nie istnieje sprawa z daną wartością klucza. bardzo przydatne podczas, a nawet REKOMENDOWANE podczas kopiowania spraw pomiędzy różnymi instancjami bazy danych HgDB. przyjmowane wartości: `true` albo `false`. Domyślna wartość: `false`.

Prefiks saveRequestContext. w nazwie parametru oznacza, że należy on do grupy parametrów związanych z aktualizacja obiektów spraw. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷
Prefiks mercury. w nazwie parametru konfiguracji oznacza przynależność do ogólnego zbioru parametrów systemu Mercury DB (HgDB) 3.0. ↩ ↩²

Definicja obiektu Context​

Podstawowy przykład wykorzystania kontekstu​

Parametry żadania requestProperties​

Footnotes​

Definicja obiektu Context

Podstawowy przykład wykorzystania kontekstu

Parametry żadania `requestProperties`

Footnotes