# Webová služba Environment verze 3.0.0 (Obecné webové služby) - popis rozhraní služby

Marbes Consulting s.r.o.

EOS4

Vygenerováno z verze 4.21.0.19.0.

Podmínky omezující zveřejnění

Autorem tohoto dokumentu je společnost MARBES CONSULTING s.r.o. Dokument obsahuje informace důvěrného charakteru a ve smyslu definice autorského práva (viz § 2, odst. 1 Zákona č. 121/2000 Sb., zákon o právu autorském) je duševním vlastnictvím autora a předmětem práva autorského. Dokument smí být použit výhradně za účelem, za kterým byl poskytnut a nesmí být bez předchozího souhlasu autora citován, kopírován, vytěžován1 nebo předán třetí fyzické či právnické osobě.

© 2009 MARBES CONSULTING s.r.o.

1 Vytěžováním se podle zákona č. 121/2000 Sb. rozumí trvalý nebo dočasný přepis celého obsahu nebo jeho podstatné části na jiný podklad, a to jakýmikoli prostředky nebo jakýmkoli způsobem.

## Obsah

- Obecné informace
- Seznam poskytovaných metod
- Seznam struktur dat
- Výjimky
- Popis poskytovaných metod
- Popis struktur dat

## Obecné informace

Rozhraní pro načítání prostředí.

### Vysvětlení pojmů

- Prvek organizační struktury - organizačí jednotka, organizační role, skupinová role nebo zařazení osoby do organizační nebo skupinové role
- Role - organizační role a skupinová role
- Agenda - obecné označení prvku stromu agend, může reprezentovat agendu, činnost, roli v agendě nebo jiný uživatelský typ, který bude definován ve stromu agend, základní typy lze zjistit z atributu typeCode u agendy
- Osoba - reprezentuje skutečnou evidovanou osobu, osoba může mít více zařazení, ale na ty není brán zřetel
- Osoba v zařazení - reprezentuje konkrétní osobu zařazenou do konkrétní role (organizační nebo skupinové)
- Primární zařazení - jedná se o zařazení osoby do role, které má nejvyšší hodnotu obsazení. Osoba nemusí mít primární zařazení pokud není nikam zařazená, nebo má více zařazení se stejnou hodnotou obsazení.
- Strom organizačních rolí - strom nadřízenosti a podřízenosti organizačních rolí
- Aplikace - aplikace evidovaná v EOS, součástí aplikace je seznam atributů
- Atribut - patří k aplikaci a definuje typy oprávnění, např. jednotlivé úrovně řízení aplikace jako je přístup k webovým službám, typy dokumentů pro přístup, zda se jedná o adminstrátora atp.
- Hodnota oprávnění - konkrétní přiřazená hodnota oprávnění pro daný atribut, např. true pro atribut administrátor, výčet konkrétních přiřazených typů dokumentů pro atribut typů dokumentů atp.
- Response filter - jedná se o objekt, který uvádí, jaká data se mají ve výstupních objektech vracet, např. pokud externí systém "zajímají" pouze základní údaje, nemusí EOS vracet další rozšiřující data, např. seznam kontaktů k osobě, když nás zajímá pouze seznam osob atp. Pokud není uveden, vrací se pouze základní data k objektu.
- Session id - jedná se i identifikátor připojení k serveru a v tuto chvíli není povinný. Tento identifikátor lze získat webovou službou pro otevárání session. V novějších verzích bude vhodné session využít pro případ, kdy bude vyžadováno čtení dat s určitými vlastnostmi, např. dat z historie atp.

### Stránkování

Pokud metoda vrací seznam objektů, může být výsledný vracený seznam stránkovaný. Informaci o stránkování obsahuje atribut paging, ve kterém se nachází i informace, zda server uchovává další data (existuje další stránka). Vychozí velikost jedné stránky je 500 záznamů. Objekt paging obsahuje identifikátor seznamu dat (lid) a ten je nutné předat do metody, která načte další stránku (typický název metody je getNextXxx).

#### Důležité upozornění

Při načítání stránkovaného seznamu nemusí vždy odpovídat počet vrácených záznamů parametru totalCount, který je uveden v objektu paging. Toto se projeví pouze v případě, že jsou během stránkovaného načítání některé vracené objekty z EOS odstraněny.

### Filtrování

Některé metody podporují filtrování dat, např. načtení seznamu aplikací. Filtr se předává formou řetězce, ve kterém je zapsána podmínka. Podmínku lze použít POUZE na základní atributy vracených objektů. Podmínku nelze tedy použít na další vnořené hodnoty, např. kontakty osoby. Pro tento účel existují samostatné metody.

#### Možnosti filtrování

Podmínky u filtrů je možné sestavovat pouze stylem ATRIBUT OPERÁTOR HODNOTA, nelze tedy např. porovnávat dva atributy navzájem. Řetězcová hodnota se VŽDY uvádí v apostrofech (jinak bude chybně chápána jako název atributu a bude vyhozena chyba), pokud hodnota obsahuje apostrof, musí být znak zapsán jako dva apostrofy ''. U operátorů like a ilike je možné použít znak %, který nahrazuje žádný nebo libovolný počet znaků. Znak % lze používat pouze na začátku a konci hodnoty. Pokud je potřeba zapsat hodnotu null, je zapsána bez uvozovek. Datum je nutné zapsat ve formátu: `dd.MM.yyyy HH:mm:ss.SSS` nebo zkráceně bez času `dd.MM.yyyy`. Pro boolean hodnoty se uvádí hodnota 'true' nebo 1 pro true a 'false' nebo 0 pro false, textové reprezentace musí být uvedeny v apostrofech.

Podmínky jsou omezeny na počet porovnávaných hodnot. U výrazu `jmeno = 'petr' and id in ('1', '2', '3')` je počet podmínek 4. Maximální bezpečný počet je 1000, ale EOS toto nijak nekontroluje. Při použití vyššího počtu může, ale nemusí dotaz projít. Toto je z důvodu, že EOS do některých dotazů přidává vlastní podmínky a tudíž se může stát, že bude překročen limit DB serveru na velikost podmínky.

#### Operátory

- = - operátor nelze použít na hodnotu null
- is null - test null hodnoty
- is not null - test na ne-null hodnotu
- <> - operátor nelze použít na hodnotu null
- <
- >
- <=
- >=
- like - u operátoru lze použít znak %, ale pouze na začátku a na konci
- ilike - u operátoru lze použít znak %, ale pouze na začátku a na konci

#### Operandy

- and
- or

#### Příklad filtru

Příklad zapsání filtru na osoby, jejichž uživatelské jméno je "kolomaznik" a titul začíná na 'i': `username = "kolomaznik" and degreeBefore ilike 'i%'`

## Seznam poskytovaných metod

Název | Popis
--- | ---
assignEnvironment | Přiřazení prostředí k aplikaci.
detachEnvironment | Odebrání prostředí od aplikace.
findEnvironmentsByFilter | Hledání prostředí podle předaného filtru.
findEnvironmentsByIds | Hledání prostředí podle předaného seznamu id.
getNextEnvironments | Načtení další části stránkovaného seznamu prostředí.
isApplicationAssignToEnvironment | Metoda zjistí, jestli je aplikace zařazena do prostředí.
syncEnvironment | Provede synchronizaci prostředí.

## Seznam struktur dat

Název | Popis
--- | ---
EosEnvironment | Prostředí.
EosEnvironments | Seznam prostředí.
EosPaging | Objekt obsahující informace pro stránkování vrácených záznamů prostředí.
EosProfileIds | Objekt obsahující seznam id prostředí.

## Výjimky

### EosIllegalArgumentException

Byl předán nevalidní vstupní argument do metody webové služby.

### EosInternalException

Neočekávaná výjimka při volání webových služeb.

### EosObjectNotFoundException

Objekt nebyl nalezen.

### EosSessionNotFoundException

Session s předaným id nebyla nalezena.

## Popis poskytovaných metod

### assignEnvironment

Přiřazení prostředí k aplikaci.

Prostředí nemusí být aplikaci přiřazno, pokud se již v prostředí nachází aplikace se stejným kódem. V takovém případě vrátí metoda vyjímku.

#### Předpis

void assignEnvironment (String sid, String environmentId, String applicationId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
environmentId | String | Ano | id prostředí
applicationId | String | Ano | id aplikace

#### Výjimky

EosObjectNotFoundException - prostředí nebo aplikace nebyly nelezeny
EosIllegalArgumentException - chybné vstupní parametry
EosSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba
EosIllegalStateException - prostředí již obsahuje aplikaci se stejným kódem, nebo je aplikace již v prostředí zařazena

### detachEnvironment

Odebrání prostředí od aplikace.

#### Předpis

void detachEnvironment (String sid, String environmentId, String applicationId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
environmentId | String | Ano | id prostředí
applicationId | String | Ano | id aplikace

#### Výjimky

EosObjectNotFoundException - aplikace nebo prostředí nebyly nelezeny
EosIllegalArgumentException - chybné vstupní parametry
EosSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba
EosIllegalStateException - aplikace není v prostředí, ze kterého ji chceme odebrat, zařazena

### findEnvironmentsByFilter

Hledání prostředí podle předaného filtru.

#### Předpis

EosEnvironments findEnvironmentsByFilter (String sid, String filter)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
filter | String | Ne | filtr na prostředí

#### Výstup

EosEnvironments - seznam prostředí podle předaného filtru

#### Výjimky

EosIllegalArgumentException - byl předán nevalidní parametr
EosSessionNotFoundException - neexistuje session
EosInternalException - vniřní chyba

### findEnvironmentsByIds

Hledání prostředí podle předaného seznamu id.

#### Předpis

EosEnvironments findEnvironmentsByIds (String sid, EosProfileIds environmentIds)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
environmentIds | EosProfileIds | Ano | seznam id prostředí

#### Výstup

EosEnvironments - nalezené prostředí, pokud podle některých id nebyly prostředí nalezeny, nebudou ve výsledku obsaženy

#### Výjimky

EosIllegalArgumentException - chybné vstupní parametry
EosSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba

### getNextEnvironments

Načtení další části stránkovaného seznamu prostředí.

#### Předpis

EosEnvironments getNextEnvironments (String sid, String lid)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
lid | String | Ano | list id

#### Výstup

EosEnvironments - další část stránkovaného seznamu prostředí

#### Výjimky

EosIllegalArgumentException - byl předán nevalidní parametr
EosSessionNotFoundException - neexistuje session
EosInternalException - vniřní chyba

### isApplicationAssignToEnvironment

Metoda zjistí, jestli je aplikace zařazena do prostředí.

#### Předpis

Boolean isApplicationAssignToEnvironment (String sid, String environmentId, String applicationId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
environmentId | String | Ano | id prostředí
applicationId | String | Ano | id aplikce

#### Výstup

Boolean - true - aplikace je přiřazena prostředí, false - není

#### Výjimky

EosObjectNotFoundException - aplikace nebo prostředí nebyly nelezeny
EosSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba

### syncEnvironment

Provede synchronizaci prostředí.

Pokud v objektu není předán identifikátor, tak bude vytvořeno nové prostředí. V opačném případě dojde k aktualizaci údajů na existujícím prostředí. Jestliže je identifikátor vyplněn, ale existující prostředí nebude nalezeno, bude vyvolána vyjímka WSObjectNotFoundException.

#### Předpis

String syncEnvironment (String sid, EosEnvironment environment)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
environment | EosEnvironment | Ano | prostředí které bude aktualizováno, nebo vytvořeno

#### Výstup

String - identifikátor vytvořenénoho, nebo editovaného prostředí

#### Výjimky

EosObjectNotFoundException - při předání neplatného identifikátoru (prostředí k aktualizaci nebylo nalezeno)
EosInternalException - vnitřní chyba
EosSessionNotFoundException - neexistující session
EosIllegalArgumentException - chybné vstupní parametry
EosIllegalStateException - pokud se pokusíme uložit produktivní prostředí a organizace již jedno produktivní prostředí obsahuje

## Popis struktur dat

### EosEnvironment

Prostředí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | String | Ne | Id prostředí.
name | String | Ne | Název prostředí.
description | String | Ne | Popis prostředí.
code | String | Ne | Kód prostředí.
testing | Boolean | Ne | Příznak jestli je prostředí testovací, nebo produktivní.

### EosEnvironments

Seznam prostředí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
environments | List<EosEnvironment> | Ne | Seznam prostředí.
paging | EosPaging | Ne | Stránkování.

### EosPaging

Objekt obsahující informace pro stránkování vrácených záznamů prostředí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
lid | String | Ne | List id nebo null, pokud stránkování není vyžadováno.
start | int | Ne | Index prvního záznamu, který byl aktuálně vrácen.
totalCount | int | Ne | Celkový počáteční záznamů.
hasNext | boolean | Ne | Příznak, zda jsou k dispozici ještě další záznamy.

### EosProfileIds

Objekt obsahující seznam id prostředí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
environmentIds | List<String> | Ne | Seznam id prostředí.