# Webová služba Profile 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í WS pro práci s profily.

### 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
--- | ---
assignProfile | Přiřazení profilu na prvek organizační struktury.
assignProfilesStateToPersonInRoles | Nastavení profilů na zařazení osob do rolí.
detachProfile | Odebrání profilu z prvku organizační struktury.
findProfilesByFilter | Hledání profilů podle předaného filtru.
findProfilesByIds | Hledání profilů podle předaného seznamu id.
getNextProfiles | Načtení další části stránkovaného seznamu profilů.
getOrgStructProfiles | Načtení profilů pro prvek organizační struktury.
syncProfileValues | Synchronizuje profil a jeho hodnoty atributů.

## Seznam struktur dat

Název | Popis
--- | ---
EosApplication | Reprezentuje aplikaci.
EosApplications | Reprezentuje kolekci aplikací.
EosAttribute | Reprezentuje atribut.
EosAttributeValue | Hodnota atributu.
EosAttributeValues | Kolekce hodnot atributu pro přiřazení.
EosAttributes | Reprezentuje kolekci atributů.
EosEntityIdType | Typ entity organizační struktury.
EosPaging | Objekt obsahující informace pro stránkování.
EosPersonInRoleProfiles | Seznam profilů na zařazení osoby do role.
EosPersonInRolesProfiles | Seznam profilů na zařazení osob do rolí.
EosProfile | Reprezentuje profil.
EosProfileIds | Objekt obsahující seznam id profilů.
EosProfiles | Reprezentuje seznam profilů.
EosRoleIdType | Typ id role.

## Výjimky

### EosIllegalArgumentException

### EosInternalException

Reprezentuje neočekávanou výjimku při volání webových služeb.

### EosListNotFoundException

List podle předaného id nebyl nalezen.

### EosObjectNotFoundException

Objekt nebyl podle předaného id nalezen.

### EosObjectNotFoundException

Nedostatečná oprávnění.

### EosSSessionNotFoundException

Session s předaným id nebyla nalezena.

## Popis poskytovaných metod

### assignProfile

Přiřazení profilu na prvek organizační struktury.

#### Předpis

void assignProfile (String sid, String profileId, String entityId, EosEntityIdType entityIdType)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
profileId | String | Ano | id profilu
entityId | String | Ano | id entity organizační struktury
entityIdType | EosEntityIdType | Ano | typ entity, na které odkazuje isId

#### Výjimky

EosObjectNotFoundException - entita nebo profil nebyly nelezeny
EosIllegalArgumentException - chybné vstupní parametry
EosObjectNotFoundException - nedostatečná oprávnění
EosSSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba

### assignProfilesStateToPersonInRoles

Nastavení profilů na zařazení osob do rolí. Metoda odstraní aktuální profily na zařazení osob do rolí a přiřadí jim jen položky předané v parametru. Tato metoda vyžaduje přihlášení.

#### Předpis

void assignProfilesStateToPersonInRoles (String sid, EosPersonInRolesProfiles personInRolesProfiles)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
personInRolesProfiles | EosPersonInRolesProfiles | Ano | profily na zařazení osob do rolí

#### Výjimky

EosObjectNotFoundException - Objekt nebyl podle předaného id nalezen.

EosIllegalArgumentException -

EosObjectNotFoundException - Nedostatečná oprávnění.

EosSSessionNotFoundException - neexistující session
EosInternalException - Reprezentuje neočekávanou výjimku při volání webových služeb.

### detachProfile

Odebrání profilu z prvku organizační struktury. Profil lze z entity odebrat pouze pokud je na ní přímo přiřazen (není zděděn).

#### Předpis

boolean detachProfile (String sid, String profileId, String entityId, EosEntityIdType entityIdType)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
profileId | String | Ano | id profilu
entityId | String | Ano | id entity organizační struktury
entityIdType | EosEntityIdType | Ano | typ entity, na které odkazuje entityId

#### Výstup

boolean - true, pokud byl profil odebrán, profil nemusí být odebrán např. pokud není na entitě přímo přiřazen a je zděděn

#### Výjimky

EosObjectNotFoundException - entita nebo profil nebyly nelezeny
EosIllegalArgumentException - chybné vstupní parametry
EosObjectNotFoundException - nedostatečná oprávnění
EosSSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba

### findProfilesByFilter

Hledání profilů podle předaného filtru.

#### Předpis

EosProfiles findProfilesByFilter (String sid, String filter)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
filter | String | Ne | filtr na profily

#### Výstup

EosProfiles - seznam profilů podle předaného filtru

#### Výjimky

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

### findProfilesByIds

Hledání profilů podle předaného seznamu id.

#### Předpis

EosProfiles findProfilesByIds (String sid, EosProfileIds profileIds)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
profileIds | EosProfileIds | Ano | seznam id profilů

#### Výstup

EosProfiles - nalezené profily, pokud podle některých id nebyly profilz nalezeny, nebudou ve výsledku obsaženy

#### Výjimky

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

### getNextProfiles

Načtení další části stránkovaného seznamu profilů.

#### Předpis

EosProfiles getNextProfiles (String sid, String lid)

#### Parametry

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

#### Výstup

EosProfiles - další část stránkovaného seznamu profilů

#### Výjimky

EosListNotFoundException - lid daného id neexistuje
EosIllegalArgumentException - byl předán nevalidní parametr
EosSSessionNotFoundException - neexistuje session
EosInternalException - vniřní chyba

### getOrgStructProfiles

Načtení profilů pro prvek organizační struktury.

#### Předpis

EosProfiles getOrgStructProfiles (String sid, String entityId, EosEntityIdType entityIdType)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
entityId | String | Ano | id entity organizační struktury
entityIdType | EosEntityIdType | Ano | typ entity, na které odkazuje isId

#### Výstup

EosProfiles - profily

#### Výjimky

EosObjectNotFoundException - aplikace nebo entita nebyly nelezeny
EosSSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba

### syncProfileValues

Synchronizuje profil a jeho hodnoty atributů.

Profila a jeho aplikace jsou dohledávány podle identifikátoru. Atributy jsou dohledávány podle názvu. V případě vyplnění neexistující hodnoty identifikátoru aplikace je vyhozena výjimka. V případě vyplnění neexistující hodnoty identifikátoru profilu je založen nový.

Upozornění! Vždy je nutné poslat kompletní aktuální stav profilu. Aplikace, které nepřijdou, budou z profilu odstraněny. Atributům, které nebudou předány, budou odstraněny jejich hodnoty. Hodnoty, které nebudou předány, budou odstraněny.

#### Předpis

String syncProfileValues (String sid, EosProfile profile, EosApplications applications)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
sid | String | Ne | session id
profile | EosProfile | Ano | webový objekt profilu
applications | EosApplications | Ano | webový objekt aplikací

#### Výstup

String - id založeného profilu

#### Výjimky

EosObjectNotFoundException - aplikace nebo profil nebyly nelezeny
EosIllegalArgumentException - chybné vstupní parametry
EosSSessionNotFoundException - neexistující session
EosInternalException - vnitřní chyba systému

## Popis struktur dat

### EosApplication

Reprezentuje aplikaci. Slouží k nastavení hodnot atributů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | String | Ne | Id.
attributes | EosAttributes | Ne | Atributy aplikace.

### EosApplications

Reprezentuje kolekci aplikací. Slouží k nastavení hodnot atributů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
applications | List<EosApplication> | Ne | Seznam aplikací sloužících pro přiřazení hodnot atributů.

### EosAttribute

Reprezentuje atribut. Slouží k nastavení hodnot atributů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | String | Ne | Id.
name | String | Ne | Název.
attributeValues | EosAttributeValues | Ne | Hodnoty atributu.

### EosAttributeValue

Hodnota atributu.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | String | Ne | Id.
content | String | Ne | Hodnota.
description | String | Ne | Popis.

### EosAttributeValues

Kolekce hodnot atributu pro přiřazení.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
attributeValues | List<EosAttributeValue> | Ne | Hodnoty atributu.

### EosAttributes

Reprezentuje kolekci atributů. Slouží pro přiřazení hodnot atributů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
attributes | List<EosAttribute> | Ne | Seznam atributu sloužící pro přiřazení hodnot.

### EosEntityIdType

Typ entity organizační struktury.

Hodnota | Popis
--- | ---
OU | Organizační jednotka.
OR | Organizační role.
GR | Skupinová role.

### EosPaging

Objekt obsahující informace pro stránkování.

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.

### EosPersonInRoleProfiles

Seznam profilů na zařazení osoby do role.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
profileIds | EosProfileIds | Ne | Id profilů.
personId | String | Ne | Id osoby.
roleId | String | Ne | Id role.
roleIdType | EosRoleIdType | Ne | Typ entity, na které odkazuje roleId.

### EosPersonInRolesProfiles

Seznam profilů na zařazení osob do rolí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personInRoleProfiles | List<EosPersonInRoleProfiles> | Ne | Seznam profilů na zařazení osoby do role.

### EosProfile

Reprezentuje profil.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | String | Ne | Id.
name | String | Ne | Název profilu.
description | String | Ne | Popis profilu.
inherited | Boolean | Ne | Příznak, zda je profil na entitu zděděn, je plněno pouze v případech zjišťování seznamu profilů na entitě nebo osobě.
sample | Boolean | Ne | Příznak zda jde o vzorový (takový které v eosu není možné ručně měnit) profil.

### EosProfileIds

Objekt obsahující seznam id profilů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
profileIds | List<String> | Ne | Seznam id organizační profilů.

### EosProfiles

Reprezentuje seznam profilů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
profiles | List<EosProfile> | Ne | Seznam profilů.
paging | EosPaging | Ne | Stránkování.

### EosRoleIdType

Typ id role.

Hodnota | Popis
--- | ---
OR | Organizační role.
GR | Skupinová role.