> For the complete documentation index, see [llms.txt](https://docs.agilecase.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agilecase.com/developer-documentation/custom-form-scripting/scripting-helper-api-reference.md). # Scripting Helper API Reference Every global available to a JavaScript label field, with its arguments. The scripting helper is a script loaded on every page that puts a set of globals in front of your JavaScript label. It exists so a label can read fields, change the form and reach the rest of the case without knowing how any of it is rendered. It is a browser library, so none of it exists in a [calculated field](/developer-documentation/case-scripting/calculated-fields.md) or an [on save script](/developer-documentation/case-scripting/on-save-scripts.md). Those run on the server and use `Service` instead. {% hint style="info" %} The declarative side of the helper — `ExecuteAllRules` and the JSON rulesets it takes — has its own page. This one covers the functions you call directly. See the [Rule Reference](/developer-documentation/custom-form-scripting/rule-reference.md). {% endhint %} ## Fields ### CustomField(id) The workhorse. Wraps a custom field by numeric ID and gives you everything you can do to it. ```javascript var outcome = CustomField(6108).Value(); CustomField(6109).HideRow(); CustomField(6110).Disable(); ```

Method	What it does
`Value()`	The field's value as a string, with the stored quoting and brackets stripped off. Empty string when the field has no value.
`ValueAsText()`	Identical to `Value()`.
`ValueAsNumber()`	`Value()` passed through `Number()`. Decimals survive; an unparseable value gives `NaN`.
`Value2()`	The raw stored value, quoting and brackets intact — the encoded form, where `Value()` gives the readable one.
`Value3(newValue)`	Writes `newValue` through `setHiddenValueElement` and returns the visible value. Called with no argument it behaves exactly like `Value()`.
`Input()`	The jQuery object for `#CustomField_<id>` — the input, select, textarea, or the output span for a label.
`InputHidden()`	The jQuery object for the hidden element that carries the value actually submitted.
`HideRow()` / `ShowRow()`	Hides or shows the whole field row, label included. Older scripts do this by walking up the DOM with `.parent().parent().parent().hide()`; these do the same job and survive markup changes.
`Disable()` / `Enable()`	Sets or clears the `disabled` property on the input.

Note that these are functions, so `Value()` needs its brackets. The server-side equivalent, `Service.CustomField(id).ValueAsText`, is a property and takes none — worth remembering when moving a piece of logic between a label and a calculated field. `CustomField` can be called with or without `new`; every example here calls it plainly. #### Every field is two elements A custom field renders as a visible control and a hidden input holding the value that is submitted. The two hold different things: the visible box shows `Approved`, the hidden element stores `"Approved"` with its quotes, and a date shows `01/04/2026` while storing `"20260401"`. `Value()` reads whichever of the two is authoritative for that field type, and strips the stored quoting. Writing has to set both, correctly, which is what [`Value3()`](#writing-values) is for. #### What each field type reads as | Field type | `Value()` returns | Notes | | ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Text box, text area, numeric | `Board A` | The value as typed. | | Date picker | `01/04/2026` | As displayed. [`get_moment`](#dates) parses it. | | Dropdown | `Board A` | The selected option's value. | | Radio list | `Board A` | The selected option's value. | | Check box | `true` or `false` | As text rather than a boolean, so the test is `=== "true"`. | | Checkbox list | `Bar","Stage` | Stored as a JSON array, of which the outer bracket and quotes are stripped. For a multiple selection, parse `InputHidden().val()` instead. | | Anything empty | | An empty string, whatever the type. | {% hint style="info" %} Check boxes are spelled differently either side of the wire: the browser reads `true` / `false`, while the server — a calculated field, an on save script, or the [Case Data API](/developer-documentation/case-data-api.md) — reports `True` / `False`. Allow for both if the same field is read in both places. {% endhint %} #### Reading a field that is not on the tab When the ID does not match anything on the page, `Value()` looks for a global called `preloadCaseData` and, if it finds one, returns the matching field from it: ```javascript preloadCaseData = preLoadServerData('Custom.6227'); var integrationOn = CustomField(6227).Value(); ``` {% hint style="info" %} The global name is part of the arrangement: assign the preload to `preloadCaseData` **without `var`**, so that it sits in global scope where the helper looks for it. `var preloadCaseData = ...` keeps it inside your own script, and the fallback then has nothing to read. {% endhint %} With no preload in scope, `Value()` returns an empty string and notes `Scripting Error: CustomField does not exist on this tab` in the console. It does not throw, so the console is where to look if a field reads as empty unexpectedly. ### ThisJSLabel() Shorthand for `CustomField(ScriptID)` — the label running the script. ```javascript ThisJSLabel().HideRow(); ThisJSLabel().Input().html("Total: " + total); ``` {% hint style="info" %} `ScriptID` is a single global, set by each label as it begins running, so it names your label for as long as your script is running. In a callback that fires later — a change handler, an AJAX success — it names whichever label ran most recently. Capture it in a local variable if you need it after your script has finished. {% endhint %} ### CustomFieldTab(id) Shows or hides a custom field group's tab link. The argument is a **custom field group ID**, not a field ID. ```javascript CustomFieldTab(6512).Hide(); CustomFieldTab(6512).Show(); ``` The [`hide_tabs`](/developer-documentation/custom-form-scripting/rule-reference.md#hide_tabs) rule action does the same thing declaratively. ### Case() Reads two values out of the case header on the page.

Method	Returns
`Case().CaseType()`	The case type name as displayed.
`Case().CaseReference()`	The case reference as displayed.

Both read the case details page directly, so both return an empty string anywhere that header is not on screen — a contact tab, or Client Connect. For anything else about the case, and for reliability, use `preLoadServerData` and the [Case Data API](/developer-documentation/case-data-api.md). ## Writing values ### Value3 is the standard way to set a field ```javascript CustomField(6216).Value3("Board A"); ``` `Value3()` works the field's type out from the control on the page and writes both halves of the field for you — the visible control and the hidden element carrying the value that is submitted — each in the form that half expects. You pass the value as a person would read it, and the encoding is handled.

Field type	Displayed	Stored
Text box, text area	`Board A`	`"Board A"`
Currency, numeric	`1250.00`	`"1250.00"`
Dropdown	The matching option selected	`["Board A"]`
Radio list, checkbox list	The matching box ticked	`["Board A"]`
Date picker	`01/04/2026`	`"20260401"`

Pass a **moment.js date** to a date picker, not a string — anything else clears the field. `Value3("")` clears any of the types above. Called with no argument it reads, behaving exactly like `Value()`. A call that only reads is clearer written as `Value()`. {% hint style="info" %} **Check boxes have their own syntax.** A Check Box field is ticked rather than filled in, so it is set through the control, with a triggered change so the stored value follows: ```javascript CustomField(6119).Input().prop('checked', true).triggerHandler('click'); ``` `Value3()` covers the five types in the table above; this line covers the sixth. {% endhint %} {% hint style="warning" %} Writing a field is not saving it. `Value3()` fills the form in as though the user had typed the value; it reaches the database when the form is saved, and is lost if they navigate away. A value that must be stored whether or not anybody presses Save belongs in an [on save script](/developer-documentation/case-scripting/on-save-scripts.md). {% endhint %} ### Writing from a ruleset The rules engine has its own syntax for writing a value: the [`set_values`](/developer-documentation/custom-form-scripting/rule-reference.md#set_values) action. It is the counterpart to `Value3()` inside a ruleset, and it takes the value in its **stored** form rather than as displayed, so the form you pass depends on the target's field type.

Target field type	Pass	Notes
Date picker	A moment.js date	Handled for you — the control and the stored value are both set from it.
Text box, text area, currency, numeric	`'"Approved"'`	Quoted, as text is stored. The quotes are part of the stored form and appear in the box on screen, which suits a field the user does not read.
Dropdown	`'["Approved"]'`	The list form, as a selection is stored. Setting `'["Please Select"]'` is the idiom for clearing one.
Radio list, checkbox list	`'["Approved"]'`	The list form. The stored value is what a save and a reload pick up.
Check box	Set it through the control	See the note above `Value3()`.

That is why existing rulesets are written as `"set_values": ['"' + value + '"']`, and against a dropdown as `"set_values": ["[\"Please Select\"]"]`. Which of the two to reach for follows from that: * **A date, or a value the user does not read** — a code, a flag, a field driving a template. `set_values` keeps the write inside the ruleset, where it sits alongside the hiding and disabling that go with it. * **A value the user sees on screen, and any list or check box you want ticked as well as stored** — work it out in JavaScript and write it with `Value3()`, then let rules handle the hiding, disabling, messaging and save-blocking around it. Most non-trivial labels use both, and that is the normal shape. {% hint style="info" %} A `set_values` rule sets its targets when the test passes and **clears** them when it does not, so the rule keeps the field in step with the condition in both directions. That makes it the right tool for a value the rule owns, and `Value3()` the one for a suggested value the user can then adjust. See [set\_values](/developer-documentation/custom-form-scripting/rule-reference.md#set_values). {% endhint %} ### setHiddenValueElement(node, value) The type-aware writer that `Value3()` calls. Reach for it directly only when you are writing a value that is already in its stored form and must not be re-encoded — the tick code from `helper_checkboxlist_to_list` is the usual case. ```javascript setHiddenValueElement(CustomField(6216).InputHidden(), "Board A"); ``` For everything else, `Value3()` is the same operation with the encoding done for you. ### helper\_checkboxlist\_to\_list(parent) Encodes a checkbox list as a positional tick code: the letter `R` followed by one `0` or `1` per box, in configured order, already wrapped in the double quotes that a stored text value carries. ```javascript var encoded = helper_checkboxlist_to_list(CustomField(6428).Input()); // "R1011" — first, third and fourth boxes ticked ``` This is **not** how a checkbox list stores its own value; that is a JSON array of the ticked option values. The code is for writing into a separate text field so a document template or report can read one short value instead of parsing a list — see [Encoding a Checkbox List](/developer-documentation/custom-form-scripting/examples/encoding-a-checkbox-list.md). Pass the field's `Input()`, which for a checkbox list is the container holding the boxes. Given a single checkbox it has nothing beneath it to walk and returns `"R"`, so a code shorter than the option list is a sign the wrong element went in. Because the returned string carries its own quotes, strip them before handing it to `Value3()`, which adds its own: ```javascript CustomField(6429).Value3(encoded.replace(/"/g, "")); ``` ### clearForm() Blanks every hidden value element on the form the label belongs to. {% hint style="info" %} `clearForm` walks every hidden input on the form and treats each as a custom field value. Forms carry other hidden inputs too, and reaching one of those ends the script early, so how much of the form is cleared depends on the order the inputs appear in. Test it on the form you intend it for. To clear a known set of fields, [`hide_and_blank`](/developer-documentation/custom-form-scripting/rule-reference.md#hide_and_blank) names its targets and is the more predictable choice. {% endhint %} ## Deprecated These are earlier forms of things the helper now does another way. They still work, and they are common in existing scripts, so it is worth recognising them — reach for the current form in anything new.

Earlier form	Current form
`setValueAndReturnNodes(node, value)`	`CustomField(id).Value3(value)`
`CustomField(id).Input().val(value)`	`CustomField(id).Value3(value)`
`ExecuteAllRulesOnChange(rules, id)`	Nothing needed — a label re-runs on every change already

The [`set_values`](/developer-documentation/custom-form-scripting/rule-reference.md#set_values) rule action is deliberately absent from that list. It shares an implementation with `setValueAndReturnNodes`, and so takes values in the same stored form, but it is the rules engine's own syntax for writing a value and stays current. See [Writing from a ruleset](#writing-from-a-ruleset). ### setValueAndReturnNodes(node, value) The original writer, from the first version of the helper. It takes the value in its **stored** form and puts it into both halves of the field: ```javascript setValueAndReturnNodes(CustomField(6424).Input(), '"Approved"'); ``` Hence the quotes: that is how a text value is stored, and they show in the box on screen as well. It covers text and — given a moment object — dates; dropdowns, lists and check boxes are set through their own controls. `Value3()` was added in 2018 to take the displayed form instead and work the encoding out per field type, which is why it is the one to use directly. `set_values` remains the way to express the same write inside a ruleset. ### CustomField(id).Input().val(value) Writes the visible control on its own, leaving the hidden element — and so the value that is submitted — as it was. That is what you want for a display-only control; where the value is meant to be kept, `Value3()` writes both halves. ### ExecuteAllRulesOnChange(rules, id) From a time when rulesets were held in globals with fixed names: the handler it binds re-runs a global called `ruleset3_set_values` rather than the array passed to it, so it only does anything for a script written to that convention. It appears in no live script. A label re-runs on every change to its form, which covers what this was for. Where you want a handler tied to one particular field, bind it yourself with a namespaced event so your script replaces its own handler on each run: ```javascript CustomField(6112).Input().off('change.rules').on('change.rules', function () { ExecuteAllRules(roleLayout); }); ``` ## Messages ### outputFieldMessage(id, message) Appends a red validation message underneath a field. The message is HTML, so it can carry markup. ### removeFieldMessage(id) Removes every message the helper has put under that field. Because a JavaScript label re-runs on every change, always clear before you write, or messages stack up as the user types: ```javascript removeFieldMessage(6116); if (guests > capacity) { outputFieldMessage(6116, "Guest count exceeds venue capacity."); } ``` The [`output_messages`](/developer-documentation/custom-form-scripting/rule-reference.md#output_messages) rule action pairs these two for you. ### outputSaveButtonMessage(message) and removeSaveButtonMessages() The same thing beside the form's Save button, for a message about the form as a whole rather than one field. [`ExecuteAllRules`](/developer-documentation/custom-form-scripting/rule-reference.md) manages these itself when a [`disable_save`](/developer-documentation/custom-form-scripting/rule-reference.md#disable_save) rule is in play, so call them directly only when you are blocking the save with your own code. ### setFieldRequired(node, state) Adds or removes the `required` class on a field, which is what marks it mandatory in the browser. ```javascript setFieldRequired(CustomField(6213).Input(), true); ``` It understands text boxes, text areas, radio lists and checkbox lists. Other field types are left alone. This is a display state only: it does not change the field's mandatory setting in the case type configuration. ## Layout ### HideInTable(column, groupId) Hides a column of a table control group, header and cells together. ```javascript HideInTable(10, 6421); ``` `column` is a position, counting from 1, not a field ID. `groupId` is the custom field group. Counting includes every column the grid renders, so the safest way to get the number right is to count them on screen. Hiding the column removes it from the grid. It does not hide the field in the row edit form — `CustomField(id).HideRow()` does that — so a column meant to be entirely internal usually needs both. ## Reading other tabs ### preLoadServerData(uriArguments) Calls the [Case Data API](/developer-documentation/case-data-api.md) for the current case and returns the whole response. ```javascript preloadCaseData = preLoadServerData('Custom.6311;Case.CaseReference;Contact.Client.Email'); var reference = preloadCaseData.data.caseFields[0].value; ``` The argument is the `getValues` string described in [Requesting Values](/developer-documentation/case-data-api/requesting-values.md): semicolon-separated tokens, one per value you want. Three things are worth knowing before you use it. * **It is synchronous.** The browser stops until the server answers, and that happens on every run of the script, so on every change to the form. One call asking for six values costs far less than six calls. * **Assign it to `preloadCaseData`, without `var`.** That is what lets `CustomField(id).Value()` fall back to it for fields on other tabs. * **Empty groups are absent, not empty.** The response leaves out `customFields`, `caseFields` or `customTables` entirely when nothing matched, so `preloadCaseData.data.caseFields[0]` throws rather than returning `undefined`. See [Response Format](/developer-documentation/case-data-api/response-format.md). It needs the global `caseid`, which exists on case pages and not on contact tabs. ### getCrossTabValueById(id) Fetches one custom field's value from elsewhere on the case, without building a request string. ```javascript var policyNumber = getCrossTabValueById(6313); ``` Also synchronous. Convenient for one value; for two or more, one `preLoadServerData` call is a single round trip instead of several. {% hint style="info" %} `getCrossTabValueById` builds its URL relative to the case page and does not adjust it for Client Connect, where `preLoadServerData` does. On a Client Connect form, preload. {% endhint %} ### Picking values out of a response

Function	Returns
`getFromJSONReponseById(array, id)`	The entry in a response array whose `id` matches. Note the spelling of `Reponse`.
`getFromJSONReponseByName(array, name)`	The entry whose `name` matches.
`getById(array, id)`	The same lookup as `getFromJSONReponseById`.
`getRowByName(name)`	A predicate for `$().filter()`, matching an entry by its `name`. In `customTables` that name is the custom field group's name, so this picks out a table.
`simplifyRowContent(row.items)`	Flattens one table row's `items` into a plain object keyed by column name, with spaces turned into underscores and other punctuation dropped.

All of them return `undefined` when nothing matches, so check before reading a property. A preloaded table has three levels — the table, its `rows`, and each row's `items`: ```javascript preloadCaseData = preLoadServerData('CaseTable.6320;'); var tables = preloadCaseData.data.customTables || []; var finance = $(tables).filter(getRowByName('Finance')); if (finance.length > 0) { var rows = finance[0].rows || []; var first = simplifyRowContent(rows[0].items); // first.Type, first.Amount, first.Received_Date } ``` Each row also carries `id` (its row number), `author` and `dateCreated`. See [Reading a Preloaded Table](/developer-documentation/custom-form-scripting/examples/looking-up-a-preloaded-table-row.md). ## Dates The date helpers are shared with the rule engine, and you can call them directly.

Function	Returns
`get_moment(value)`	A moment.js date. A value containing `/` is read as `DD/MM/YYYY`, anything else as `YYYYMMDD` — which covers both the displayed and the stored form of an AgileCase date.
`test_before(a, b)`	`true` when `a` is before `b`. `false` if either date is unreadable.
`test_after(a, b)`	`true` when `a` is after `b`, on the same terms.
`test_between(a, b, c)`	`true` when `a` falls after `b` and before `c`.

An empty field is not a readable date, so all three return `false` for one. Check for empty yourself if a missing date should mean something other than "the test did not pass". ## Comparisons These are the primitives behind the rule engine's string test types. They are occasionally useful directly.

Function	Returns
`test_equals(x, y)`	`x == y`, so `"5"` and `5` match.
`test_greater(x, y)` / `test_less(x, y)`	A plain `<` or `>`, which orders strings alphabetically — so `"9" > "10"`. Convert with `parseFloat` for a numeric comparison.
`test_in_list(x, list)`	`true` when `x` is one of the entries in `list`.
`test_contains(x, list)`	Whether `x` contains the last entry of `list`; pass a single-entry list. Use `test_contains_any` to test several.
`test_contains_any(x, list)`	Whether `x` contains any entry in `list`. This is the one to use for a list of several.

## Rules

Function	What it does
`ExecuteAllRules(rules)`	Runs an array of rules and applies the combined result, including enabling or disabling the Save button.
`ExecuteSingleRule(rule)`	Runs one rule on its own.
`ExecuteAllRulesOnChange(rules, id)`	An earlier form. A label re-runs on every change to its form already, so a ruleset is re-applied without it.

These are covered in full in the [Rule Reference](/developer-documentation/custom-form-scripting/rule-reference.md).