Proměnné

Datové typy

Do proměnných se mohou ukládat následující datové typy:

STRING (řetězcové (znakové) proměnné).
INTEGER (celočíselné numerické proměnné).
DECIMAL (dekadické numerické proměnné (s desetinnou čárkou).
BOOLEAN (pro ukládání logických hodnot true (pravda) a false (nepravda).
DATETIME (pro ukládání hodnot typu datum a čas).
GUID (představuje 128bitovou globálně jedinečnou hodnotu).
XML (zápis dat podle syntaxe XML – eXtensible Markup Language, neboli rozšiřitelný značkovací jazyk, který umožňuje efektivní výměnu dat mezi různými aplikacemi a systémy ).
JSON (JavaScript Object Notation k zápisu krátkých strukturovaných dat vyměňovaných webovými aplikacemi. Je jedním z nejpoužívanějších formátů pro výměnu dat na webu.).

Data, s kterými agenda pracuje, se dělí do několika kategorií podle toho, kde všude mají být k dispozici.

FormData – formulářové proměnné

Tyto proměnné:

Jsou k dispozici pouze v rámci formuláře.
Žádným způsobem se neodesílají do Sofa.
Po odeslání formuláře jsou z pohledu agendy uložené hodnoty ztracené.
Lze je využívat například pro pomocné výpočty, k přepínání oddílů apod.

FormData jsou tedy speciální kategorie dat, platná v rámci jednoho formuláře. Tato data se nepřenáší do dalších uzlů procesu, každý formulář může mít jiná FormData.

FormData se obvykle využívají jen v rámci jednoho formuláře jako pomocné proměnné nebo pro optimalizaci procesu, aby se vše zbytečně neukládalo do proměnných agendy.

FormData je možné uložit do proměnných formuláře, nebo zpracovávat v procesním JavaScriptu daného uzlu.

S formulářovými proměnnými se pracuje pomocí tradičního formulářového JavaScriptu, například pomocí funkcí DataXpath, SetData, SetDataTo atd.

Variables – agendové proměnné

Tyto proměnné slouží k uchování dat mezi jednotlivými uzly grafu a jsou dostupné v průběhu celé agendy.

Jsou vázané na token = každý token si sebou nese své hodnoty proměnných.
K jejich hodnotám lze přistupovat v rámci PAJSu, nelze se k nim dostat pomocí GraphQL.
Pokud se v agendě používají paralelní úkoly a má dojít ke jejich sjednocení, je nutné pomocí skriptu sjednotit hodnoty z jednotlivých tokenů do nově vzniklého sjednoceného tokenu, toto musí zajistit návrhář agendy.

Mají plochou strukturu, tedy není možné v nich vytvářet stromovou strukturu. Proměnná typu XML ale může obsahovat větvené XML, jehož elementy je možné napojovat do formuláře.

V případě paralelního běhu procesu (popisuje kapitola Paralelní brána) si každý token si nese své hodnoty proměnných. Pokud se tedy mají větve paralelního běhu později slučovat, je nutné do agendy vložit vlastní procesní JavaScript, který vyhodnotí proměnné ze všech tokenů.

U agendových proměnných lze zjišťovat jejich existenci, zda má proměnná nastaveno hodnotu, obnovit její výchozí hodnotu a ukládat nové hodnoty. Všechny metody se volají nad objektem Variables.

Zjištění existence proměnné

Výsledkem metody HasVariable je logická hodnota true / faIlse (typ boolean).

if (Variables.HasVariable("nazev_promenne")) Log.DbgLog("Proměnná existuje");
else Log.DbgLog("Proměnná neexistuje");

Zjištění, zda má daná proměnná nastavenou hodnotu

Výsledkem metody HasValue je hodnota typu boolean.

if (Variables.HasValue("nazev_promenne")) Log.DbgLog("Proměnná má nastavenou hodnotu");
else Log.DbgLog("Proměnná nemá nastavenou hodnotu");

Nastavení hodnoty proměnné

U nastavení hodnoty metodou SetValue je nutné hlídat si správný typ proměnné. Například do agendové proměnné typu DECIMAL nepůjde uložit javascriptová proměnná typu STRING a může dojít k chybě.

Do textové proměnné lze ukládat text:

Variables.SetValue("nazev_promenne_typu_string", "hodnota_k_nastaveni");

Do celočíselné proměnné lze ukládat celá čísla (zadávaná bez uvozovek):

Variables.SetValue("nazev_promenne_typu_integer", 123);

Do desetinné proměnné lze ukládat desetinná čísla (zadávaná bez uvozovek):

Variables.SetValue("nazev_promenne_typu_decimal", 123.456);

Do booleovské proměnné lze ukládat booleovskou informaci (bez uvozovek true/false):

Variables.SetValue("nazev_promenne_typu_boolean", true);

Do datetime proměnné je nutné ukládat javascriptový objekt DateTime. V příkladu je vytvořen nový objekt, který obsahuje datum vytvoření:

 Variables.SetValue("nazev_promenne_typu_datetime", new Date());

Do XML proměnné je nutné vkládat objekt typu xdocument, který lze vytvořit buď ručně v PAJSu (viz níže). Případně je možné načítat hodnotu jiné proměnné typu XML a s tímto objektem dále pracovat. Práce s xdocumentem bude vysvětlena v dalších kapitolách.

var xdocument = ParseXDocument("<root></root>");
Variables.SetValue("nazev_promenne_typu_xml", xdocument);

Do JSON proměnné je nutné vkládat JSON objekt, níže ukázka vytvoření prázdného objektu:

var json = {};
Variables.SetValue("nazev_promenne_typu_json", json);

Získání hodnoty proměnné

Při získávání hodnoty proměnné metodou GetValue je vždy návratovou hodnotou objekt typu dané proměnné. Tedy při získání hodnoty typu BOOLEAN se vrací JS proměnná typu boolean.

Pokud daná proměnná hodnotu neobsahuje, dojde k chybě. V případě, že proměnná nemusí mít nastavenou hodnotu, je dobré nejprve zjistit, zda proměnná existuje.

if (Variables.HasValue("nazev_promenne")
    {
        var jspromenna = Variables.GetValue("nazev_promenne");
    }
else Log.DbgLog("Proměnná nemá nastavenou hodnotu, nelze ji získat");

Výmaz hodnoty proměnné

Metodou ResetValue lze vymazat hodnotu proměnné.

Variables.ResetValue("nazev_promenne");

Global Variables – globální proměnné

Global Variables jsou proměnné, které mají platnost v celé agendě.

Tyto proměnné:

Jsou vázané na instanci agendy.
Lze k nim přistupovat pomocí PAJSu i GraphQL (lze tedy například získávat jejich hodnoty pomocí API).
Jejich hodnoty lze automaticky zapisovat do databázové tabulky a automaticky aktualizovat na základě pohybu tokenu.
Kromě identifikátoru instance lze hodnoty rozlišovat ještě common identem, na základě common identu lze tedy uložit hodnotu globální proměnné, ke které budou mít přístup i jiné agendy (příkladem může být například uložení bankovního účtu nebo registrační značky vozidla, přičemž common identem je identifikátor přihlášeného uživatele - v agendě je možné využít uloženou hodnotu a tak uživateli např. vyplnit číslo bankovního účtu, které vyplnil jako poslední), tento mechanismus je vysvětlený níže.
Globální proměnné lze označit jako konfigurační a používat je k ovlivnění chování agendy.
Jsou nejnáročnější na databázový výkon, neměly by se tedy využívat zbytečně.

S globálními proměnnými lze provádět v podstatě stejné operace jako s normálními proměnnými, ale je zde nutné dbát na to, že je zapotřebí je dále upřesnit pomocí dvou identifikátorů.

Buď lze použít instance ident, nebo common ident, případně kombinaci obojího.

Existují ještě speciální systémové globální proměnné, které jsou vždy vázány na identifikátor instance a nelze do nich ručně zapisovat žádné hodnoty, jsou plněny vždy automaticky. Výjimkou je proměnná sys_serialnumber, do které lze ručně zapsat pořadové číslo, ale zápis lze provést pouze jednou. Zapsanou hodnotu tedy není možné změnit.

Systémové globální proměnné jsou následující:

Název	Popis
sys_authorident	Obsahuje identifikátor autora instance agendy
sys_authorname	Obsahuje jméno autora instance agendy
sys_authortype	Obsahuje typ autora instance agendy
sys_instanceident	Obsahuje jednoznačný identifikátor dané instance
sys_processstate	Obsahuje stav procesu, je možné nastavovat pomocí funkce SetState (viz další kapitoly)
sys_serialnumber	Obsahuje pořadové číslo dané instance, je možné jednou ručně zapsat hodnotu

Název

Popis

sys_authorident

Obsahuje identifikátor autora instance agendy

sys_authorname

Obsahuje jméno autora instance agendy

sys_authortype

Obsahuje typ autora instance agendy

sys_instanceident

Obsahuje jednoznačný identifikátor dané instance

sys_processstate

Obsahuje stav procesu, je možné nastavovat pomocí funkce SetState (viz další kapitoly)

sys_serialnumber

Obsahuje pořadové číslo dané instance, je možné jednou ručně zapsat hodnotu

Globální proměnné také mohou být nastavené jako konfigurační. Konfigurační proměnná musí mít vždy nastavenou výchozí hodnotu, kterou lze změnit:

Přímo přes rozhraní Sofa (Administrace > Správa agend > vybraná agenda > tři tečky > Upravit konfigurační proměnné agendy). Zde je možné zadat nové hodnoty, které se pak v rámci agendy využívají. Příkladem využití může být například výše částky, při které je nutné agendu schválit dalším schvalovatelem. Výchozí hodnota v agendě je 10000, ale v rámci konfigurace přes rozhraní je možné nastavit výši částky např. 100000. V tuto chvíli bude další schvalovatel schvalovat jen částky nad 100000, aniž by bylo nutné zasahovat do agendy a znovu ji publikovat.
Dále je u globální proměnné možné nastavit, zda je zasílaná. Pokud je toto nastavení povoleno, znamená to, že tuto proměnnou lze plnit pomocí GraphQL, například z API. Pokud toto nastavení není pro proměnnou povoleno, lze s ní pracovat pouze v rámci agendy a vůbec není zobrazena v GraphQL schématu.

U globálních proměnných lze zjišťovat jejich existenci, zda má proměnná nastaveno hodnotu, obnovit její výchozí hodnotu a ukládat nové hodnoty. Všechny metody se volají nad objektem GlobalVariables.

Zjištění existence globální proměnné

Výsledkem je hodnota typu boolean.

Využití instance identu:

if (GlobalVariables.HasVariable("nazev_promenne",InstanceInfo.InstanceIdent,"")) Log.DbgLog("Globální proměnná existuje");
else Log.DbgLog("Globální proměnná neexistuje");

Zjištění, zda má daná globální proměnná nastavenou hodnotu

Výsledkem je hodnota typu boolean.

Využití instance identu:

if (Variables.HasValue("nazev_promenne",InstanceInfo.InstanceIdent,"")) Log.DbgLog("Globální proměnná má nastavenou hodnotu");
else Log.DbgLog("Globální proměnná nemá nastavenou hodnotu");

Nastavení hodnoty proměnné

U nastavení hodnoty je nutné hlídat si správný typ proměnné. Například do agendové proměnné typu DECIMAL nepůjde uložit javascriptová proměnná typu STRING a může dojít k chybě.

Je možné nastavovat i hodnoty proměnných, které nejsou definovaný ve vlastnostech. V takovém případě je proměnná automaticky vytvořena, ale není nikde zobrazena a je nutné si pamatovat její název a přistupovat do ní pouze v rámci PAJSu.

Využití instance identu:

GlobalVariables.SetValue("nazev_promenne", InstaceInfo.InstanceIdent, "", "hodnota_k_nastaveni");

Využití common identu:

GlobalVariables.SetValue("nazev_promenne_2", null, "hodnota_common_identu", "hodnota_k_nastaveni");

Využití obou identů:

GlobalVariables.SetValue("nazev_promenne_3", InstanceInfo.InstanceIdent, "hodnota_common_identu", "hodnota_k_nastaveni");

Získání hodnoty globální proměnné

Při získávání hodnoty proměnné je vždy návratovou hodnotou objekt typu dané proměnné. Tedy při získání hodnoty typu BOOLEAN se vrací JS proměnná typu boolean.

Pokud daná proměnná hodnotu neobsahuje, dojde k chybě. V případě, že proměnná nemusí mít nastavenou hodnotu, je dobré nejprve zjistit, zda proměnná existuje. Opět je důležité hlídat si zadání správného instance identu nebo common identu.

Využití instance identu:

GlobalVariables.GetValue("nazev_promenne", InstaceInfo.InstanceIdent, "");

Využití common identu:

GlobalVariables.GetValue("nazev_promenne_2", null, "hodnota_common_identu");

Využití obou identů:

GlobalVariables.GetValue("nazev_promenne_3", InstanceInfo.InstanceIdent, "hodnota_common_identu");

Výmaz hodnoty globální proměnné

GlobalVariables.ResetValue("nazev_promenne",InstanceInfo.InstanceIdent,"");

Sofa databáze

Kromě dat specifických pro danou agendu je možné pracovat i s dalšími daty, sdílenými mezi různými agendami.

K tomu slouží uživatelská databáze v Sofa. V ní má každá firma své databázové schéma, ve kterém si může vytvářet svoje uživatelské tabulky. Firmy si do databází navzájem přistupovat nemohou.

Práce s databází

Do prostředí pro práci s databázemi se dostanete v okně Administrace po klepnutí na tlačítko Datové zdroje. Chcete-li vytvořit nový datový zdroj, klepněte na tlačítko Nový datový zdroj.

Zdroj pojmenujte a zvolte si heslo, systém sám vygeneruje uživatelské jméno. Po založení je možné se k databázi připojit např. přes Microsoft SQL Server Management Studio, zde navrhnout tabulky a vztahy mezi nimi.

Po vytvoření požadovaných tabulek je nutné přes administraci Sofa načíst aktuální databázové schéma a publikovat ho: u zvoleného datového zdroje si zobrazte tabulky a klepněte na tlačítko Aktualizovat datové schéma.

V případě změn ve struktuře tabulek je nutné vždy přes administraci Sofa načíst aktuální verzi.

K zápisu a čtení z databáze se používají dotazy v jazyce GraphQL. V rozhraní pro návrh procesu tedy nejsou tyto datové zdroje přímo zobrazené, rozhraní jen dovoluje vložit kód dotazu, který se při běhu procesu provede.

Bližší informace k tomuto tématu najdete v dokumentaci Správa reportů, v kapitole GraphQL dotazy pro vytváření reportů.

Konektory

Konektory umožňují rozšířit GraphQL rozhraní směrem ven. Jedná se o .NET kód, který umožňuje zpracovávat požadavky od externích systémů, případně vystavovat nasbíraná data pro využití externím systémem. Konektory připravuje Software602 vždy na míru pro konkrétní systém, proto se neváhejte obrátit se svými požadavky na technickou podporu.