Helper Functions

 
Helper functions can be entered the same as any other JavaScript code in Calculate Field, JavaScript, or JavaScript Button controls. They enable the Workflow builder to use a single function to perform complex actions on the Workflow page, such as showing, hiding, or suppressing multiple fields. They are split into groups based on their category, and briefly described below - for further detail and examples please see the Knowledge Base.
 
Please note that all of these functions are documented for the current release of Scripting, and for the most up-to-date System Controls. They may be incompatible with older releases of Scripting, or Custom/outdated Controls.
 

Desktop.Pop

These functions are documented under Popping Mechanisms.
 
 

Desktop.Queue

These functions are documented under Popping Mechanisms.
 
 

Script.CTI.Buttons

These functions are documented under Toolbar Buttons.
 
 

Script.Data

These functions allow the manipulation of a temporary data stash that exists only within that session. The stash is pre-populated by pop data passed via External Links, if enabled, or specified in a Pop, and can be freely read or written to during the Workflow run. Note that when used in a Workflow popped from the Social Dashboard, this holds a structured data object populated with the data returned from the Social provider that is used to build the displayed content.
Name
Description
Code
Script.Data.GetPostData
Returns the entire data stash as a JavaScript object, formatted as a list of key:value pairs.
var myData = Script.Data.GetPostData();
Script.Data.GetPostDataItem
Returns the value of the particular data item identified by the supplied key. Key must be provided as a string.
[Customer Name] = Script.Data.GetPostDataItem("name");
Script.Data.SetPostDataItem
Sets the value of the particular data item identified by the supplied key. Key must be provided as a string.
Script.Data.SetPostDataItem("age", [Customer Age]);
 
 

Script.Email

These functions are documented in the Social Media Guide for inbound functions, and Sending Emails with JavaScript for outbound functions.
 
 

Script.Events

These functions are documented under Sending Events between Active Sessions with JavaScript.
 
 

Script.Fields

These functions are used to manage Workflow fields.
Name
Description
Code
Script.Fields.Enable
Enables field(s). Enables a field previously hidden using the Script.Fields.Disable() function.
Script.Fields.Enable("[Field1]","[Field2]","[Field3]");
Script.Fields.Disable
Disables field(s). The field will be "greyed-out". The field can no longer be interacted with by the agent, but the field is still visible and any information contained within them is still visible.
Script.Fields.Disable("[Field1]","[Field2]","[Field3]");
Script.Fields.Hide
Hides the specified field(s) but retains the place previously occupied by the field.
 
Note: if the height of a control is altered while hidden (such as the text in a Text Label being altered), the gap where the hidden control is placed will also alter in height.
Script.Fields.Hide("[Field1]","[Field2]","[Field3]");
Script.Fields.IsEnabled
Returns true or false depending on whether the provided Field is enabled or disabled. If the Field isn't recognise, then it returns undefined.
Script.Fields.IsEnabled("[Field1]"); //true
Script.Fields.IsVisible
Returns true or false depending on whether the provided Field is visible or hidden/suppressed. If the Field isn't recognise, then it returns undefined.
Script.Fields.IsVisible("[Field1]"); //false
Script.Fields.NavigateIFrame
Allows the setting or alteration of an IFrame's destination URL.
Script.Fields.NavigateIFrame("[IFrame]", "http://www.example.com");
Script.Fields.ReadOnly
Sets/unsets field(s) as Read Only. The field will appear visually the same as a normal field when Read Only. The field can no longer be interacted with by the agent, but the field is still visible and any information contained within them is still visible. Provides same functionality as found in the Field Properties.
Script.Fields.ReadOnly(true, "[Field1]","[Field2]");
Script.Fields.ReadOnly(false, "[Field1]","[Field2]");
Script.Fields.Show
Shows field(s) that have been previously hidden or suppressed.
Script.Fields.Show("[Field1]","[Field2]","[Field3]");
Script.Fields.Suppress
Suppress (hide) the specified field(s) AND the space it previously occupied.
Script.Fields.Suppress("[Field1]","[Field2]","[Field3]");
 
 

Script.Fields.Data

These functions are used to format data.
Name
Description
Code
Script.Fields.Data.AlphaOnly
Removes any non-English alphabet characters from a string.
For example:
Script.Fields.Data.AlphaOnly("a1b2c3") //"abc"
[Field] = Script.Fields.Data.AlphaOnly([Field]);
Script.Fields.Data.NumbersOnly
Removes any non-numeric characters from a string.
For example:
Script.Fields.Data.NumbersOnly("a1b2c3") //"123"
[Field] = Script.Fields.Data.NumbersOnly([Field]);
Script.Fields.Data.Money
Takes a number or numeric string, and returns it as a numeric string formatted with two decimal places
For example:
Script.Fields.Data.Money(1/3) //"0.33"
Script.Fields.Data.Money("10") //"10.00"
[Field] = Script.Fields.Data.Money([Field]);
Script.Fields.Data.LeftTrim
Removes any whitespace from the left end of a string.
[Field] = Script.Fields.Data.LeftTrim([Field]);
Script.Fields.Data.RightTrim
Removes any whitespace from the right end of a string.
[Field] = Script.Fields.Data.RightTrim([Field]);
Script.Fields.Data.Trim
Removes any whitespace from both ends of a string.
[Field] = Script.Fields.Data.Trim([Field]);
Script.Fields.Data.ProperCase
Capitalises the first letter of every word, makes every other character lower case.
For example:
Script.Fields.Data.ProperCase("this has no capitals") //"This Has No Capitals"
Script.Fields.Data.ProperCase("THIS IS ALL CAPITALS") //"This Is All Capitals"
[Field] = Script.Fields.Data.ProperCase([Field]);
Script.Fields.Data.StartCase
Alias for Script.Fields.Data.ProperCase
[Field] = Script.Fields.Data.StartCase([Field]);
Script.Fields.Data.TitleCase
Capitalises the first letter of a sentence, leaves every other character unchanged.
For example:
Script.Fields.Data.TitleCase("this has no capitals") //"This has no capitals"
Script.Fields.Data.TitleCase("this has Some capitals") //"This has Some capitals"
Script.Fields.Data.TitleCase("THIS IS ALL CAPITALS") //"THIS IS ALL CAPITALS"
[Field] = Script.Fields.Data.TitleCase([Field]);
 
 

Script.Labels

These functions are documented under Toolbar Label - Add and Toolbar Label - Remove.
 
 

Script.Message

These functions are documented under Sending Messages with JavaScript.
 
 

Script.NavigationButtons

These functions are documented under Toolbar Buttons.
 
 

Script.Queue

These functions are documented under Popping Mechanisms.
 
 

Script.Reschedule

These functions are documented under Reschedules.
 
 

Script.Sms

These functions are documented under SMS.
 
 

Script.Toast

These functions are documented under Toast Popup and Toast Remove.
 
 

Script.Utils

These functions are used to fulfil a variety of purposes, including validation.
Name
Description
Code
Script.Utils.ChangeRecordReference
Alters the campaign reference for the current Workflow run to the provided value. The new value must still be unique within the campaign.
Note that when the function completes, it triggers the Workflow to run calculations again.
Script.Utils.ChangeRecordReference("NewReference");
Script.Utils.GetAllFieldsAndVariables
Returns a JavaScript object of all Fields on the page, and all variables in the Workflow. The object is formatted with the Field or variable name as the Key, and the Field or variable's value as the Value.
For example:
{Caller Name:"Joe Bloggs", var_csAgentName:"Jane Doe"}
var pageData = Script.Utils.GetAllFieldsAndVariables();
Script.Utils.GetCSObject
Function to return the field as an HTML DOM element. This result can be used in the same way as document.getElementById in a normal web form.
 
Further examples and details are located in the Knowledge Base.
Script.Utils.GetCSObject([Field Name]);
 
After the element has been accessed you can then use its properties/actions. For example, to click a button:
Script.Utils.GetCSObject([Field Name]).click();
Script.Utils.GetGuid
Returns a GUID containing both letters and numbers, of the form XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
For example:
5D3F830A-ADA8-4568-9AAC-26E7263C6103
[Reference Number] = Script.Utils.GetGuid();
Script.Utils.GeneralException
Pops up an error modal containing user-defined text, and immediately ends the Workflow. Accepts two parameters, which are displayed in the error modal as text - typically, used as a heading or class, and then a descriptive section.
Script.Utils.GeneralException("Access error", "Unable to contact the customer database");
Script.Utils.isJson
Returns true or false depending on whether the supplied thing is a JSON string.
For example:
Script.Utils.isJson('{"key":"value"}') //true
Script.Utils.isJson({key:"value"}) //false
Script.Utils.isJson("Hello") //false
if (Script.Utils.isJson(thing)) {
    //Do something with the JSON string
}
Script.Utils.isNullOrWhiteSpace
Returns true or false depending on whether the supplied thing is undefined/null/composed entirely of whitespace, or not.
For example:
Script.Utils.isNullOrWhiteSpace(undefined) //true
Script.Utils.isNullOrWhiteSpace("   ") //true
Script.Utils.isNullOrWhiteSpace("Hello") //false
if (Script.Utils.isNullOrWhiteSpace(thing)){
    //Do something with the empty thing
}
Script.Utils.isNumeric
Returns true of false depending on whether the supplied thing is numeric or not.
For example:
Script.Utils.isNumeric(3) //true
Script.Utils.isNumeric("10.2") //true
Script.Utils.isNumeric("Hello") //false
if (Script.Utils.isNumeric(thing)){
    //Do something with the numeric
}
Script.Utils.StartsOrEndsWithSpace
Returns true or false depending on whether the supplied string has any leading or trailing whitespace.
For example:
Script.Utils.StartsOrEndsWithSpace("Hello") //false
Script.Utils.StartsOrEndsWithSpace(" Hello") //true
Script.Utils.StartsOrEndsWithSpace("Hello ") //true
Script.Utils.StartsOrEndsWithSpace(" Hello ") //true
if (Script.Utils.StartsOrEndsWithSpace(myString)){
    //Do something to the whitespace-wrapped string
}
Script.Utils.StringFormat
Allows the construction of a string with a placeholders replaced by supplied parameters. May result in easier-to-read code in some cases when trying to assemble large strings with many dynamic elements.
For example:
String.Utils.StringFormat("Hello, my name is {0}. {0} is short for {1}, and my username is {2}", "Joe", "Joseph", [var_csAgentUserName]); //"Hello, my name is Joe. Joe is short for Joseph, and my username is joe.bloggs"
[Greeting] = String.Utils.StringFormat("Good {0}, you've reached the {1} answering service. How can I direct your call this {0}?", [timeOfDay], [companyName]);
Script.Utils.Navigate
Triggers page transition to the named Workflow page. Be aware that this doesn't fire page validation, and isn't detected by Workflow checking (potentially leading to warnings of unlinked pages).
Script.Utils.Navigate("02 Next Page Name");
Script.Utils.UpdateFieldOrVariable
Allows the setting of a Workflow Field on the current page, or Variables.
 
The first parameter is a string of the Field or Variable name (excluding the surrounding square brackets).
The second parameter is a string of the value to be set to the Field or Variable.
Script.Utils.UpdateFieldOrVariable("Field 1", "My value");
Script.Utils.UpdateMultipleFields
Allows the immediate setting of the value of any Workflow field, regardless of whether it's on the current page or not. It cannot be used to set the value of Variables.
 
The first parameter is a JavaScript object containing a dictionary of Field names and the values they are to be set to.
The second parameter is an optional "callback" function that can be used to execute further JavaScript once the function has completed.
var fieldData = {
    "Field 1":"Value 1",
    "Field 2":"Value 2"
};
Script.Utils.UpdateMultipleFields(fieldData, function(response) {
    if (response.success) {alert("Set values to database")}
    else {alert("Unable to set values to database")}
});
Script.Utils.ValidatePage
Runs page validation on any Fields that have validation enabled. Any Fields that fail the validation will be highlighted in red until remedied. It accepts a boolean (true/false) argument that controls whether the normal "validation failed" warning modal is hidden or not.
Script.Utils.ValidatePage(true); //Warning modal isn't displayed if validation fails
Script.Utils.ValidatePage(false); //Warning modal is displayed if validation fails
if (Script.Utils.ValidatePage(true)) {
    //Continue, page passed validation
}
 
 

Other

Name
Description
Code
Script.CancelRecord
Allows the immediate cancellation of all outstanding activities relating to a provided Outbound ID, including any pending reschedules, unsent messages, or incomplete records or transfers. This function is only intended for use with records that aren't being actively run by an agent at the time. There is also an identical Desktop.CancelRecord() helper function, for use by plugins and non-Workflow development..
The first parameter is the Outbound ID that will have all related activities cancelled.
The second parameter is the outcome, a string that will be stamped on the relevant closure entries.
The third parameter is an optional string of the connector type to mark as having initiated the closure.
The fourth parameter is an optional string of the connector name to mark as having initiated the closure.
Script.CancelRecord([Outbound Record To Close], "Dispatched engineer closing record", "connector-email
", "Dispatch (Inbound)");
Script.Finish
An object-based variant of Script.FinishScript.
outcome: A string used to determine the Workflow run's disposition.
preserveState: A boolean (true/false) of whether to preserve the Workflow state.
preserveToolbar (Optional): A boolean of whether to retain the Workflow as an in-progress activity. If this is true, it will override the preserveState parameter to also be true.
comments (Optional): A string that will be included in the Campaign View's record history.
Suspend the current Workflow, allowing the agent to resume it at will:
Script.Finish({outcome:"Paused", preserveState:true, preserveToolbar:true, comments:"Paused while consulting with manager"});
Script.FinishScript
Allows the immediate closure or suspension of the current Workflow run, with the option to preserve the Workflow state in the database. If the Workflow state is preserved, the Workflow run can be resumed at a later date (via a method like JavaScript Pop, and even left in a suspended state that the agent can resume at will. If this method is used, then record data isn't submitted to any integration that may have been linked to the Workflow.
The first parameter is the outcome, a string used to determine the Workflow run's disposition.
The second parameter is a boolean (true/false) of whether to preserve the Workflow state.
The third parameter is an optional boolean of whether to retain the Workflow as an in-progress activity. If this is true, it will override the second parameter to also be true.
The fourth parameter is an optional comment to attach to this history entry, a string that can be reported on via Data Extracts.
Close the current Workflow, leaving the disposition as "Transferred" and the Workflow ready to be resumed in the future:
Script.FinishScript("Transferred", true);
 
Suspend the current Workflow, allowing the agent to resume it at will:
Script.FinishScript("Paused", true, true, "Taking priority call for client");
Script.GetCurrentUser
Returns a JavaScript object that contains various information about the current user. Requires no parameters, but some of the items in the returned object are listed below.
 
AssignedGroups: an array of objects, each containing the ID and name of the user's groups.
AssignedParts: an array of the licences that have been assigned to the user.
Attributes: an object of any System Attributes have been added to the users, in name:value pairs.
Pop a toast alert to users in a particular group.
var groups = Script.GetCurrentUser().AssignedGroups;
for (var x in groups) {
    if (groups[x].Name == "Training") {
        Script.Toast.Info("Remember!", "Always speak with a smile, and keep the notes updated as the call progresses");
    }
}
Script.CTI.DisconnectOnClose
Determines whether the interaction should be closed automatically at the end of the Workflow run or not. This allows the override of any global setting in CTCallDisconnectOnClose (default is true) on a per-Workflow basis.
If set to true, the interaction will be closed on Workflow completion.
If set to false, the interaction won't be closed on Workflow completion.
Script.CTI.DisconnectOnClose(false);
Script.Info.GetSessionId
Returns the Session ID of the current Workflow run, similarly to [var_csSessionID].
var sessionId = Script.Info.GetSessionId();
Script.Info.GetScriptId
Returns the Workflow ID of the current Workflow run, similarly to [var_csScriptID].
var scriptId = Script.Info.GetScriptId();