# Webová služba OrgStructureRead verze 2.1.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

WS pro čtení organizační struktury v 2.1.0.

## Seznam poskytovaných metod

Název | Popis
--- | ---
getAllPersonContainersExtended | Vrací seznam daného počtu osob v kontejnerech s jejich primárními zařazeními od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena).
getAllPersonsExtended | Vrací seznam daného počtu osob od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena).
getPersonContainerExtendedInfo | Načtení kompletních informací o osobě včetně primárního zařazení,
getPersonContainersInOUs | Vrací seznam daného počtu osob v kontejnerech s jejich primárními zařazeními od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena).
getPersonImage | Načtení fotografie osoby.
getPersonImageInfoEx | Vrátí informace o fotografie osoby na základě kterých může externí systém rozhodnout, zda má osoba přiřazen stejný nebo rozdílný obrázek než ten, který má již načtený.

## Seznam struktur dat

Název | Popis
--- | ---
EosBuildingInfo | Reprezentuje údaje o budově.
EosBuildingInfoExtended | Reprezentuje údaje o budově.
EosContactType | Reprezentuje typ kontaktního atributu.
EosContactTypeCategory | Reprezentuje kategorii typu kontaktního atributu.
EosContacts | Reprezentuje wrapper pro kolekci telefonů.
EosIdentifier | Reprezentuje identifikátor webového objektu slučující interní a externí ID.
EosIds | Struktura obsahující seznam eos identifikátorů.
EosImage | Webový objekt pro přenos fotografie.
EosImageInfo | Webový objekt pro přenos informací o fotografie.
EosOrgStructureResponseFilter | Třída reprezentující filter odpovědi WS.
EosOtherContact | Reprezentuje telefoní kontakt.
EosPerson | Reprezentuje osobu.
EosPersonContainer | Kontejner sloužící pro vrácení osoby společně s jejím primárním zařazením.
EosPersonContainerExtended | Kontejner sloužící pro vrácení rozšířené osoby společně s jejím primárním zařazením.
EosPersonContainerExtended2 | Kontejner sloužící pro vrácení rozšířené osoby společně s jejím primárním zařazením.
EosPersonContainers | Reprezentuje wrapper pro kontejnery osob, obsahující samotnou osobu a její primární zařazení, pokud ho daná osoba má.
EosPersonContainersExtended | Reprezentuje wrapper pro kontejnery rozšíených osob, obsahující samotnou osobu a její primární zařazení, pokud ho daná osoba má.
EosPersonExtended | Reprezentuje osobu s rozšířením.
EosPersonInfoExtended | Reprezentuje doplňující informace o zařazení osoby, tedy uživatelská pole, telefony a informace o umístění.
EosPersonPrimaryLocation | Reprezentuje primární zařazení osoby.
EosPersonPrimaryLocationExtended | Reprezentuje primární zařazení osoby.
EosPersonsExtended | Reprezentuje wrapper pro kolekci rozšířených osob.
EosPhoneContact | Reprezentuje telefoní kontakt.
EosString | Třída reprezentující stringovou hodnotu.
EosUserField | Reprezentuje uživatelské pole.
EosUserFields | Reprezentuje kolekci uživatelských polí.
EosValue | Reprezentuje hodnotu string atributu, výčtového atributu a selectového atributu.

## Výjimky

### EosInvalidParameterException

Vyjímka reprezentuje špatný vstupní parametr do web metod.

### EosObjectNotFoundException

Výjimka reprezentuje stav, kdy nebyl objekt podle kriterií nalezen.

### EosUnexpectedException

Reprezentuje neočekávanou výjimku při volání WS. Jejím zdrojem musí být vždy jiná výjimka.

## Popis poskytovaných metod

### getAllPersonContainersExtended

Vrací seznam daného počtu osob v kontejnerech s jejich primárními zařazeními od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena). Seznam je řazený podle klíčů neviditelných pro externí systém.

#### Předpis

EosPersonContainersExtended getAllPersonContainersExtended (EosIdentifier lastPersonId, int count, String clientId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
lastPersonId | EosIdentifier | Ne | ID poslední vrácené osoby při minulém volání; pro první volání je očekávána hodnota null
count | int | Ano | počet vrácených záznamů, maximum je 1000
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v lastPersonId

#### Výstup

EosPersonContainersExtended - všechny nalezené osoby v kontejnerech s primárním zařazením

#### Výjimky

EosObjectNotFoundException - objekt nebyl nalezen
EosInvalidParameterException - byl předán nevalidní vstupní parametr
EosUnexpectedException - nastala vnitřní chyba EOSu

### getAllPersonsExtended

Vrací seznam daného počtu osob od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena). Seznam je řazený podle klíčů neviditelných pro externí systém.

#### Předpis

EosPersonsExtended getAllPersonsExtended (EosIdentifier lastPersonId, int count, String clientId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
lastPersonId | EosIdentifier | Ne | ID poslední vrácené osoby při minulém volání; pro první volání je očekávána hodnota null
count | int | Ano | počet vrácených záznamů, maximum je 1000
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v lastPersonId

#### Výstup

EosPersonsExtended - všechny nalezené osoby

#### Výjimky

EosObjectNotFoundException - objekt nebyl nalezen
EosInvalidParameterException - byl předán nevalidní vstupní parametr
EosUnexpectedException - nastala vnitřní chyba EOSu

### getPersonContainerExtendedInfo

Načtení kompletních informací o osobě včetně primárního zařazení,

#### Předpis

EosPersonContainerExtended2 getPersonContainerExtendedInfo (EosIdentifier personId, String clientId, EosOrgStructureResponseFilter responseFilter)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
personId | EosIdentifier | Ano | id osoby
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v personId
responseFilter | EosOrgStructureResponseFilter | Ne | response filtr

#### Výstup

EosPersonContainerExtended2 - kompletní informace o osobě včetně primárního zařazení

#### Výjimky

EosObjectNotFoundException - osoba nebyla nalezena
EosInvalidParameterException - při předání neplatného identifikátoru osoby
EosUnexpectedException - nastala vnitřní chyba EOSu

### getPersonContainersInOUs

Vrací seznam daného počtu osob v kontejnerech s jejich primárními zařazeními od osoby s předaným identifikátorem (ta mezi vrácenými již není obsažena). Seznam je řazený podle klíčů neviditelných pro externí systém. Seznam osob je omezen pouze na organizační jednotky, které jsou vstupním parametrem. Osoby mohou být v libovolné hloubce pod organizační jednotkou.

#### Předpis

EosPersonContainers getPersonContainersInOUs (EosIdentifier lastPersonId, int count, EosIds ids, String clientId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
lastPersonId | EosIdentifier | Ne | ID poslední vrácené osoby při minulém volání; pro první volání je očekávána hodnota null
count | int | Ano | počet vrácených záznamů, maximum je 1000
ids | EosIds | Ano | seznam id organizačních jednotek v EOS, pro které se budou vracet osoby
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v ids

#### Výstup

EosPersonContainers - všechny nalezené osoby v kontejnerech s primárním zařazením

#### Výjimky

EosObjectNotFoundException - objekt nebyl nalezen
EosInvalidParameterException - byl předán nevalidní vstupní parametr
EosUnexpectedException - nastala vnitřní chyba EOSu

### getPersonImage

Načtení fotografie osoby.

#### Předpis

EosImage getPersonImage (EosIdentifier personId, String clientId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
personId | EosIdentifier | Ano | id osoby
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v personId

#### Výstup

EosImage - fotografie nebo null, pokud osoba žádnou nemá

#### Výjimky

EosObjectNotFoundException - osoba nebyla nalezena
EosInvalidParameterException - při předání neplatného identifikátoru osoby
EosUnexpectedException - nastala vnitřní chyba EOSu

### getPersonImageInfoEx

Vrátí informace o fotografie osoby na základě kterých může externí systém rozhodnout, zda má osoba přiřazen stejný nebo rozdílný obrázek než ten, který má již načtený.

#### Předpis

EosImageInfo getPersonImageInfoEx (EosIdentifier personId, String clientId)

#### Parametry

Parametr | Typ | Povinný | Popis
--- | --- | --- | ---
personId | EosIdentifier | Ano | id osoby ke které se má fotografie přiřadit
clientId | String | Ano | identifikátor klienta, je povinný jen při předání externího id v personId

#### Výstup

EosImageInfo - informace o fotografii osoby nebo null, pokud osoba žádnou nemá

#### Výjimky

EosUnexpectedException - nastala vnitřní chyba EOSu
EosObjectNotFoundException - osoba nebyla nalezena
EosInvalidParameterException - při předání neplatného identifikátoru osoby

## Popis struktur dat

### EosBuildingInfo

Reprezentuje údaje o budově. Není v EOSu skutečnou entitou, proto neobsahuje žádný identifikátor.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
building | EosValue | Ne | Název budovy.
floor | EosValue | Ne | Patro budovy.
room | EosValue | Ne | Místnost budovy.
externalRegistryId | EosValue | Ne | Odkaz na externi id registru budov.

### EosBuildingInfoExtended

Reprezentuje údaje o budově. Není v EOSu skutečnou entitou, proto neobsahuje žádný identifikátor.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
buildingId | String | Ne | Název budovy.
floorId | String | Ne | Patro budovy.
roomId | String | Ne | Místnost budovy.

### EosContactType

Reprezentuje typ kontaktního atributu.

Hodnota | Popis
--- | ---
PHONE | Telefon.
FAX | Fax.
EMAIL | Email.
WWW | WWW.

### EosContactTypeCategory

Reprezentuje kategorii typu kontaktního atributu.

Hodnota | Popis
--- | ---
HOME | Domů.
WORK | Do práce.
MOBILE | Mobilní.
BLANK | Bez kategorie.

### EosContacts

Reprezentuje wrapper pro kolekci telefonů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
phoneContact | List<EosPhoneContact> | Ne | Kolekce telefonů(fax, mobil, ...).
otherContact | List<EosOtherContact> | Ne | Kolekce ostatních kontaktů(email, www, ...).

### EosIdentifier

Reprezentuje identifikátor webového objektu slučující interní a externí ID.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
externalId | String (255) | Ne | Id entity v externím systému.
eosIdentifier | String (255) | Ne | Unikátní identifikátor entity v EOSu (v rámci konkrétního potomka entity, tedy např. organizační role), při importu do EOSu nemá význam.

### EosIds

Struktura obsahující seznam eos identifikátorů.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
eosIdentifier | List<EosString> | Ne | Seznam id.

### EosImage

Webový objekt pro přenos fotografie.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
image | byte | Ne | Fotografie reprezentována polem bytů.

### EosImageInfo

Webový objekt pro přenos informací o fotografie.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
imageHeight | int | Ne | Výška obrázku v pixelech.
imageWidth | int | Ne | Šířka obrázku v pixelech.
imageSize | Long | Ne | Valikost obrázku v bytech.
imageChecksum | String | Ne | Kontrolní součet.

### EosOrgStructureResponseFilter

Třída reprezentující filter odpovědi WS. Ná základě atributů třídy jsou plněny a vraceny doplňující informace k entitám a osobám.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
fillUserFields | boolean | Ne | Příznak zda plnit uživatelská pole.
userFieldCode | List<EosString> | Ne | Seznam identifikátorů uživatelských polí, kterou mohou být vráceny.
fillBuildingInfo | boolean | Ne | Příznak zda vracet budovy.
fillContacts | boolean | Ne | Příznak zda vracet kontakty.
fillOnlyPublicableContacts | boolean | Ne | Příznak zda vracet pouze veřejné kontakty.
contactEosIdentifier | List<EosString> | Ne | Seznam kontaktů, které mohou být vráceny.

### EosOtherContact

Reprezentuje telefoní kontakt.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
description | String (512) | Ne | Popis telefonu.
contactType | EosContactType | Ne | Typ kontaktu.
contactTypeCategory | EosContactTypeCategory | Ne | Kategorie typu kontaktu.
contact | EosIdentifier | Ne | Id atributu kontaktu.
primary | boolean | Ne | Určuje zda je kontakt primární.
publicable | boolean | Ne | Určuje zda je kontakt veřejný.
value | String (80) | Ne | Linka.

### EosPerson

Reprezentuje osobu.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
surname1 | String (64) | Ano | 1. příjmení.
surname2 | String (64) | Ne | 2. příjmení.
firstname1 | String (64) | Ano | 1. křestní jméno.
firstname2 | String (64) | Ne | 2. křestní jméno.
degreeBefore | String (32) | Ne | Akademický titul před jménem.
degreeAfter | String (32) | Ne | Akademický titul za jménem.
dateStart | Date | Ne | Datum zavedení do evidence.
dateEnd | Date | Ne | Datum vyřazení z evidence.
username | String (255) | Ne | Uživatelské jméno. Není povinné kvůli tomu, že je možné jméno generovat.
abbrev | String (24) | Ne | Zkratka.
email | String (128) | Ne | Adresa elektronické pošty. Pokud je uvedena, je unikátní. Nevyplněná hodnota je dovolena u více uživatelů.
displayName | String (255) | Ne | Zobrazované jméno.
personalNumber | String (255) | Ne | Osobní číslo.

### EosPersonContainer

Kontejner sloužící pro vrácení osoby společně s jejím primárním zařazením.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
person | EosPerson | Ano | Osoba.
primaryAssignment | EosPersonPrimaryLocation | Ne | Primární zařazení osoby.

### EosPersonContainerExtended

Kontejner sloužící pro vrácení rozšířené osoby společně s jejím primárním zařazením.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personExtended | EosPersonExtended | Ano | Osoba.
primaryAssignment | EosPersonPrimaryLocation | Ne | Primární zařazení osoby.

### EosPersonContainerExtended2

Kontejner sloužící pro vrácení rozšířené osoby společně s jejím primárním zařazením.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personExtended | EosPersonExtended | Ano | Osoba.
primaryAssignment | EosPersonPrimaryLocationExtended | Ne | Primární zařazení osoby, pokue nelze určit, není uvedeno.
personInfoExtended | EosPersonInfoExtended | Ne | Další informace k osobě - uživatelská pole, kontakty, umístění.

### EosPersonContainers

Reprezentuje wrapper pro kontejnery osob, obsahující samotnou osobu a její primární zařazení, pokud ho daná osoba má.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personContainer | List<EosPersonContainer> | Ne | Kolekce kontejnerů osob.

### EosPersonContainersExtended

Reprezentuje wrapper pro kontejnery rozšíených osob, obsahující samotnou osobu a její primární zařazení, pokud ho daná osoba má.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personContainer | List<EosPersonContainerExtended> | Ne | Kolekce kontejnerů osob.

### EosPersonExtended

Reprezentuje osobu s rozšířením.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
surname1 | String (64) | Ano | 1. příjmení.
surname2 | String (64) | Ne | 2. příjmení.
firstname1 | String (64) | Ano | 1. křestní jméno.
firstname2 | String (64) | Ne | 2. křestní jméno.
degreeBefore | String (32) | Ne | Akademický titul před jménem.
degreeAfter | String (32) | Ne | Akademický titul za jménem.
dateStart | Date | Ne | Datum zavedení do evidence.
dateEnd | Date | Ne | Datum vyřazení z evidence.
username | String (255) | Ne | Uživatelské jméno. Není povinné kvůli tomu, že je možné jméno generovat.
abbrev | String (24) | Ne | Zkratka.
email | String (128) | Ne | Adresa elektronické pošty. Pokud je uvedena, je unikátní. Nevyplněná hodnota je dovolena u více uživatelů.
displayName | String (255) | Ne | Zobrazované jméno.
personalNumber | String (255) | Ne | Osobní číslo.
disabled | Boolean | Ne | Je osoba povolená?
signature | String (8) | Ne | Iniciály.
publicable | Boolean | Ano | Zobrazovat na intenetu.
domain | String (255) | Ne | Doména v EOS, pod kterou uživatel spadá a pro kterou je dané uživatelské jméno unikátní. V tuto chvíli není v EOS implementováno a hodnota není vracena, po implementaci v EOS bude hodnota povinná a bude vyplněná.

### EosPersonInfoExtended

Reprezentuje doplňující informace o zařazení osoby, tedy uživatelská pole, telefony a informace o umístění. U umístění je přidáno rozšíření o identifikátory.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
buildingInfo | EosBuildingInfo | Ne | Informace o budově.
userFields | EosUserFields | Ne | Uživatelská pole jednotlivých entit.
phones | EosContacts | Ne | Telefony přiřazené této entitě.
buildingInfoExtended | EosBuildingInfoExtended | Ne | Informace o budově.

### EosPersonPrimaryLocation

Reprezentuje primární zařazení osoby. Nese informace o roli, ve které je osoba primárně zařazena a o rganizační jednotce, ve které je tato role.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
roleName | String (255) | Ano | Jméno organizační role.
roleIdentifier | EosIdentifier | Ano | Identifier organizační role.
orgUnitName | String | Ano | Jméno organizační jednotky.
orgUnitIdentifier | EosIdentifier | Ano | Identifier organizační jednotky.

### EosPersonPrimaryLocationExtended

Reprezentuje primární zařazení osoby. Nese informace o roli, ve které je osoba primárně zařazena a o rganizační jednotce, ve které je tato role. Dále obsahuje informace o typu organizační role.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
roleName | String (255) | Ano | Jméno organizační role.
roleIdentifier | EosIdentifier | Ano | Identifier organizační role.
orgUnitName | String | Ano | Jméno organizační jednotky.
orgUnitIdentifier | EosIdentifier | Ano | Identifier organizační jednotky.
roleTypeCode | String (32) | Ano | Kód typu organizační role.

### EosPersonsExtended

Reprezentuje wrapper pro kolekci rozšířených osob.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
personExtended | List<EosPersonExtended> | Ne | Kolekce osob.

### EosPhoneContact

Reprezentuje telefoní kontakt.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
description | String (512) | Ne | Popis telefonu.
contactType | EosContactType | Ne | Typ kontaktu.
contactTypeCategory | EosContactTypeCategory | Ne | Kategorie typu kontaktu.
contact | EosIdentifier | Ne | Id atributu kontaktu.
primary | boolean | Ne | Určuje zda je kontakt primární.
publicable | boolean | Ne | Určuje zda je kontakt veřejný.
prefix | String (80) | Ne | Předvolba.
number | String (80) | Ano | Telefonní číslo.
extension | String (80) | Ne | Linka.

### EosString

Třída reprezentující stringovou hodnotu. Třída slouží k opravě bugu v cxo.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
value | String (1024) | Ne | Hodnota.

### EosUserField

Reprezentuje uživatelské pole.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
name | String (255) | Ano | Jméno uživatelského pole.
content | String (512) | Ano | Hodnota uživatelského pole.
code | String (255) | Ano | Kód uživatelského pole.

### EosUserFields

Reprezentuje kolekci uživatelských polí.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
userField | List<EosUserField> | Ne | Kolekce uživatelských polí.

### EosValue

Reprezentuje hodnotu string atributu, výčtového atributu a selectového atributu. Dále pak hodnoty rozsahu výčtového atributu.

Jméno atributu | Datový typ | Povinné | Popis
--- | --- | --- | ---
id | EosIdentifier | Ano | Identifikátor.
content | String (512) | Ano | Samotná hodnota atributu.
comment | String (512) | Ne | Komentář hodnoty atributu.