KS WebAPI

Z Prirucky

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í.

Komunikační protokol

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.

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:

  1. V aplikaci KS mzdy, v okně 'Rozšíření aplikace' (menu: Nápověda > Rozšíření aplikace), aktivovat požadované rozšíření.
  2. Provést úpravu databáze.
  3. 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.

Operace dostupné pomocí KS WebAPI

V tabulce jsou uvedeny pouze hlavní operace dostupné všem zákazníkům. Někteří zákazníci mohou mít zpřístupněny další specifické operace. Vždy je nutné vygenerovat si dokumentaci k WebAPI pomocí C/S aplikace.

Souhrn údajů Čtení Zápis Význam
PracovniPomucky Ano Ano Přiřazení prac. pomůcek zaměstnancům
ZpracovaneMzdy Ano Ne Mzdy zaměstnanců a odvody podniku.
JazykoveZnalosti Ano Ano Jazykové znalosti zaměstnanců
Dovolena Ano Ne Dovolená v hodinách (legislativa 2021)
Divize Ano Ano Číselník divizí
BenefitniVolno Ano Ne Benefitní volna zaměstnanců
ZpracovanaDochazka Ano Ano Sesumovaná docházková data pro mzdy
Platby Ano Ano Platby zaměstanců
PracovniMista Ano Ano Číselník pracovních míst
PracovniPomery Ano Ano Pracovněprávní poměry zaměstnanců
PracovniPostup Ano Ne Pracovní postup zaměstnanců
PracovniPovoleni Ano Ano Pracovní povolení cizinců
KmenoveUdaje Ano Ano Evidence zaměstnanců
RodinniPrislusnici Ano Ano Rodinní příslušníci
RodinniPrislusniciSlevy Ano Ano Daňové zvýhodnění rodinných příslušníků
SkupinyStredisek Ano Ano Číselník skupiny středisek
SluzebniCestyVydaje Ano Ne Cestovní výdaje/náhrady
SluzebniCesty Ano Ne Služební cesty
SluzebniCestyVyuctovani Ano Ne Vyúčtování služebních cest
SluzebniCestyZalohy Ano Ne Zálohy na služební cesty
Strediska Ano Ano Číselník středisek
Kontakty Ano Ano Kontakty (telefonní čísla, emaily)
Vzdelani Ano Ano Dosažené vzdělání zaměstnanců
KumulacePoVyuctovani Ano Ne Měsíční kumulace a další údaje po vyúčtování za os.číslo.

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).
  • JsonOptions - nepovinný údaj, slouží pro doplnění speciálních parametrů, které ovlivní zpracovávanou skupinu údajů.


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 

[
    [{ "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"}]
]

Příklad dat pro vložení více záznamů 

[
 [ { "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"}
 ]
]


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ů 

[{ "KmenStr": "100", "DatumVystupu": "2019-12-31" }]
  • JsonSearchCriteria - předá se vyhledávací podmínka v JSON formátu, pro omezení množiny dat, které mají být změněny.
  • JsonOptions - nepovinný údaj, slouží pro doplnění speciálních parametrů, které ovlivní zpracovávanou skupinu údajů.

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ů.
  • JsonOptions - vlastnost slouží pro doplnění speciálních parametrů, které ovlivní zpracovávanou skupinu údajů.

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

<security>
  <message clientCredentialType="UserName" />
</security>

Uživatelé se evidují v okně 'Správa uživatelů'

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


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 

<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>


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.

Nastaveni-as-seancemanager-webapi.jpg

Správa uživatelů

V AS SeanceManageru 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 .

Sprava-uzivatelu-KS-WEBAPI.jpg

Oprávnění na položky

V AS SeanceManageru se provádí nastavení oprávnění 'Čtení' a 'Zápis' na položky pro jednotlivé skupiny položek. V sekci 'Nastavení webové služby' se po stisku tlačítka 'Přístupová práva' otevře příslušné okno

Pristupova-prava-polozky-ks-webapi.jpg

Spuštění KS WebAPI

Pro spuštění KS WebAPI je potřeba mít aktivní úlohu 'Webová služba KSWebAPI' (Kód = 73). Aktivace / Deaktivace se provádí tlačítkem Aktivovat vybranou úlohu / Deaktivovat vybranou úlohu. Dále je potřeba mít spuštěnou instanci AS. Spuštění / Zastavení instance AS se provádí tlačítkem Spustit instanci KS-AS / Zastavit instanci KS-AS.

Chybové stavy

Při požadavku zaslaném klientem na KS WebAPI jsou případné chybové stavy odesílány zpět klientovi v návratovém typu KSWebAPI_Response, atributu ErrorMessage. Některé typy výjimek (např. databázové chyby) jsou navíc logovány v event logu systému windows.

Klientská aplikace

Klientská aplikace se vytvoří na základě znalosti popisu webové služby KS WebAPI (WSDL). WSDL je dostupné v umístění webové služby. Dle zde uvedeného vzorového konfiguračního souboru tomu odpovídá: http://localhost:9001/KSAsServer/WebService/WebAPI?wsdl

Níže je uveden příklad zdrojového kódu v C#, který provádí volání GetData z KS WebAPI.

Vzorová konfigurace 

ServiceReference_KSWS.KSWebAPI_Parameters par = new ServiceReference_KSWS.KSWebAPI_Parameters();

// Požadované údaje.
par.Items = "OsCislo, Jmeno, Prijmeni, KmenStr, DatumNastupu, DatumVystupu";

// Skupina údajů.
par.ItemGroup = "KmenoveUdaje";

// Nastavení vyhedávacího kritéria.
par.JsonSearchCriteria = @"[
                               { 'Item': 'OsCislo', 'Operator': '<=', 'Value': 100 },
                               'AND',
                               { 'Item': 'DatumNastupu', 'Operator': '>=', 'Value': '2000-01-01' }
                           ]".Replace("'", "\"");


ServiceReference_KSWS.KSWebAPIClient client = new ServiceReference_KSWS.KSWebAPIClient("WSHttpBinding_IKSWebAPI");
try
{
    // Zadání uživatelského jména a hesla pro autentizaci.
    client.ClientCredentials.UserName.UserName = "uzivatel";
    client.ClientCredentials.UserName.Password = "test";

    // Zavolání metody webové služby.
    resp = client.GetData(par); // Získání dat.

    // Zpracování výsledku.
    string code = resp.StatusCode; // Stavový kód. (200 - OK, 500 - chyba)
    string data = resp.Data; // Data.
    string errorMessage = resp.ErrorMessage; // Chybová správa.

    client.Close(); // Uzavření klienta.
}
catch (Exception ex)
{
    client.Abort();
}

Odkazy

Citováno z „http://prirucky.ksprogram.cz/index.php?title=KS_WebAPI&oldid=41977“