Kuba1: Porovnání verzí

Z Prirucky
 
(Není zobrazeno 39 mezilehlých verzí od 2 dalších uživatelů.)
Řádek 1: Řádek 1:
KS WebAPI je webová služba postavená na technologii Windows Communication Foundation. Umožňuje předávat údaje z databáze KS mzdy klientské aplikaci nebo ukládat údaje do databáze KS mzdy zaslané klientskou aplikací.
=Čtení pomocí WebAPI=
{|border="1" cellpadding="3" cellspacing="0"
|- style="background-color: #eeeeee"
|'''Údaj'''
|'''Datový typ'''
|'''Význam'''
                    |-
|OsCislo
|decimal(10,0)
|Os. číslo zaměstnance
                   
                    |-
|CisloPom
|smallint
|Číslo poměru zaměstnance
                   
                    |-
|Sklad
|char(10)
|Identifikace skladu
                   
                    |-
|CisPomucky
|char(12)
|Číslo pomůcky
                   
                    |-
|Pocet
|decimal(10,3)
|Vydané množství
                   
                    |-
|DatVyd
|date
|Datum výdeje
                   
                    |-
|Cena
|decimal(8,2)
|Cena pomůcky
                    |-
|CisPol
|integer
|Číslo záznamu v rámci skladu a čísla pomůcky
                    |-
|IdVyd
|integer
|Identifikace výdejky v rámci skladu, pomůcky, cis_pol
                    |-
|DatVrac
|date
|Datum vrácení
                    |-
|DuvVrac
|char(7)
|Důvod vrácení
                    |-
|DatStor
|date
|Datum storna
                    |-
|PrevNaOsCislo
|decimal(10,0)
|Osobní číslo zaměstnance, na kterého byla pomůcka převedena
                    |-
|PrevNaCisloPom
|smallint
|Číslo poměru zaměstnance, na kterého byla pomůcka převedena
|}


==Komunikační protokol==
=Zápis pomocí WebAPI=
Pro hostování webové služby se využívá KS aplikační server. Komunikačním protokolem je http, případně ve spojení se SSL (HTTPS). Pro výměnu zpráv se používá protokol SOAP. Ve výchozím nastavení je připraven typ endpointu wsHttpBinding.
{|border="1" cellpadding="3" cellspacing="0"
|- style="background-color: #eeeeee"
|'''Údaj'''
|'''Datový typ'''
|'''Povinné pole'''
|'''Význam'''
                    |-
|OsCislo
|decimal(10,0)
|Ano
|Os. číslo zaměstnance
                   
                    |-
|CisloPom
|smallint
|Ano
|Číslo poměru zaměstnance
                   
                    |-
|Sklad
|char(10)
|Ano
|Identifikace skladu
                   
                    |-
|CisPomucky
|char(12)
|Ano
|Číslo pomůcky
                   
                    |-
|Pocet
|decimal(10,3)
|Ne
|Vydané množství
                   
                    |-
|DatVyd
|date
|Ano
|Datum výdeje
                   
                    |-
|Cena
|decimal(8,2)
|Ne
|Cena pomůcky
|-
|CisPol
|integer
|Ne
|Číslo záznamu v rámci skladu a čísla pomůcky
                    |-
|IdVyd
|integer
|Ne
|Identifikace výdejky v rámci skladu, pomůcky, cis_pol
                    |-
|DatVrac
|date
|Ano
|Datum vrácení
                    |-
|DuvVrac
|char(7)
|Ano
|Důvod vrácení
                    |-
|DatStor
|date
|Ne
|Datum storna
                    |-
|PrevNaOsCislo
|decimal(10,0)
|Ne
|Osobní číslo zaměstnance, na kterého byla pomůcka převedena
                    |-
|PrevNaCisloPom
|smallint
|Ne
|Číslo poměru zaměstnance, na kterého byla pomůcka převedena
|}


=Metody webové služby=
==Položky nutné k vyplnění pro vložení pomůcky==
*OsCislo
*CisloPom
*Sklad
*CisPomucky
*Pocet
*DatVyd
*Cena


KS WebAPI nabízí metody: '''GetData''', '''InsertData''', '''UpdateData'''.
=Popis=


Všechny metody přebírají v parametru strukturu ''KSWebAPI_Parameters'' a vrací návratovou strukturu ''KSWebAPI_Response''.
==Option==


==GetData==
Stav
 
* '''Použití pro metodu:''' "UpdateData".
Metoda '''GetData''' vrací data z databáze KS mzdy dle zadaných kritérií.
* '''Datový typ:''' Integer  (Příklad: 'Stav':'1‘).
 
* '''Přípustné hodnoty:'''  
Nastavení parametrů struktury KSWebAPI_Parameters
** '''0''' – Vrácení pracovní pomůcky
 
** '''1''' – Storno pracovní pomůcky
* '''ItemGroup'''
** '''2''' – Převod na jinou osobu
:Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
* '''Funkcionalita:''' Při jeho vyplnění budou vráceny, stornovány případně převedeny pracovní pomůcky. Jiná funkcionalita není v tomto případě definována a není nijak jinak možné zasahovat do této struktury z důvodu udržení integrity dat. Při použití toho Option není nutné definovat vyhledávací podmínku '''JsonSearchCriteria''', může tedy zůstat nevyplněna.
 
* '''Items'''
:Předá se seznam položek, které budou v návratové datové struktuře. Jednotlivé položky se oddělí čárkou (Příklad: OsCislo, Jmeno, Prijmeni).
 
* '''JsonSearchCriteria'''
:Předá se vyhledávací podmínka v JSON formátu.
 
 
Popis údajů v návratové struktuře '''KSWebAPI_Response'''
 
* '''Data'''
:Očekávané data vyhovující podmínce v JsonSearchCriteria ve formátu JSON.
 
==InsertData==
 
Metoda '''InsertData''' zapisuje data do databáze KS mzdy.
 
Nastavení parametrů struktury '''KSWebAPI_Parameters'''
 
* '''ItemGroup'''  
:Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
 
* '''JsonChangeData'''
:Povinný údaj. V JSON struktuře se předají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o pole, kde v jednotlivých objektech pole jsou data pro insert.
 
 
'''Příklad dat pro vložení jednoho záznamu'''
<pre>
[
    [{ "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-01-01"}]
]
</pre>
 
'''Příklad dat pro vložení více záznamů'''
<pre>
[
[ { "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín",
  "KmenStr": "1", "DatumNastupu": "2019-01-01"},
  { "IdPodniku": "1", "Jmeno": "Petr", "Prijmeni": "Test", "RodneCislo": "81101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "101", "PscTrv": "75501", "MistoTrv": "Vsetín",
  "KmenStr": "1", "DatumNastupu": "2019-02-01"},
  { "IdPodniku": "1", "Jmeno": "Marie", "Prijmeni": "Nová", "RodneCislo": "820101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "102", "PscTrv": "75501", "MistoTrv": "Vsetín",
  "KmenStr": "1", "DatumNastupu": "2019-03-01"}
]
]
</pre>
 
 
Popis údajů v návratové struktuře '''KSWebAPI_Response'''
 
*'''Data'''
:V JSON formátu jsou předána data, která byla vložena do databáze.
 
==UpdateData==
Metoda '''UpdateData''' provádí změnu dat v databázi KS mzdy.
 
Nastavení parametrů struktury '''KSWebAPI_Parameters'''
 
* '''ItemGroup'''
:Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
 
* '''JsonChangeData'''
:Povinný údaj. V JSON struktuře se předají data, která mají být změněna v databázi KS mzdy. Vždy se jedná o pole. V poli by měl být pouze jeden objekt s měněnými položkami.
 
'''Příklad dat pro změnu údajů'''
<pre>
<pre>
[{ "KmenStr": "100", "DatumVystupu": "2019-12-31" }]
Metoda = "UpdateData"
SkupinaUdaju = "PracovniPomucky"
Data = [{'OsCislo': '1','CisloPom': '0','Sklad': '001','CisPomucky': '05','Pocet': '1','DatVyd':'2021-05-24','Cena':'NULL','IdVyd':'73','CisPol':'1','PrevNaOsCislo':'3','PrevNaCisloPom':'0'}]
JsonOptions = {"Stav": "2"}
</pre>
</pre>
* '''JsonSearchCriteria'''
:Předá se vyhledávací podmínka v JSON formátu, pro omezení množiny dat, které mají být změněny.
=KSWebAPI_Parameters=
Struktura obsahuje parametry:
* '''ItemGroup''' 
:Povinný údaj. Předává se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
* '''Items'''
:Vyplňuje se v případe volání metody '''GetData'''. Předává se seznam položek, které budou v návratové datové struktuře, na které má uživatel oprávnění. Jednotlivé položky se oddělují čárkou (Příklad: OsCislo, Jmeno, Prijmeni).
* '''JsonChangeData'''
:Vyplňuje se v případe volání metody '''InsertData''' nebo '''UpdateData'''. V JSON struktuře se předávají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o JSON pole.
* '''JsonSearchCriteria'''
:Slouží k předání vyhledávacích kritérií pro omezení množiny zpracovávaných údajů. Podmínka se zapisuje v JSON formátu. Vyhledávací kritérium se skládá z výrazů (výraz obsahuje atributy 'Item', 'Operator', 'Value'), přičemž může být zadán buď jediný výraz nebo složený, oddělený logickými operátory.
Přípustné logické operátory: '''OR, AND'''
Přípustné operátory porovnání:''' =, <=, >=, >, <, LIKE, NOT LIKE, IN, NOT IN'''
===Příklady===
'''1 (jednoduchý výraz)'''
<pre>
[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 }
]
</pre>
'''1 AND 2'''
<pre>
[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 },
    "AND",
    { "Item": "DatumNastupu", "Operator": ">=", "Value": "2000-01-01" }
]
</pre>
'''1 OR 2'''
<pre>
[
    { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
    "OR",
    { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
]
</pre>
'''(1 OR 2) AND (3 OR 4)'''
<pre>
[
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
        "OR",
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" }
    ],
    "AND",
    [
        { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
        "OR",
        { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
    ]
]
</pre>
'''1 OR (2 AND (3 OR 4))'''
<pre>
[
    { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
    "OR",
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" },
        "AND",
        [
            { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
            "OR",
            { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
        ]
    ]
]
</pre>
=KSWebAPI_Response=
Struktura obsahuje parametry:
* '''ResponseDatetime'''
:Datum a čas odpovědi.
* '''StatusCode'''
:Stav odpovědi. 200 – OK, 500 – chyba.
* '''Message'''
:Zpráva odpovědi.
* '''IsError'''
:Indikace zda nastala chyba.
* '''ErrorMessage'''
:Chybová zpráva o chybovém stavu při zpracování metody.
* '''Data'''
:Data ve formátu JSON.
=Autentizace=
Pro ověření uživatele se používá UserName autentizace, kdy se předává jméno a heslo uživatele při volání metody webové služby v části ClientCredentials.
Tato metoda musí být nastavena v konfiguračním souboru klienta.
==Příklady==
<pre>
<security>
  <message clientCredentialType="UserName" />
</security>
</pre>
Uživatelé se evidují v okně ''''Správa uživatelů''''
[[Soubor:Sprava-uzivatelu-KS-WEBAPI.jpg]]
=Zpřístupnění KS WebAPI=
KS WebAPI je potřeba aktivovat přes Rozšíření aplikace v aplikaci KS mzdy (menu: Nápověda > Rozšíření aplikace).
Jsou dostupné 3 varianty, které se liší množinou zpracovávaných dat a povolením pro čtení a zápis údajů:
* '''KS WebAPI Free'''
:Bezplatná verze obecného rozhraní pro čtení dat zaměstnanců ze systému KS mzdy. Umožňuje čtení omezené množiny položek ze skupiny údajů 'KmenoveUdaje'.
* '''KS WebAPI Reader'''
:Obecné rozhraní pro čtení dat zaměstnanců ze systému KS mzdy.
* '''KS WebAPI Writer'''
:Obecné rozhraní pro čtení a zápis dat zaměstnanců do/ze systému KS mzdy.
'''Pro zpřístupnění je potřeba provést tyto kroky:'''
# V aplikaci KS mzdy, v okně 'Rozšíření aplikace' (menu: Nápověda > Rozšíření aplikace), aktivovat požadované rozšíření.
## Provést úpravu databáze.
### V aplikaci KS mzdy spustit úlohu WebAPI (menu: Systém > Web API). Potvrzením volby 'Ano' dojde k vygenerování dokumentace k přenášeným údajům (ve formě HTML). Generování dokumentace je potom potřeba  provádět vždy, pokud bude vydaná nová verze KS WebAPI.

Aktuální verze z 15. 6. 2021, 08:26

Čtení pomocí WebAPI

Údaj Datový typ Význam
OsCislo decimal(10,0) Os. číslo zaměstnance
CisloPom smallint Číslo poměru zaměstnance
Sklad char(10) Identifikace skladu
CisPomucky char(12) Číslo pomůcky
Pocet decimal(10,3) Vydané množství
DatVyd date Datum výdeje
Cena decimal(8,2) Cena pomůcky
CisPol integer Číslo záznamu v rámci skladu a čísla pomůcky
IdVyd integer Identifikace výdejky v rámci skladu, pomůcky, cis_pol
DatVrac date Datum vrácení
DuvVrac char(7) Důvod vrácení
DatStor date Datum storna
PrevNaOsCislo decimal(10,0) Osobní číslo zaměstnance, na kterého byla pomůcka převedena
PrevNaCisloPom smallint Číslo poměru zaměstnance, na kterého byla pomůcka převedena

Zápis pomocí WebAPI

Údaj Datový typ Povinné pole Význam
OsCislo decimal(10,0) Ano Os. číslo zaměstnance
CisloPom smallint Ano Číslo poměru zaměstnance
Sklad char(10) Ano Identifikace skladu
CisPomucky char(12) Ano Číslo pomůcky
Pocet decimal(10,3) Ne Vydané množství
DatVyd date Ano Datum výdeje
Cena decimal(8,2) Ne Cena pomůcky
CisPol integer Ne Číslo záznamu v rámci skladu a čísla pomůcky
IdVyd integer Ne Identifikace výdejky v rámci skladu, pomůcky, cis_pol
DatVrac date Ano Datum vrácení
DuvVrac char(7) Ano Důvod vrácení
DatStor date Ne Datum storna
PrevNaOsCislo decimal(10,0) Ne Osobní číslo zaměstnance, na kterého byla pomůcka převedena
PrevNaCisloPom smallint Ne Číslo poměru zaměstnance, na kterého byla pomůcka převedena

Položky nutné k vyplnění pro vložení pomůcky

  • OsCislo
  • CisloPom
  • Sklad
  • CisPomucky
  • Pocet
  • DatVyd
  • Cena

Popis

Option

Stav

  • Použití pro metodu: "UpdateData".
  • Datový typ: Integer (Příklad: 'Stav':'1‘).
  • Přípustné hodnoty:
    • 0 – Vrácení pracovní pomůcky
    • 1 – Storno pracovní pomůcky
    • 2 – Převod na jinou osobu
  • Funkcionalita: Při jeho vyplnění budou vráceny, stornovány případně převedeny pracovní pomůcky. Jiná funkcionalita není v tomto případě definována a není nijak jinak možné zasahovat do této struktury z důvodu udržení integrity dat. Při použití toho Option není nutné definovat vyhledávací podmínku JsonSearchCriteria, může tedy zůstat nevyplněna.
Metoda = "UpdateData"
SkupinaUdaju = "PracovniPomucky"
Data = [{'OsCislo': '1','CisloPom': '0','Sklad': '001','CisPomucky': '05','Pocet': '1','DatVyd':'2021-05-24','Cena':'NULL','IdVyd':'73','CisPol':'1','PrevNaOsCislo':'3','PrevNaCisloPom':'0'}]
JsonOptions = {"Stav": "2"}
Citováno z „http://prirucky.ksprogram.cz/index.php?title=Kuba1&oldid=41783“