Defining JavaScript that is accessible in all scripts: custom.js

This is an advanced feature, and carries the risk of damaging your operations if improperly used. Caution is advised, and please contact the CallScripter Helpdesk if you have any queries about this.

There are instances when there is JavaScript code that needs to be available to many different scripts. Instead of manually copying the code into different scripts and having to propagate any changes made to all instances of this code, it can be useful to define the code in a single place and then have all it available to all scripts. This is what the custom.js file is for.


Using this functionality requires write access to the file structure at the Synergy or CallScripter install locations. custom.js is located within the Synergy or CallScripter installations, note the difference in capitalisation:
  • Synergy location: \%%Your Synergy Install Folder%%\wwwroot\lib\custom.js
  • CallScripter 4.5 location: \%%Your CallScripter 4.5 Install Folder%%\wwwroot\Lib\custom.js
If the file doesn't exist it can be freely created as long as the name matches, and there may be an example custom.js.sample file located in the folder for reference - simply removing the .sample suffix will make it active.

Considerations and Risks

Any JavaScript within custom.js will be executed shortly before the page is fully rendered, during the final stages of the page initialisation process. As such, the contents of custom.js should be written such that they do not execute unless called by an agent action or code within a script Calculate, JavaScript or JavaScript Button field (i.e., simple declaration of variables or functions that are available within a script, rather than active code). Failure to do so may cause the JavaScript within custom.js to try and manipulate unready or non-existent page elements, causing unexpected and potentially breaking behaviour.
Any JavaScript placed within custom.js is available inside all Synergy or CallScripter 4.5 scripts for that installation. As such, caution should be made with the code that is included in this file is correct, and that there are no collisions between the names of any variables or functions in custom.js and any script-defined variables or functions.
  • If the JavaScript in custom.js is broken in any way, it may instantly disrupt or even break all scripts runs until remedied. This includes pages rendering incorrectly, page elements being non-functional, and failure to transfer data to and from the SQL database or run reports.
  • If the JavaScript in custom.js shares the name of any JavaScript variables or functions defined within the Synergy or CallScripter 4.5 product, then a collision will occur. The most likely result is that the variable or function defined in custom.js will be overridden, but it may in some cases cause sections of the core product to stop working at all.
  • If the JavaScript in custom.js shares the name of any JavaScript variables or functions defined within individual scripts, then a collision will occur. The most likely result will be that the script-defined variable or function overrides the custom.js defined variable or function, but in some cases improper mixing of data may occur.
As a result of the above concerns, it is recommended that this only be used by competent JavaScript coders and that the utilised code be stored inside a uniquely titled "namespace". For instance, if your company name was "CallCom", then placing all the defined functions and variables within "CallCom_Custom" in custom.js would reduce the chance of such collisions:
var CallCom_Custom = {};

CallCom_Custom.ManagerName = "Joe Bloggs";
CallCom_Custom.addOrder = new function() { /* Some code goes here */; }
Also to be noted is that any changes to custom.js will be made live immediately, and as soon as an agent starts a script or transitions to a fresh page they will be using the updated JavaScript defined in custom.js. As such, any alterations should ideally be tested in a development instance prior to deployment, and deployed during non-critical times so that a rollback can be made to the old custom.js if a problem is noticed with minimal disruption.
Finally, custom.js is specific to each installation of Synergy or CallScripter 4.5. In instances where multiple installations all access the same database, it will be necessary to manually copy the relevant custom.js content to each seperate installation. This also means that custom.js should be included in any backup processes that are undertaken to avoid a loss of functionality should the system need to be reinstalled or upgraded.