Tema 2 · ERP Objektas (JSON)

Duomenų modelis JSON formatu ir kur jį matote sistemoje

Po įvado ir mokymų formato sutariame bendrą kalbą apie ERP objektą kaip JSON: kokios reikšmės būna laukuose, kaip užrašomos datos ir laikas, kur naršyklėje rasite objektų sąrašą, RQL įrankį ir GraphQL schemą (Apollo Sandbox) bandymams ir paieškai. Toliau Temoje 3 sutariame duomenų išvedimą iš ERP (ataskaitos, RQL scenarijuje, failai) ir ryšį su GraphQL bei rql užklausomis.

1. Kas yra ERP Objektas (JSON)

ERP objektas čia suprantame kaip vieną verslo įrašą ar struktūrą (pvz. dokumentą, kontrahentą, eilutę), kurį sistema gali pateikti ar priimti kaip hierarchinį JSON objektą: raktai (laukų vardai), reikšmės, įdėtiniai objektai ir masyvai.

Trumpai apie JSON struktūrą ir elementų tipus

JSON dokumentą sudaro objektai ({ … }), masyvai ([ … ]), tekstai kabutėse, skaičiai, logikos reikšmės ir null. Rivile ERP kontekste dažnai sutiksite šiuos laukų tipus (pavadinimai gali skirtis nuo diegimo, bet formatų esmė lieka):

Konkretūs laukų vardai ir ar data ateina kaip tekstas ar skaičius — visada derinkite su GraphQL tipais ir žinynu savo aplinkoje; čia fiksuojame bendrą skaitymo kultūrą, kad vėliau RQL ir API skyriai būtų lengvesni.

{
  "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
  "documentNo": "PI-000123",
  "docDate": "2026-05-12",
  "createdAt": "2026-05-12T08:56:45.129552Z",
  "active": true,
  "statusId": 0,
  "exchangeRate": 1.0,
  "notes": null,
  "supplier": {
    "id": "40ab5f61-1785-4bd0-a587-482738398a83",
    "code": "TIEK-001",
    "name": "UAB Pavyzdinis tiekėjas",
    "isSupplier": true
  },
  "totals": {
    "amount": 2289.26,
    "taxAmount": 480.74,
    "amountWithTax": 2770.0
  },
  "lines": [
    {
      "lineNo": 1,
      "itemId": "12a5f3b7-9e55-441f-a50b-f1259272b153",
      "itemCode": "PREK-001",
      "itemName": "Kompiuteris",
      "qtyBase": 1,
      "price": 2400.0,
      "amount": 1983.47
    },
    {
      "lineNo": 2,
      "itemId": "7dd893a1-8fae-4327-b4f8-c04f51cf457a",
      "itemCode": "PREK-002",
      "itemName": "Monitorius",
      "qtyBase": 1,
      "price": 350.0,
      "amount": 289.26
    }
  ],
  "ext": {
    "dimVP": "mokymai"
  }
}

2. Kaip susirasti sąrašą ERP objektų

Kurėjų meniu (kelias ERP → Kurėjų meniu) kai kuriuose diegimuose ar naudotojo profiliuose gali būti paslėptas. Tuomet Lentelių tipų ir RQL įrankio per įprastą meniu nepamatysite.

Įjungti arba išjungti kūrėjų įrankius galima naršyklėje atvėrus Developer Tools (pvz. F12) ir skiltyje Console įvykdžius komandą (kol aktyvus Rivile ERP skirtukas):

erp.devTools(true);   // įjungti kūrėjų įrankius (rodyti Kurėjų meniu ir pan.)
erp.devTools(false);  // išjungti

Komentaras anglų kalba dažnai paliekamas kaip // Enable/Disable dev tools — esmė ta pati: boolean parametras valdo būseną.

Naršyklėje Rivile ERP vykdykite kelią: Kurėjų meniu → Lentelių tipai. Ten matote objektų / lentelių sąrašą, kuris padeda susieti domenų pavadinimus su tuo, ką vėliau naudosite RQL ar schemoje.

Kelias Kūrėjų meniu → Lentelių tipai (tas pats poslinkis rodo ir RQL įrankį — žr. skyrių 3).

Lentelių tipų sąrašas ir paieška

Atvėrus Lentelių tipus, viršuje matote naršymo kelią Kūrėjų meniu > Lentelių tipai. Paieškos laukas leidžia filtruoti objektus pagal vardą — pavyzdyje įrašyta Client, kad būtų matomi visi susiję tipai (Client, ClientGroup, ClientType ir kt.).

Stulpelyje NAME rodomas techninis lentelės vardas — jį naudojate RQL po raktažodžio FROM, pvz. SELECT … FROM Client. Kiti stulpeliai (COUNTABLE, EXTENDABLE, TRANSLATABLE, IS MASTERDATA, IS ENUM, ACTIVE, ALLOW WORKFLOW) trumpai apibūdina objekto savybes (ar skaičiuojami įrašai, ar galima plėtra, ar tai žinynas / enum, ar galimi darbo procesai ir pan.).

Filtruotas sąrašas: stulpelis NAME atitinka RQL FROM šaltinio pavadinimą.

Atverta lentelė: metaduomenys ir laukai

Paspaudus ant eilutės (pavyzdyje Client), atveriamas išsamus vaizdas su skiltimis Lentelė ir Laukai. Skiltyje Lentelė matote Name ir Id — pastarasis yra UUID (objekto tipo identifikatorius sistemoje; JSON kontekste UUID dažnai perduodamas kaip string — žr. skyriaus 1 lentelę). Pažymėtos vėliavėlės (Countable, Extendable, Master data, Active, Allow workflow ir kt.) atitinka sąrašo stulpelius.

Skiltyje Laukai pateikiami visi lauko vardai ir tipai (String, Boolean, Date, Many2One, Many2Many ir kt.) — tai tiesioginė atrama rašant SELECT laukų sąrašą ir WHERE sąlygas bei skaitant JSON rezultatą.

Pavyzdys Client: lentelės Id ir laukų sąrašas su tipais.

Vieno lauko ypatybės

Pasirinkus konkretų lauką (dialogas Edit field), matote jo tipą (Type), ar laukas sisteminis, ar verčiamas (Translatable), apribojimus, numatytąją reikšmę ir etiketes kalbomis (pvz. lietuviškas „Pavadinimas“). Tai padeda susieti JSON lauką su formos elgsena ir lokalizacija.

Lauko name ypatybės: tipas String, vertimas į lietuvių kalbą.

Praktinė užduotis: papildomas laukas ant „Client“

Prieš pereinant prie skyriaus 3. RQL įrankis, salėje atlikite šią užduotį TEST aplinkoje (ir tik su tomis teisėmis, kurias leidžia mokymų organizatorius). Tą pačią sesiją papildykite pradiniais duomenimis tiekėjui ir prekei, jei dar nepadarėte — RQL pavyzdžiai remiasi tais įrašais. Lauko techninis vardas turi būti unikalus: naudokite prefiksą dim ir savo inicialus (pvz. Vardas Pavardė → dimVP).

1. Atverkite ERP → Kūrėjų meniu (jei meniu paslėptas — žr. aukščiau esantį erp.devTools(true);).
2. Eikite į Lentelių tipus, paieškoje suraskite lentelę Client ir ją atverkite (eilutės paspaudimas).

3. Pridėkite naują lauką: tipas String, techninis vardas lauke Name — dim + jūsų inicialai (vienas žodis be tarpų, pradėti mažosiomis kaip įprasta papildomam laukui):

   1. Spauskite mygtuką Pridėti (laukų sąraše).
   2. Tipas: pasirinkite String.
   3. Lauke Name įrašykite dim ir savo inicialus (pvz. dimVP).
   4. Spauskite Išsaugoti.
4. Tada eikite ERP → Pardavimai → Pirkėjai sąraše: atverkite bet kurio kliento kortelę ir skiltyje / skyriuje Papildomi laukai patikrinkite, ar matosi jūsų sukurtas papildomas laukas.

Jei lauko vardas sutampa su kito mokinio — pakoreguokite inicialus arba trumpą unikalų sufiksą.

Pradiniai duomenys prie RQL praktikos

Prieš bandant RQL įrankį (žemiau), salėje TEST aplinkoje paruoškite bent minimalius pirkimų katalogo įrašus — taip užklausų rezultatus galėsite sieti su savo sukurtais duomenimis, o ne su atsitiktiniais sąrašo įrašais. Tiekėjo kortelė sistemoje priklauso bendram klientų objektui su pažymėtu požymiu tiekėjas — RQL užklausose ieškosite per clients ir isSupplier, o ne per atskirą suppliers lentelę.

1. Atverkite ERP → Pirkimai → Tiekėjai sąrašą ir sukurkite bent vieną tiekėją (kiekvienas mokinys — savo įrašą). Kortelėje užpildykite bent kodą ir pavadinimą taip, kad kodas būtų unikalus jūsų grupei (pvz. inicialai + trumpas sufiksas: jdMOK1).
2. Atverkite ERP → Pirkimai → Prekės, paslaugos sąrašą ir sukurkite bent vieną prekę (ar paslaugą, jei taip organizuotas sąrašas). Taip pat nurodykite unikalų kodą ir aiškų pavadinimą.
3. Užsirašykite suvestus kodus ir, jei patogu, id iš sąrašo ar kortelės — juos įrašysite į RQL pavyzdžius vietoje rezervuotų reikšmių.

3. Kaip veikia RQL užklausos — RQL įrankis

Norėdami išbandyti užklausą be pilno scenarijaus, naudokite: Kurėjų meniu → RQL įrankis. Tai atskiras įrankis sąrašų ir filtrų eksperimentams; jo rezultatas padeda suprasti, kokius laukus grąžinsite į scenarijų per rql (žr. Temą 3).

Kurėjų meniu → RQL įrankis: pavyzdinė užklausa į clients su addresses, contacts, ext; žemiau — Data skilties JSON (vienas atitinkantis tiekėjo įrašas).

Žemiau — SELECT šablonai, skirti rasti būtent jūsų ką tik sukurtą tiekėją ir prekę (pagal organizacijos kontekstą, size ir filtrus). Tiekėjas šiame modelyje nėra atskiros RQL lentelės: tai tie patys clients, atskirti požymiu isSupplier = true (pardavimų klientas — isCustomer, abu požymiai gali būti true toje pačioje kortelėje). Bendresnę sintaksę ir ryšį su scenarijumi žr. Temą 3 bei praktiką (dokumentai, eksportas / prekės, integracijos).

RQL įrankyje vietoje <jūsų_companyId> įrašykite organizacijos ID iš savo konteksto (TEST), jei jūsų sesijoje reikia aiškaus WITH companyId = … (kai kur kontekstas perduodamas automatiškai). Tiekėjui visada naudokite lentelę clients ir filtrą isSupplier = true. Prekėms — products (patikrinkite Lentelių tipų NAME, jei diegime kitas vardas).

SELECT id, code, name, isSupplier, isCustomer FROM clients
WITH companyId = <j> size = 50
WHERE isSupplier = true

SELECT id, code, name, isSupplier FROM clients
WITH companyId = <j> size = 10
WHERE isSupplier = true AND code = 'jdMOK1'

SELECT id, code, name, isSupplier FROM clients
WITH companyId = <j> size = 5
WHERE isSupplier = true AND id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'

SELECT id, code, name, isSupplier, addresses, contacts, ext FROM clients
WITH companyId = <j> size = 5
WHERE isSupplier = true
  AND name = 'UAB Mano pavyzdys'
  AND ext.dimVP = 'žymė_kurią_suvedėte_kortelėje'

SELECT id, code, name FROM products
WITH companyId = <j> size = 50

SELECT id, code, name FROM products
WITH companyId = <j> size = 10
WHERE code = 'PREK-JD-1'

SELECT id, code, name FROM products
WITH companyId = <j> size = 5
WHERE id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'

SELECT id, code, name FROM products
WITH companyId = <j> size = 10
WHERE name = 'Mokymų prekė 1'

4. Apollo schemos pristatymas

Šiame įrankyje galite susirasti norimą ERP objektą (GraphQL objekto tipą) ir peržiūrėti jo atributus: laukus, įterptus tipus, argumentus užklausoms ir mutacijoms. Tai papildo Lentelių tipus ir RQL įrankį — ypač kai reikia greitai palyginti Query / Mutation paviršių su vidiniu duomenų modeliu; plačiau apie klausimus ir mutacijas žr. Temą 3.

Schemą TEST aplinkoje pasiekiate adresu: https://erp.test.rivile.cloud/graphql-gen3. Atvėrus Apollo Sandbox, kairėje pasirinkite Schema reference, tada skyrių Objects — čia rodomi objektų tipai; viršuje esančioje paieškoje įveskite tipą (pvz. Client, Product), kad filtruotumėte sąrašą ir atvertumėte lauko aprašus.

Schema reference → Objects: paieška pagal tipą (pavyzdyje Client) ir sutampančių laukų santrauka.

Pastaba. Rivile ERP naršyklės lange paspauskite F12, tada Developer Tools skiltyje Network stebėkite POST užklausas į https://erp.test.rivile.cloud/graphql-gen3 — tai alternatyvus būdas pamatyti, kokius ERP objektus ir GraphQL operacijas forma ar sąrašas siunčia serveriui, ir susieti atsakymą su konkrečia ERP forma ar veiksmu, kurį ką tik atlikote.

Praktinis darbas

Savarankiškai TEST aplinkoje atlikite šiuos žingsnius ir užfiksuokite rezultatą (užklausos tekstas + ar JSON pavyko gauti).

1. Išsiaiškinkite pirkimo sąskaitos ERP objekto (lentelės) techninį vardą, kurį naudosite RQL po raktažodžio FROM: atverkite Lentelių tipus ir paieškoje suraskite sąskaitai atitinkantį tipą, tada stulpelyje NAME persirašykite vardą; papildomai galite patikrinti Apollo schemą (Schema reference → Objects, paieška pagal pvz. PurchaseInvoice) ir palyginti su GraphQL tipų vardu.
2. RQL įrankyje sudarykite vieną užklausą, kuri ištrauktų pirkimo sąskaitas ir jų eilutes (eilučių kolekciją ar laukus, priklausančius nuo jūsų modelio). Dokumento lygiui užtenka kelių laukų (pvz. identifikatorius, dokumento numeris); eilutėms naudokite įterptą ryšį, kurį matote toje pačioje lentelėje skiltyje Laukai (dažnai panašu į lines ar analogą — neatspėkite iš galvos, patikrinkite metaduomenyse).
3. Jei užklausa grąžina klaidą dėl nežinomo lauko — pakoreguokite SELECT sąrašą arba įterptų laukų vardus pagal Lentelių tipų laukų sąrašą; ribokite size, kad atsakymas būtų skaitomas.

SELECT id, documentNo, lines
FROM purchaseInvoices
WITH companyId = <j> size = 5