There are some points to be aware of when adding any JavaScript-manipulating Fields (Calculate, JavaScript, JavaScript - Button) to a Page.

 

Fields on the Page that contain JavaScript are executed in a particular order:

 

Upon a Page being loaded, all JavaScript Fields have their content executed, starting at the top-left Field on the Page, and finishing at the bottom-right Field. It should be noted that JavaScript Fields are executed prior to the full initialisation of Fields or System and Workflow Variables, and attempting to interact with any Fields or Variables at this stage may fail. As such, it's suggested that JavaScript Fields not be used for this purpose to avoid uncertainties.

 

After this, all Calculate and Conditional Builder Fields on the Page have their content executed. They execute from the top-left to the bottom-right, just as JavaScript Fields do.

 

Finally, any JavaScript - Button Fields with a configured Auto-Click option will have their content executed. They execute from the top-left to the bottom-right, just as JavaScript Fields do. If the Run Calculations option is enabled for any them, then refer to the section below.

 

 

When a Field on the Page has its value changed (with one exception, below), or a JavaScript - Button Field with the Run Calculations option enabled completes, then all Calculate and Conditional Builder Fields on the Page will execute their code again from the top-left to the bottom-right of the Page. Additionally, any Fields on the Page will have their visual state and values updated once these "Page Calculations" have completed.

 

The exception to Page Calculations being run when a Field's value is changed is when a JavaScript Promise or "callback" function are executed. This can lead to the mistaken perception that the callback or Promise has failed to trigger, and may require for Page Calculations to be triggered explicitly via Script.Utils.DoCalculations()or .click() a JavaScript - Button Field that has the Run Calculations option enabled.

 

Neither JavaScript Fields nor JavaScript - Button Fields will execute automatically as a result of a Field's value changing, although a JavaScript - Button Field may be manually triggered by the code executed by a Calculate Field, and functions defined in JavaScript Fields may be called by the code executed in a Calculate Field.

 

 

There are a number of Fields which will trigger Page Calculations, most commonly any button-type Fields will trigger Page Calculations to ensure that the most current information is used during their execution.

 

A special case of this is the JavaScript - Button Field. When a JavaScript - Button Field is clicked, its code will be executed but Page Calculations won't be automatically triggered. If it has the Run Calculations option enabled, then upon its completion it will trigger Page Calculations; if not, then no further action is taken.

 

 

In certain circumstances, it may be necessary to manually trigger any Calculate Fields on the Page to execute their code as described above. The most likely case for this is upon the completion of an asynchronous JavaScript process, such as a callback function, or JavaScript Promise. As these don't automatically invoke the re-running of Page Calculations, the default experience is that any values being set into the Workflow won't appear to the agent until Page Calculations are triggered by some other action (like the agent clicking a button or updating a Field).

 

To ensure that the agent is always presented with the current data, it may be necessary to use the Script.Utils.DoCalculations() Helper Function to cause the Page to properly synchronise and refresh its display with any changes from the asynchronous process. However, care needs to be taken not to use this Helper Function in such a way that it leads to a loop where it is repeatedly re-called, as otherwise the Page may cause the agent's browser tab to become unresponsive, and the Page to "crash".

 

 

Globally-scoped JavaScript code defined in different Fields can only be accessed and used by certain other Fields on the Page. The following table applies to globally-scoped content (e.g., defined with the var keyword), and block-scoped content (e.g., defined with the const or let keywords) will only be available within their local block scope.