pyrus-form-scripts

Skill: Pyrus Client Form Script Developer

This skill provides step-by-step guidance, code structures, API reference, safety constraints, and checklists for building interactive Client Form Scripts in Pyrus.

When to Use This Skill

Use this skill whenever you need to:

1. Write or edit JavaScript/TypeScript scripts executed in Pyrus form UI (in browser or mobile app).
2. Automate form field calculations (setValue, setValues).
3. Add real-time field validation (validate, validateAsync).
4. Implement dynamic catalog filtering (setFilter, setFilterAsync).
5. Control field visibility (setVisibility) or assignees (setAssignee).
6. Calculate working days (getDaysCount) or aggregate table columns (cost.sum).

---

1. Key Rules for Client Form Scripts

• Prerequisite Gate: NEVER start writing scripts until ТЗ, Catalogs, JSON Form Upload, and Form Verification via pyrus:dump are 100% completed.
• Execution Context: Runs in the user's browser/mobile app when filling out a form in real-time.
• Top-level Chains: Subscriptions form.onChange(...) MUST be declared at the top level of the script.
• Field Codes: Field codes must be unique in the form and match standardized codes across forms (client_name, inn, order_date, etc.).
• No Direct HTTP: fetch(), XMLHttpRequest, and external network calls are FORBIDDEN. Use form.getCatalog(), form.fetchRoles(), form.fetchRegister().
• 5-Second Timeout: Operations must finish within 5 seconds.
• Always set executeOnLoad = true: Pass true as 2nd parameter to form.onChange(fields, true) so calculations run when opening existing tasks.
• Code Articles in KB: Always run npm run mirror:scripts after writing/updating script code to generate .ts.md articles for Pyrus KB sync.

---

2. API Quick Reference

Methods on form.onChange(fields, executeOnLoad):

• .setValue('TargetCode', state => newValue)
• .setValues(['Code1', 'Code2'], state => [val1, val2])
• .setValueAsync('TargetCode', async state => await newValue)
• .setAssignee(state => personId)
• .validate('FieldCode', state => ({ errorMessage: "Error", canSave: false }))
• .setFilter('CatalogField', state => ({ values: [1, 2, 3] }))
• .setVisibility(['FieldCode'], state => boolean)