Kuba1

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.

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

[
    [{ "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.

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)

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 }
]

1 AND 2

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 },
    "AND",
    { "Item": "DatumNastupu", "Operator": ">=", "Value": "2000-01-01" }
]

1 OR 2

[
    { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
    "OR",
    { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
]

(1 OR 2) AND (3 OR 4)

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

1 OR (2 AND (3 OR 4))

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

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

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>