Kuba1: Porovnání verzí

Z Prirucky
 
(Není zobrazeno 28 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
|}


=Zpřístupnění KS WebAPI=
==Položky nutné k vyplnění pro vložení pomůcky==
*OsCislo
*CisloPom
*Sklad
*CisPomucky
*Pocet
*DatVyd
*Cena


KS WebAPI je potřeba aktivovat přes Rozšíření aplikace v aplikaci KS mzdy (menu: Nápověda > Rozšíření aplikace).
=Popis=
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'''
==Option==
: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'''
Stav
:Obecné rozhraní pro čtení dat zaměstnanců ze systému KS mzdy.
* '''Použití pro metodu:''' "UpdateData".
 
* '''Datový typ:''' Integer  (Příklad: 'Stav':'1‘).
* '''KS WebAPI Writer'''
* '''Přípustné hodnoty:'''  
:Obecné rozhraní pro čtení a zápis dat zaměstnanců do/ze systému KS mzdy.
** '''0''' – Vrácení pracovní pomůcky
 
** '''1''' – Storno pracovní pomůcky
'''Pro zpřístupnění je potřeba provést tyto kroky:'''
** '''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.
# 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.
 
=Metody webové služby=
 
KS WebAPI nabízí metody: '''GetData''', '''InsertData''', '''UpdateData'''.
 
Všechny metody přebírají v parametru strukturu ''KSWebAPI_Parameters'' a vrací návratovou strukturu ''KSWebAPI_Response''.
 
==GetData==
 
Metoda '''GetData''' vrací data z databáze KS mzdy dle zadaných kritérií.
 
Nastavení parametrů struktury KSWebAPI_Parameters
 
* '''ItemGroup'''
:Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
 
* '''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>
<pre>
[
Metoda = "UpdateData"
[ { "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín",
SkupinaUdaju = "PracovniPomucky"
  "KmenStr": "1", "DatumNastupu": "2019-01-01"},
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'}]
  { "IdPodniku": "1", "Jmeno": "Petr", "Prijmeni": "Test", "RodneCislo": "81101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "101", "PscTrv": "75501", "MistoTrv": "Vsetín",
JsonOptions = {"Stav": "2"}
  "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>
</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>
[{ "KmenStr": "100", "DatumVystupu": "2019-12-31" }]
</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]]
=Aplikační server=
Aplikační server (dále AS)  je samostatný program, který běží jako '''Windows služba''' a mimo jiné zajišťuje hostování webové služby '''KS WebAPI'''.
==Instalace==
Z uložiště KS - program je potřeba stáhnout poslední verzi aplikace MaPSetup, která slouží k instalaci AS: http://download.ksprogram.cz/download/MaPSetup.zip.
V instalaci pokračujte podle příručky: [[Aplikační_server_KS|Aplikační_server_KS]]
==Konfigurace KS WebAPI==
Konfigurace KS WebAPI se provádí převážně v konfiguračním souboru AS. Některá nastavení (např. Správa uživatelů KS WebAPI) se provádí v aplikaci AS SeanceMAnager.
===Konfigurační soubor===
Konfigurace KS WebAPI se provádí v konfiguračním souboru AS 'ASServer.exe.config'. Soubor je uložen v adresáři 'ASServer', v umístění instance AS, které bylo vybráno pro instalaci AS.
V konfiguračním souboru se nastaví Endpoint, Binding, Behavior, případně jiná nastavení.
Níže je uvedena vzorová konfigurace, která využívá zabezpečení s ověřením uživatelského jména na straně klienta a proto je potřeba nastavit certifikát v části '''''<serviceCertificate>'''''
'''Vzorová konfigurace'''
<pre>
<system.serviceModel>
  <services> 
    <service name="KSProgram.AS.WCF.KSWebAPI" behaviorConfiguration="KSWebAPIBehavior">
      <host>
        <baseAddresses>
          <add baseAddress="http://localhost:9001/KSAsServer/WebService/WebAPI"/>
        </baseAddresses>
      </host>
      <endpoint address=""
                binding="wsHttpBinding"
                bindingConfiguration="KSWebAPIBinding"
                contract="KSProgram.AS.WCF.IKSWebAPI" />
    </service>
  </services>
  <bindings>
      <wsHttpBinding>
        <binding name="KSWebAPIBinding">
      <security mode="Message">
  <message clientCredentialType="UserName" />
</security>
<readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
        maxArrayLength="2147483647" 
        maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
</binding>
      </wsHttpBinding>
    </bindings>
    <behaviors>
      <serviceBehaviors>
        <behavior name="KSWebAPIBehavior">
  <serviceMetadata httpGetEnabled="true"/>
  <serviceDebug includeExceptionDetailInFaults="true"/>
  <serviceCredentials>
      <userNameAuthentication userNamePasswordValidationMode="Custom" 
            customUserNamePasswordValidatorType="KSProgram.AS.WCF.PasswordValidator, WCFLib"/>
  <serviceCertificate findValue="WebAPI_cert" storeLocation="LocalMachine" 
            storeName="My" x509FindType="FindBySubjectName"/>
  </serviceCredentials>
</behavior>
      </serviceBehaviors>
    </behaviors>
</system.serviceModel>
</pre>
===AS SeanceManager===
AS SeanceManager (dále ASSM) je aplikace, která byla nainstalována společně s AS a slouží ke správě AS (spouštění instancí AS, konfigurace úloh, kontrola stavu úloh, atd.), viz obr. 1.  ASSM je umístěn v adresáři, který byl vybrán pro instalaci AS (''…\KS-AS\ASSeanceManager\ASSeanceManager.exe'').
V případě KS WebAPI je zde typ úlohy ''''Webová služba KSWebAPI'''' (Kód = 73) v seznamu '''Typy úlohy'''. V části 'Nastavení webové služby' se provádí nastavení uživatelských účtů pro autentizaci.
ASSM (soubor '''ASSeanceManager.exe''') je nutné spouštět jako '''správce'''.
[[Soubor:Nastaveni-as-seancemanager-webapi.jpg|450px]]
===Správa uživatelů===
V ASSM se provádí nastavení uživatelských účtů pro autentizaci. V sekci ''''Nastavení webové služby'''' se po stisku tlačítka 'Správa uživatelů' otevře příslušné okno .
[[Soubor:Sprava-uzivatelu-KS-WEBAPI.jpg]]
[[Soubor:Pristupova-prava-polozky-ks-webapi.jpg]]

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“