Run Once: Ensuring a Control Containing Code Only Fires Once

In some instances it's desirable to execute code only once, rather than whenever page calculations are run. For example, a database control that populates script fields may be set to run each time the page loads, and you may wish to stop this happening should an agent navigate back and forth to a script page.

When this is the case, it's common to use a "Run Once".


A Run Once is a conditional statements that encloses the code to be executed once, and that sets the value it checks against: 

if ([Run Once] == "ready") {
    // This is where the code to be executed once is located
    [Run Once] = "run";

The initial condition will only succeed when the Run Once value is at its default value of "ready", and when the statement finishes the control is then set to a value of "run" to prevent re-execution of the enclosed code. These initial values and set values can be anything you choose, and as long as the checked value doesn't equal the value within the condition the contained code will not be re-run.

There are two main styles of Run Once used, either using a JavaScript variable or a script field to hold the value that controls whether the code is executed. The two styles are implemented identically, but have different characteristics and uses:

JavaScript Script Field
Value is lost on page refresh or transition. Value survives page refresh or transition.
Can be used to allow a block of code to run once, every time a page is loaded. Can be used to allow a block of code to be run only the first time a page is loaded.
Mostly used to reduce needless resetting of values, or firing intensive code. Mostly used to prevent a one-time action being repeated.


To differentiate between these styles, we will refer to the JavaScript version as a runOnce and the Script Field version as a [Run Once].



It is also important consider other scenarios - for example, if the script will be re-popped (for example, in the event of a rescheduled call). In instances such as this, the Run Once behaviour becomes more complicated, and is outside the scope of this article.

Note that in some instances JavaScript Run Once functionality could be side-stepped by simply placing the code within a JavaScript control (which only runs once on page load), but in many cases this isn't possible as it requires the code to be executed after some initial condition has been reached such as required data having been input by an agent.

Both examples below are written for Synergy users, if using CallScripter 4.5 the process is similar but please contact the helpdesk if you require further guidance.


Example: JavaScript runOnce

A Hidden field is used to transfer a customer's name between pages, and on this page the agent has the opportunity to edit it. Having the Text Box pre-populated with the customer's stored name would be useful, but presents a problem: if the Text Box value is just set to equal a Hidden field's value, then any changes made to the Text Box will simply be overwritten from the original value stored in the Hidden field when the agent leaves the Text Box. A solution in this case is to use a runOnce:


1) Create a Text Box, and Hidden, JavaScript and Calculate fields:


2) Create the runOnce variable in the JavaScript field. Note that this must be done in the JavaScript field and not a Calculate field, as variables in the Calculate field are lost each time page calculations occur, so the runOnce would run every time!


3) Add the desired code to the Calculate field: 


Now when the page loads it will cause the Text Box to be initially populated from the Hidden field, but after that the Text Box is only editable by the agent rather than the script. Note that as the final line of code is outside the runOnce, any subsequent changes to the Text Box will be written back to the Hidden field.


Example: Script Field [Run Once]

An External Data Source is used to populate a customer's details into Text Boxes. If we return to the page with the External Data Source control we don't want to re-run the query and potentially overwrite any changes made to the details. One solution is to use a [Run Once] that triggers the External Data Source where appropriate:


1) Create the Text Boxes, External Data Source, and Hidden and Calculate fields:


2) Configure the External Data Source so that it won't automatically trigger, and isn't visible by default:


3) Add the desired code to the Calculate field:


Now, when the page is first loaded it will trigger the External Data Source, but upon returning to the page, the External Data Source control will not trigger again.