Tema 7 · API ir GraphQL

Scenarijaus kontraktas ir automatizavimo (JavaScript) API

Po JSON eksporto ir repo sutarties čia vienoje vietoje sutvirtiname vykdymo sutartį: initial (įėjimas) → validacija ir darbas (rql, mutate, DataExport, failai) → *`log.** ir **output** (išėjimas). Domenų vardus derinkite su GraphQL modeliu — trumpa santrauka [čia](/academy/automation_training/praktika/gql-schema-santrauka); pirmiejirql/mutate` šablonai — Tema 3. Pilnas API aprašas: Automatizavimo scenarijų API (HTML).

1. Pradiniai parametrai — initial

Paleidus automatizavimą, runtime injektuoja initial:

  • Sąrašo kontekstas: initial.ids (masyvas), initial.id, initial.filterString, initial.sortString.
  • Formos laukai (kai paramsFormEnabled: true): reikšmės pagal paramsFormSchema lauko fieldName, pvz. initial.departmentIn, initial.fileName / initial.fileName.publicLink.
  • Papildomas kontekstas: pvz. initial.acceptLanguage vertimams.
Pavyzdys: `paramsFormSchema` (JSON fragmentas) 
[
  { "blockType": "FILEUPLOAD", "meta": { "fieldName": "fileName", "accept": ".xlsx,.csv" } },
  { "blockType": "SELECT", "meta": { "fieldName": "reasonCode", "required": true, "meta": { "getItems": "rql:..." } } }
]

Scenarijuje: const url = initial.fileName?.publicLink ?? initial.fileName;

2. Exception handling

Mechanizmas Kada Pastaba
throw new UserError("…") Verslo taisyklė neįvykdyta (niekas nepažymėta, trūksta privalomo lauko) Suprantama vartotojo žinutė
try / catch aplink mutate, rql, fetchData Tinklo / DB / validacijos klaidos Į log.error su kontekstu
continue / failed.push Partijos apdorojimas Viena eilutė krenta — tęsiame kitas
Pagalbinė logException(tag, err) Centralizuotas serializavimas message, stack, name
Scenarijaus fragmentas: validacija + try/catch 

if (!initial?.ids || initial.ids.length

3. Veiksmų žurnalas — log.*

Standartinis žurnalavimas: logMessage, log.info, log.error, …; užbaigiant dažnai derina su output.executionStatus.

  • INFO — sėkmingi žingsniai, santraukos (kiek įrašų, kokie ID).
  • TRACE / DEBUG — payload, diagnostika (išjungti gamyboje, jei per didelė apimtis).
  • WARN — neįprasta, bet tęsiama.
  • ERROR — klaida; visada su kontekstu (entitetas, operacija, filtras).
  • Rekomendacija: await log.info(...), kad įrašas spėtų užsirašyti iki sesijos pabaigos.

4. Rezultato išvedimas — output

Pabaigoje priskiriamas output objektas — matomas UI ir istorijoje. Dažni laukai:

  • message — žmogui skirtas tekstas.
  • executionStatus — SUCCESS | WARNING | CANCELED.
  • documentsCount — kiek dokumentų apdorota (alternatyva: setDocumentsCount vykdymo metu).
  • Papildomi laukai pagal poreikį: created, failed, failedCount (masinio apdorojimo ataskaita).
Techninis pavyzdys: žurnalas ir `output` 
await log.info("Pradėta");
output = {
  executionStatus: "WARNING", // optional, default SUCCESS
  documentsCount: 1
};
Pavyzdys: `output` su daliniu nesėkmių atveju 
output = {
  message: failed.length
    ? `Atlikta su klaidomis. OK: ${okCount}, klaidų: ${failed.length}`
    : `Sėkmingai apdorota: ${okCount}`,
  executionStatus: failed.length ? "WARNING" : "SUCCESS",
  documentsCount: okCount,
  failed
};

5. Ryšys su GraphQL domenu

Kai rašote mutate("…") arba RQL į purchaseInvoices ir pan., galvojate apie tuos pačius entitetus, kaip GraphQL schemoje (purchaseInvoice ir pan.). Tikslūs vardai pas jus — iš tikros SDL ar introspection.

6. Kito automatizavimo kvietimas

Techninis pavyzdys: `callErpAutomation` 
const response = await callErpAutomation(
  "childAutomation",
  { param1: "param1", param2: true, param3: 3.14 }
);
// response.status: SUCCESS | FAILED | CANCELED
// response.data: Object | String

Įdėtiniai kvietimai susiję su ciklo apsauga — žr. Tema 9 · vykdymas ir ribos.

7. DataExport scenarijuje

UI srautas su užduotimi ir failu aprašytas temoje apie kelius ir asinchroninį eksportą; scenarijuje dažnai naudojama getDataExportSchemas, fetchExportData.

Techninis pavyzdys: schemos ir eksporto duomenys 
await getDataExportSchemas();

await fetchExportData("reportTypeId", {
  filters: { /* … */ },
  dataSelection: ["laukas1", "laukas2"], // optional
  groupBy: "CLIENT" // optional
});
// { status: "SUCCESS" | "ERROR", data: { "{entityTypeName}": [ ... ] } }

8. Failai ir HTTP

Galima apibrėžti failo įkėlimą parametrų schemoje (FILEUPLOAD), skaityti per fetchData su viešu URL, generuoti viešą nuorodą per RQL getPublicLink — detalės pilname API apraše.

Teorijos santrauka

  • initial perduoda sąrašo, formos ir konteksto duomenis; validacija prasideda nuo jų.
  • UserError — verslui; techninės klaidos — try/catch ir log.error su kontekstu.
  • log.* kuria vykdymo istoriją; output užbaigia scenarijų ir matomas UI.
  • DataExport, įdėtiniai automatizavimai ir failai — pagal tą patį API dokumentą.

Praktika salėje

Pasirinkite vieną praktikos pavyzdį su sąrašo kontekstu ir kartu peržvelkite, kur jame skaitomas initial ir kur formuojamas output.

Savarankiškas darbas

  1. TEST aplinkoje parašykite juodraštį: validacija initial.ids, vienas log.info, output su message ir executionStatus (be tikrų slaptų duomenų).
  2. Palyginkite savo RQL lentelės vardą su GQL santrauka — užfiksuokite vieną neatitikimą, kurį tektų tikrinti schemoje.