Mokymų HTML (kontraktas, stilius): mokymosi eiga (nuo nulio); Tema 6 — naujokams: sutraukta sutartis su pavyzdžiais; Tema 7 — scenarijaus kontraktas ir API; Tema 5 — redagavimas, TypeScript ir kokybė.
Čia saugomi automatizavimo apibrėžimų eksportai (JSON formatas). Vykdomas kodas saugomas lauke values.scriptContent (JavaScript). Tai palaiko versijų kontrolę ir dalijimąsi ta pačia logika su technine dokumentacija. Įėjimo sluoksnis mokymuose — tas pats turinys sutrauktas su lentelėmis ir kodo gabalėliais Temoje 6 (skyrius „Naujokams…“); šis failas lieka pilna indeksuota nuoroda.
Failų vardų šablonas šiame kataloge: vidinis kodas ir trumpas pavadinimas, pvz. eksportas, susijęs su klientų duomenų atnaujinimu iš „Excel“.
initialPaleidus automatizavimą iš UI, scenarijus gauna initial — kontekstą, kurį sudaro:
Bendri laukai (priklausomai nuo vietos / trigerio), pvz.:
initial.ids — pažymėtų įrašų ID masyvas (sąrašo vaizdas),
initial.id — vienas įrašas,
initial.sortString, initial.filterString — sąrašo būsena,
initial.acceptLanguage — kalbos nuoroda (žr. vertimų pavyzdį ss-ocr-read-email faile).
Laukai iš parametrų formos — apibrėžiami JSON schemoje paramsFormSchema, kai paramsFormEnabled: true:
FILEUPLOAD — laukas fieldName (pvz. fileName). Po įkėlimo dažnai naudojama:
initial.fileName — nuoroda / identifikatorius,
arba initial.fileName.publicLink — vieša nuoroda į turinį (jm16750, c-001 variantai).
SELECT ir kt. — pvz. fieldName: "departmentIn", reikšmė ateina kaip initial.departmentIn (aa260126).
| Laukas JSON | Paskirtis |
|---|---|
paramsFormSchema |
Formos blokai: blockType, meta.fieldName, accept, required, RQL getItems ir pan. |
exampleData |
Pavyzdinis initial testavimui (JSON eilutė), pvz. { "ids": [...], "departmentIn": "..." }. |
placeId |
Kur UI rodomas veiksmas (clients-list, purchases-invoice-list, …). |
triggerTypeId |
Trigerio tipas; 0 — dažnai rankinis / kontekstinis; suplanuotiems — žr. cronExpression (ss-ocr-read-email). |
Pavyzdys iš c-001: vienas blokas FILEUPLOAD, laukas fileName, toliau fetchData skaito Excel turinį.
Pavyzdys iš aa260126: forma su privalomu departmentIn (SELECT iš padalinių) + sąrašo kontekstas ids.
Projekto skriptuose matomi keli sluoksniai:
UserErrorKai sąlyga neįvykdyta (pvz. nieko nepažymėta), metama throw new UserError("žinutė") — tai suprantama kaip kontroliuojama klaida vartotojui (aa260126).
try / catchAplink mutate, rql, fetchData — tipinis šablonas: try { … } catch (error) { log.error(…); … }.
Cikle po dokumentą / eilutę: klaida vienam elementui gali ne nutraukti viso proceso:
failed.push(errInfo); continue; — kitas dokumentas (aa260126),
arba eilutės lygyje kaupti linesFailed ir vis tiek tęsti kitas eilutes.
logExceptionFaile c-001 naudojama logException(tag, exception), kuri serializuoja message, stack, name ir rašo per await log.error(...). Tai palengvina diagnostiką veiksmų žurnale.
c-001 faile vienoje vietoje catch (execption) neatitinka kintamojo exception — tokia klaida paslėptų tikrąją išimtį. Verta laikytis vieno pavadinimo (exception / error) visur.
ss-ocr-read-email: klaidos el. pašto skaityme — catch (error) su šakomis (pvz. AUTHENTICATIONFAILED → aiški log.error, kitu atveju log.debug + log.error).
outputScenarijaus pabaigoje priskiriama output (objektas). Tipiniai laukai iš jūsų pavyzdžių:
| Laukas | Pavyzdys | Pastaba |
|---|---|---|
message |
"Veiksmas atliktas" |
Trumpas tekstas UI / žurnalui. |
created |
masyvas sukurtų objektų santraukų | aa260126 — detali struktūra (movement + eilutės). |
failedCount / failed |
skaičius ar detalės | Dalinis nesėkmės atvejis. |
| (kiti) | output = { xlsxDataAsJson } |
jm16750 — diagnostikai (didžiulis output gali būti nepageidautinas gamyboje). |
Papildomai API gali naudoti executionStatus (SUCCESS / WARNING / CANCELED) ir documentsCount — žr. Automatizavimo scenarijų API.
Naudojami lygiai: log.trace, log.debug, log.info, log.warn, log.error (ir kartais logMessage — pagal API dokumentą).
| Situacija | Ką daryti | Pavyzdžiai iš šio katalogo |
|---|---|---|
| Sėkmingas žingsnis | log.info su santrauka |
Sukurtas dokumentas / eilutė (aa260126 po mutate). |
| Diagnostikai / payload | log.trace su JSON |
Įvesties objektai, payload prieš sunkias operacijas. |
| Įspėjimas, bet ne stabdymas | log.warn |
Nerasti failai pagal el. paštą (ss-ocr-read-email). |
| Klaida | log.error su kontekstu |
JSON.stringify su docRef, functionName, payload (aa260126). |
| Daug eilučių | Po eilutę arba santrauką | jm16750: log.info(createdProduct); c-001: eilutės lygio klaidos į žurnalą per logException. |
Kada būtina: klaidos (error) — be jų sunku atsekti, kuris dokumentas / kuri eilutė sukrito. Info po kiekvieno svarbaus mutate palengvina auditą „kas sukurta“. Trace palikti tik kai reikia gilumo (gali būti labai kalbūs žurnalai).
Pastaba: dalis kodo kviečia log.info(...) be await, dalis — su await. Vadovaukitės automatizavimo API sutartimi: jei log.* yra asinchroniniai, saugiau naudoti await log.info(...), kad užtikrintumėte įrašymą prieš baigiant sesiją.
| Failas | Pirminiai duomenys | Klaidos / output | Logging |
|---|---|---|---|
| c-001 | FILEUPLOAD → initial.fileName, Excel |
try/catch + logException eilutėms; output.message |
trace/info užkomentuoti; error per helperį |
| aa260126 | ids, departmentIn, sąrašo filtrai |
UserError; failed / created; output su santrauka |
info po kiekvieno create, trace payload, error su kontekstu |
| jm16750 | initial.fileName.publicLink |
catch eilutei; output su visu JSON (atsargiai) |
info po produkto sukūrimo, error klaidai |
| ss-ocr-read-email | CRON, parametrai DB, companyId |
UserError jei nėra parametro; try/catch skaitymui ir mutate |
info/warn/error pagal srautą; vertimai per getTranslations |
Jei pridedate naują JSON į šį katalogą, trumpai įrašykite į šį README vieną eilutę: kodas, trigeris, pagrindinis initial laukas.