Tema 4 · ERP Automatizacijos

ERP automatizacijos: sukūrimas, tipai, dialogas, žurnalas ir rezultatas

Po Temoje 3 išmokote, kaip ištraukti ir transformuoti duomenis (RQL, JSON, failai). Temoje 4 sutariame, kaip tas pats darbas atrodo ERP sąsajoje: kur kuriate automatizavimą, kokį tipą pasirenkate, kaip vartotojas įveda pradinius duomenis ir kaip grąžinate rezultatą. Techninį kodą (scriptContent, forma, initial, output) detaliau — Tema 6.

Testavimo aplinka. Tai jūsų bandomoji organizacija. Parašytų automatizacijų testavimui naudokite vartotoją, kurio teisės atitinka galutinį vykdytoją.

1. Automatizacijų sukūrimas

Naują automatizavimą paprastai rasite ERP-> Nustatymai -> Bendrieji -> Automatizacijos. Tipinė eiga: Naujas → užpildote metaduomenis → pasirenkate tipą ir vietas → įrašote scenarijų → išsaugote.

Pavadinimas ir kodas

• Pavadinimas — žmogui suprantamas (pvz. „Klientų tipų ataskaita“, „Importas iš Excel“). Rodymas sąraše ir pranešimuose.
• Kodas — trumpas techninis identifikatorius (pvz. CLIENT-TYPE-REPORT, C-001). Patogus paieškai ir palaikymui (aptarnavimui).
• Aprašymas (nebūtina, bet rekomenduojama) — vienu sakiniu paaiškina, ką daro automatizavimas ir kam skirtas.

Vietos priskyrimas (placeId)

Vietos priskyrimas nurodo, kur ERP sąsajoje vartotojas matys rankinio paleidimo veiksmą (mygtuką, meniu eilutę, „Papildomi veiksmai“).

Vienas automatizavimas gali turėti kelias vietas arba būti susietas su viena pagrindine vieta — priklauso nuo produkto konfigūracijos. Prieš publikuojant patikrinkite, ar veiksmas matomas ten, kur tikitės.

Programėlė ir sprendimas

Programėlė ir Sprendimas — tai automatizavimų grupavimas organizacijoje. Pagal nutylėjimą dažnai renkama parinktis „Organizacijai pritaikytos automatizacijos“ ir sukuriamas (ar pasirenkamas) savo sprendimo pavadinimas (pvz. „Integracijos“, „Ataskaitos“, „Mokymai“).

• Padeda tvarkyti dešimtis automatizavimų pagal funkciją ar komandą.
• Sutampa su diegimo / licencijų moduliais (kas mato kuriuos sprendimus).
• Palengvina paiešką ir diegimą naujoms komandoms.

2. Automatizacijų tipai

Automatizavimo tipas nulemia, kaip jis paleidžiamas, ką gauna į initial ir kaip elgiasi vartotojo sąsajoje. Konkretūs triggerTypeId reikšmės priklauso nuo versijos — žemiau — logika, kurią sutapatinsite su savo TEST aplinka ir eksportuotais JSON failais (triggerTypeId: 0 dažnai reiškia rankinį / kontekstinį).

Išsamesnė trigerių logika — Tema 8 · Konceptas ir trigeriai. Sinchroninio / asinchroninio skirtumai — Tema 9.

3. Pradiniai duomenys ir atsakymas vartotojui

Kiekvienas paleidimas perduoda scenarijui objektą initial. Turinys priklauso nuo tipo:

Ataskaitoje rezultatą grąžinate per output = { data: ... } (žr. Tema 3). Automatizavimo scenarijuje rezultatą ir vartotojo žinutę formuojate per output su message ir executionStatus (žr. §6).

4. Kaip pasidaryti dialogą pradinių duomenų įvedimui (paramsFormSchema)

Kai paramsFormEnabled: true, ERP rodo formą pagal paramsFormSchema — JSON masyvas su blokais. Kiekvienas blokas turi blockType ir meta (lauko vardas, antraštė, dydis, privalomumas).

SELECT iš fiksuotų reikšmių

{
  "blockType": "SELECT",
  "meta": {
    "fieldName": "dateType",
    "submitFieldName": ":id",
    "title": "Datos tipas",
    "size": 3,
    "defaultValue": 0,
    "meta": {
      "detectPrimitive": true,
      "getItems": [
        { "id": 0, "name": "Operacijos data" },
        { "id": 1, "name": "Mokėjimo data" }
      ]
    }
  }
}

SELECT iš duomenų bazės (RQL)

[
  {
    "blockType": "SELECT",
    "meta": {
      "fieldName": "client",
      "title": "Klientas",
      "size": 12,
      "meta": {
        "getItems": "rql:@MDPAGE SELECT * FROM clients"
      }
    }
  }
]

Datų intervalas (nuo / iki)

{
  "blockType": "FIELD",
  "meta": {
    "fieldName": "rangeFrom",
    "title": "Data nuo",
    "fieldType": "date",
    "size": 3,
    "required": true,
    "meta": { "defaultIsCurrentDate": true }
  }
},
{
  "blockType": "FIELD",
  "meta": {
    "fieldName": "rangeTo",
    "title": "Data iki",
    "fieldType": "date",
    "size": 3,
    "required": true,
    "meta": { "defaultIsCurrentDate": true }
  }
}

Scenarijuje reikšmės skaitomos kaip initial.rangeFrom, initial.rangeTo, initial.client ir t. t. Pilnesni pavyzdžiai — scripts/readme .

5. Vykdymo žurnalas ir tarpinių duomenų išvedimas

Automatizavimo istorija / veiksmų žurnalas / vykdymo detalė — ten matote, kas vyko vykdymo metu. Kode naudokite log.info, log.warn, log.error (geriau await log.info(...), kad įrašai spėtų užsirašyti prieš sesijos pabaigą).

• Diagnostika — kiek įrašų apdorota, kokie ID, kur sustojo procesas.
• Klaidos — log.error su kontekstu (eilutės numeris, dokumento ID).
• Tarpiniai duomenys — dideli JSON gabalais tik auditui; vartotojui dažnai pakanka output.message.

await log.info("Pradedama. Pažymėtų klientų: " + (initial.ids?.length ?? 0));
const page = await rql(`SELECT id, name FROM clients WHERE ...`);
await log.info("Rasta klientų: " + (page?.content?.length ?? 0));
await log.error(JSON.stringify({ step: "processRow", rowNo, error: error?.message }));

6. Rezultatų išvedimas (output)

Scenarijaus pabaigoje formuojate objektą output. Platforma pagal jį parodo vartotojui pranešimą ir (priklausomai nuo konfigūracijos) struktūrizuotus duomenis.

executionStatus

• SUCCESS — viskas atlikta pagal planą (numatytasis).
• WARNING — dalinai atlikta arba su įspėjimais (pvz. nieko nerasta pagal filtrą).
• FAILED — kritinė klaida.

message ir HTML

message — tekstas, kurį mato vartotojas. Galite naudoti paprastą tekstą arba HTML (nuorodos, paryškinimai):

output = {
  executionStatus: "SUCCESS",
  message:
    "Failas sukurtas: " +
    `<a href="${uploadedFile.publicLink}" target="_blank" style="color: green;">Peržiūrėti</a>`,
  data: {
    file: {
      id: uploadedFile.id,
      fileName: "purchase-invoices.csv",
      publicLink: uploadedFile.publicLink,
      internalLink: uploadedFile.internalLink,
    },
  },
};

Lauką data naudokite papildomiems duomenims. Pilna API — Tema 7 · output.

// SUCCESS
output = {
  executionStatus: "SUCCESS",
  message: "Apdorota klientų: <strong>12</strong>",
  data: { count: 12 },
};

// WARNING — pvz. nieko nerasta pagal filtrą
output = {
  executionStatus: "WARNING",
  message:
    "Pagal pasirinktą tipą klientų nerasta. Patikrinkite filtrą arba sukurkite duomenis TEST aplinkoje.",
  data: { count: 0 },
};

7. Praktinė užduotis: rankinis automatizavimas iš klientų sąrašo

Užduotis: sukurkite Manual tipo automatizavimą, kuris kviečiamas iš Klientų sąrašo, su dialogu ir rezultatu ekrane bei žurnale.

7.1 Dialogas: kliento tipas

Prieš vykdymą vartotojas pasirenka Kliento tipą: Juridinis arba Fizinis.

{
  "blockType": "SELECT",
  "meta": {
    "fieldName": "clientKind",
    "title": "Kliento tipas",
    "size": 6,
    "required": true,
    "meta": {
      "detectPrimitive": true,
      "getItems": [
        { "id": "JURIDINIS", "name": "Juridinis asmuo" },
        { "id": "FIZINIS", "name": "Fizinis asmuo" }
      ]
    }
  }
}

Scenarijuje reikšmė bus initial.clientKind. Svarbu: tikrą lauką klientų lentelėje patikrinkite Lentelių tipuose / GraphQL (pvz. isCompany, clientType) — pavyzdžiuose naudojame loginį pavadinimą clientKind.

7.2 Scenarijaus logika (santrauka)

const selectedKind = initial.clientKind;

if (!selectedKind) {
  throw new UserError("Pasirinkite kliento tipą.");
}

const companyId = initial.companyId;
const page = await rql(`
  SELECT id, code, name, isCompany
  FROM clients
  WITH companyId = ${companyId} size = 500
`);

let rows = page?.content ?? [];

if (selectedKind === "JURIDINIS") {
  rows = rows.filter((c) => c.isCompany === true);
} else if (selectedKind === "FIZINIS") {
  rows = rows.filter((c) => c.isCompany === false);
}

await log.info(`Rasta klientų (${selectedKind}): ${rows.length}`);

if (rows.length === 0) {
  output = {
    executionStatus: "WARNING",
    message: `Pagal tipą „${selectedKind}“ klientų nerasta.`,
    data: { clientKind: selectedKind, count: 0 },
  };
} else {
  output = {
    executionStatus: "SUCCESS",
    message: `Rasta klientų (${selectedKind}): <strong>${rows.length}</strong>`,
    data: { clientKind: selectedKind, count: rows.length, preview: rows.slice(0, 20) },
  };
}

7.3 Konfigūracijos santrauka

Repo pavyzdžiai su clients-list ir forma — c-001 (failo įkėlimas) ir Tema 8.

Teorijos santrauka

• Automatizavimas = pavadinimas + kodas + vieta + sprendimas + trigerio tipas + scenarijus.
• Rankinis tipas duoda dialogą ir aiškų output; įvykis — savo įvykio struktūrą; CRON — be vartotojo dialogo.
• initial ir paramsFormSchema apibrėžia įėjimą; log.* — auditą; output.message ir executionStatus — vartotojo atsakymą.
• Kitas žingsnis — Tema 5 · redagavimas ir kokybė.

Savarankiškas darbas

1. Sukurkite automatizavimą su placeId: clients-list ir dialogu „Kliento tipas“ (§7).
2. Paleiskite su tipu Juridinis ir Fizinis; užfiksuokite ekrano nuotrauką su executionStatus ir žurnalo eilutėmis.
3. Jei TEST neturi pakankamai klientų — sukurkite testinius įrašus arba naudokite filtrą, kuris garantuoja bent kelis rezultatus.
4. Palyginkite su Tema 6: kur formoje, kur initial, kur output.