Zde je možné vystavit jakoukoliv již existující sestavy EGJE. Nicméně je třeba si uvědomit, že standardní sestavy EGJE poskytují velké bloky formátovaných dat směřovaných do souboru určitého typu (např. PDF).

Volající tedy službu zavolá a pak musí v čekací smyčce zjišťovat, jestli už je výsledek hotov a jestli jej lze převzít. Jde o náročnější volání.

2. Server webových služeb REST

EGJE jako server webových služeb typu REST má své jádro vestavěno do EGJEWEB2

Pro službu je třeba vytvořit speciální uživatelskou sestavu, jejíž design je takový, že "stručně odpovídá na stručný" dotaz.

Sestavy se ptají na konkrétní údaje, např. pro konkrétní osobu (ale už ne třeba pro všechny osoby v db).

Pro export takové sestavy byl zřízen v Adm53 Typ AS úlohy:

3 - Webová služba REST (realizovaná uživ. sestavou)

Instalace sestavy poskytující webovou službu je pak standardní, přes Adm51.

Testování běžné webové služby REST je možné i pomocí webového prohlížeče.

2.1 Instalace

Configurator na záložce AS, Web obsahuje hodnotu radio přepínače "Web server", která slouží k označení, že instalace je určena jako Web server poskytující WS.

Umožňuje pomocí checkboxů určit, které komponenty se mají pustit:

Spustit EGJEWEB2 / HR portál – běžné web aplikace

Spustit server Web services

Spustit server Web services zaškrtněte pouze v případě, že je opravdu chcete používat. Jelikož standardní EGJEWEB2 / HR portál jde odškrtnout, je možné udělat i dedikovaný server Web services, který standardní Web aplikace spuštěné nemá.

V případě zájmu o konkrétní Web službu se na nás obraťte prostřednictvím ESP.

2.2 Autentizace

EGJE umožňuje nastavit autentizaci na dvou místech:

· V Configuratoru na záložce Ověření WS

· V aplikaci na formuláři Adm57

Kde se nastavuje autentizace?

Autentizace se nastavuje v Configuratoru na záložce Ověření WS:

Při nastavení “Oboje” se nastavení vezme z dané služby a pokud není ve službe vyplněno, vezme se z Configuratoru.

Při nastavení “V aplikaci” jsou k výběru tyto způsoby ověření:

· je možné povolit přístup bez ověření

· automatické (SSO), které je řešeno delegováním na operační system Windows/NTLM

· LDAPOnly

o Ověřování probíhá vůči LDAP serveru. U nás máme testovací LDAP server rtt.local. Pro správnou autentizaci je potřeba vyplnit tyto parametry:

§ LDAP - SSI URL (protokol://server:port): = ldaps://RTTDC1.RTT.local:636/DC=rtt,DC=local

§ LDAP(Web - implicitní doména uživatele: = rtt.local

o V této doméně existuje testovací uživatel:

§ uživ. jméno: egje

§ heslo: Elanor123*

§ logname v EGJE: egje@rtt.local

· LDAPSearch

o Pomocí toho lze nastavit omezení služby specificky pouze pro daného uživatele. Je zapotřebí vyplnit:

§ LDAP - SSI URL (protokol://server:port): = ldaps://RTTDC1.RTT.local:636/DC=rtt,DC=local

§ LDAPSearch - filtr: = (&(objectClass=person)(sAMAccountName=egje))

§ LDAP - speciální uživatel pro práci s LDAP: emans@rtt.local

§ LDAP - speciální uživatel pro práci s LDAP - Heslo:

§ LDAP(Web - implicitní dom=na uživatele: = rtt.local

o A volitelně LDAPSearch - Atribut unikátní identity uživatele.

o Speciální uživatel musí mít práva pro čtení LDAP.

· API Key

o Standartní BASIC autentizace. Jméno a heslo se ověřuje vůči údajům vyplněným na formuláři/v konfigurátoru.

o V této autentizaci se neověřuje, že je přihlašovaný uživatel v EGJE, tudíž nemá smysl vyplňovat Ověřovat profil práv=Ano.

o Při použití tohoto způsobu ověření doporučujeme zabezpečit komunikaci mezi klientem a serverem šifrováním

2.3 Konfigurace služby, autorizace

Na Adm53 zadejte nový záznam s typem úlohy 3 - Webová služba REST. V tabulkovém nebo formulářovém pohledu doplňte dle potřeby tyto parametry:

· Rozšíření url – finální část URL, na které bude služba dostupný

· Vyžadovat ověření – pokud je zaškrtnuto, služba bude požadovat ověření

· Zdroj autentizace – při nastavení autentizace z aplikace zde vyplňte kód z Adm57 pro danou autentizaci, pokud je prázdné, bere se z Configurátoru

· Ověřovat profil práv – pro „Ano“ musí mít „Osoba – autor“ (není-li vyplněno tak „Změnu provedl“) ze záložky Detail přiřazený „Profil práv pro spuštění úlohy“

Profil práv může být omezený tak, aby umožňoval přístup pouze k webovým službám, tzn. nebude nabízen při přihlášení do tlustého nebo web klienta – nastavením typu GUI na 21 - Pouze WS (Adm02/Profil základní údaje).

2.4 URL pro volání sestavy

Vzorové URL pro volání sestavy vypadá následovně: https://host:port/aliaswebapp/ws/endpoint[?položka=hodnota[&položka=hodnota]...]

Popis jednotlivých parametrů URL je následující:

· https://host:port/aliaswebapp = základní URL adresa webového serveru EGJE

· ws = konstanta

· endpoint = kód sestavy (Rstxx)

· ? = konstatní parameter URL, který odděluje základní adresu od jednotlivých parametrů. Po tomto znaku se zadávají parametry, které jsou přenášeny přímo do sestavy. Jednotlivé parametry jsou odděleny znakem “&”.

· položka = název parametru

· hodnota = hodnota parametru

Příklad URL:

https://egje.elanor.cz:8080/egjeweb/ws/rtf21?oscpv=10254&active=1

2.5 Logování

logování REST WS probíhá takto:

ukládání logů:

O každém běhu REST WS se vytváří a ukládá protokol (soubor logů tj dat o běhu programu). Tyto protokoly se budou skládat z:

logování REST API (tj. endpointu)

čas spuštění
kdo se autentizoval a jak
jaké byly parametry volání
čas ukončení
stav volání (sice nám je vždy vrácena 200, ale pokud vím, tak jsme schopni zjistit i jiné stavy - neproběhla autentizace, nefunkční spojení, proběhl import atd.)
detail stavu volání

logování JSON souboru

na Adm53/Parametry je možné přidat nový parament protocol_body s těmito vlastnostmi:

uživatelem zvolená hodnota (0;1) se uloží do cesastask.dalsi_xml/param/@parname = protocol_body
protocol_body = 0

JSON tělo se neukládá (skutečně neukládá, neznamená to jen jeho zašifrování například)
defaultní hodnota, protože JSON může obsahovat rodná čísla atd

protocol_body = 1

JSON tělo se ukládá
může mít i 1MB tj. je potřeba těmto objemům přizpůsobit hodnotu max_protocols viz níže

logování zpracování údajů v databázi tj logy podkladové Rst sestavy

zadání dodává klient

promazávání protokolů:

Konfiguruje se pro danou konfiguraci REST WS na Adm53/Protokol pomocí parametru max_protocols, který říká, kolik posledních protokolů si v databázi pro danou konfiguraci sestavy ponecháváme

§ defaultní hodnota max_protocols = 10

§ v kódu obecně není kontrola na výši max_protocols

zobrazování logů:

bude probíhat úplně stejně jako AS-IS stav pro sestavy s typem AS úlohy = 1 tj na Adm53/Protokol

tj. v panelu zpráv bude rozpársován protokol na jednotlivé logy REST API a logy Rst sestavy
ten JSON se ale nikde zobrazovat nebude

2.6 Diagram procesu spuštění REST WS

Textové pole:

2.7 Ukázkové sestavy

2.7.1 Rst01f

Sestava vrací údaje o osobě ve formátů xml podle zadaného OSCPV

2.7.2 Rst02f

Sestava slouží pro nahrání dokumentů PV.

Příklad volání sestavy

import java.io.File;

import java.nio.charset.Charset;

import java.nio.charset.StandardCharsets;

import org.apache.commons.io.IOUtils;

import org.apache.http.HttpEntity;

import org.apache.http.HttpResponse;

import org.apache.http.client.HttpClient;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.mime.MultipartEntity;

import org.apache.http.entity.mime.content.FileBody;

import org.apache.http.entity.mime.content.StringBody;

import org.apache.http.impl.client.DefaultHttpClient;

public class TestHttpPost {

public static void main(String[] args) {

try {

HttpClient httpclient = new DefaultHttpClient();

HttpPost httppost = new HttpPost("http://server:8080/ws/Rst02f");

MultipartEntity reqEntity = new MultipartEntity();

Charset utf8 = StandardCharsets.UTF_8;

reqEntity.addPart("r_oscpv", new StringBody("1_0685.001", utf8));

reqEntity.addPart("r_uchaz_dok_typ", new StringBody("3", utf8));

reqEntity.addPart("r_public_dok", new StringBody("true", utf8));

reqEntity.addPart("r_personal", new StringBody("false", utf8));

String fileName = "C:\\Users\\Michal\\Documents\\download.jpg";

reqEntity.addPart("r_file", new FileBody(new File(fileName)));

httppost.setEntity(reqEntity);

// Execute and get the response.

HttpResponse response = httpclient.execute(httppost);

int statusCode = response.getStatusLine().getStatusCode();

System.out.println("status_code: " + statusCode);

HttpEntity entity = response.getEntity();

IOUtils.copy(entity.getContent(), System.out);

} catch (Exception e) {

e.printStackTrace();

}

2.8 Rst07f - WEB Služba pro zápis do Dca01

Sestava pomoci API/RES Webové služby na základě vstupního zadání vytvoří zápis do Dca01.

Vstupem je soubor JSON v požadovaném formátu, který obsahuje jeden nebo více řádků.

Podrobný popis a použití je uvedeno v Doch_uzdoc, kapitola „Rst07f - WEB Služba pro zápis do Dca01“.

3. Server webových služeb SOAP

Jde o webový server integrovaný do aplikačního serveru EGJE.

Umožňuje spouštění standardních a uživatelských sestav voláním webové služby.

3.1 Instalace

3.1.1 Aplikační server - wrapper.conf

V aplikačním serveru (wrapper.conf) přidejte do classpath za egjelib.jar tyto knihovny

egjelib2.jar

egjews-embed.jar

AS je pak zapotřebí spouště pomocí jiné třídy a to:

wrapper.app.parameter.1=cz.elanor.egjews.server.RunServerWithWS

Dále je zapotřebí přidat parametry:

Varianta bez ssl

egjews.port=8000

Varianta se ssl

egjews.port=8000

egjews.sslkeystore=server.jks

egjews.sslkeystorepassword=xxxxx

Přičemž předpokládáme stejné heslo ke keystore i ke klíči.

Jméno klíče předpokládáme jetty

Toto javakeystore je zapotřebí na serveru vytvořit (JDK utilita keytool).

Parametry mohou být buď v konfiguračním souboru config_egje.jar/config_local.properties

nebo, a to doporučujeme přímo ve wrapper.conf:

wrapper.app.parameter.x=-Cegjews.port=8000

wrapper.app.parameter.x=-C egjews.sslkeystore=server.jks

wrapper.app.parameter.x=-C egjews.sslkeystorepassword=xxxxx

Na OS linux ještě přidejte

wrapper.java.additional.y= -Djava.awt.headless=true

3.1.2 Autentizace k webovým službám

· je stejná jako u aplikačního serveru nebo EgjeWebu, tzn. konfiguruje se stejným způsobem a je sdílena s AS

· je možné použít buď SSO autentizace, ta pak probíhá na úrovni protokolu HTTP, nebo interaktivní autentizace a zde se jméno a heslo zadává pomocí volání metody login webové služby - public void login(String user, String pass);

· interaktivní autentizace je možná pouze při použití SSL

· pokud je nakonfigurována autentizace typu SSO, budou i web služby vyžadovat tuto autentizaci

· u autentizací, které kombinují SSO s ověřením jménem heslem je možné vypnout SSO přidáním parametru "i" nebo "interactive_auth" do adresy služby -
např. http://localhost:8000/egjews?wsdl&i

· uživatel s heslem null resp. prázdný String není povolen

3.1.3 Autorizace uživatele

· při zpracování kontrolujeme, zda-li autentizovaný uživatel má přidělen profil, který je uveden u akce evidované v Adm53, kterou se snaží spustit

· pokud je v Adm53 uvedena i organizace, tak je kontrolováno, zda-li volající uživatel má tento profil přiřazen k této organizaci nebo zda-li má přiřazen profil bez omezení organizací.

· pokud v Adm53 není organizace vyplněna, jako parametr do dalšího zpracování je použita organizace přihlášeného uživatele (z přiřazeného profilu)

3.2 Použití

3.2.1 Volající program

Jeho ukázku přikládáme v souboru egjews-client.jar

V něm je také definiční soubor služby EgjeWS.wsdl. Ten je postačující pro volání z .NET resp. jiného prostředí než java

Pokud službu voláte z javy můžete využít:

TestClient.java, který obsahuje úplný příklad volání služby.

InstallCert.java, pomocná utility pro zprovoznění SSL autentizace – stáhne certifikát a uloží jej lokálně.

cz\elanor\egjews\* interface webové služby v javě

Soubor egjews-client.jar můžete také použít přímo do classpath vaší aplikace, tam také patří knihovny z lib-client\* - jsou potřeba pro překlad testovací aplikace TestClient.java (patří do classpath)

3.2.2 Nastavení v Adm53

Z důvodu zabezpečení EGJE a pro získání dalších parametrů, je nutné každou sestavu, která má být volatelná z webové služby EGJE, deklarovat na Adm53 a uvést profil, se kterým se bude volat. Tento profil také musí být jedním z profilů, které má autentizovaný uživatel volající webovou službu přiřazen (viz Autorizace)

K tomuto účelu jsme zřídili Typ AS úlohy 2 – Uživatelská sestava jako WS

Uvedete zde dále:

· Spustit na serveru s IP: IP adresa (pokud možno primární) AS

· Organizace: jen u multiorganizační db

· Profil práv pro spuštění úlohy: - definuje hlavně práva k řádkům

· Jazyk uživatelského rozhraní

· Název - tento název je zpřístupněn v getDescs()

Na záložce Parametry pak :

Generuj parametry – vybrat sestavu
Vyplnit případné výchozí parametry a formát výstupu (mohou být zadány až při volání)

3.3 Dodatek - spouštění TestClient s SSL

Nejprve je zapotřebí vytvořit jks keystore na serveru (během instalace)

Následně je zapotřebí získat certifikát na klienta

(jinak volání hlásí chybu javax.xml.ws.WebServiceException: Failed to access the WSDL at: http://prghr3:8098/egjews?wsdl. It failed with:

Unexpected end of file from server. )

– utilita InstallCert.java

parametr příkazové řádky server:port

zeptá se který certifikát a vytvoří lokální soubor jssecacerts obsahující certifikát.

Nyní můžete zavolat TestClient.java (přičemž v static String host je třeba uvádět protokol https).