|
|
Helper Functions
Helper Functions can be entered the same as any other JavaScript code in a Calculate, JavaScript, or JavaScript - Button Field. They enable the designer to use a single function to perform complex actions on the Page, such as controlling the visibility of multiple fields, manipulating data, or triggering integration functionality. They are split into groups based on their category, and briefly described below.
Please note that all of these Helper Functions are documented for the current version of Intelligent Agent, and for the most up-to-date System Controls. They may be incompatible with older versions of Intelligent Agent, Custom Controls, or outdated Control versions.
These Helper Functions are documented under Popping Mechanisms.
These Helper Functions are documented under Popping Mechanisms.
These Helper Functions allow retrieving System Attribute information relating to the current record and User. They each accept a single optional parameter, which if provided will filter the return to only include any System Attribute with a matching name, and return an array of objects consisting of {Name: "", Value: ""} pairs.
Note: these Helper Functions are asynchronous and make use of Promises. Promises are a form of JavaScript that allow for subsequent actions to be triggered once their asynchronous actions have been completed, and require a slightly different way of writing and designing your JavaScript. They also do not cause the usual Run Calculations process to occur when they complete, so if assigning a value to a Field then the assignment won't be visible to the agent until JavaScript is next triggered. An easy way to do this is to use Script.Utils.DoCalculations() or trigger a JavaScript - Button at the end of a Promise, as this will cause the Page to execute JavaScript immediately.
|
Name
|
Description
|
Code
|
|
Script.Attributes.Campaign.Get
|
Returns an array of objects of System Attributes relating to the currently-popped Campaign.
|
Script.Attributes.Campaign.Get()
.then(attributes => { // Make use of the returned data as desired
});
|
|
Script.Attributes.User.Get
|
Returns an array of objects of System Attributes relating to the current User.
|
Script.Attributes.User.Get("Primary Language")
.then(attributes => { [Agent Language] = attributes[0].Value;
});
|
|
Script.Attributes.Workflow.Get
|
Returns an array of objects of System Attributes relating to the currently-popped Workflow.
|
Script.Attributes.Workflow.Get("Internal Customer")
.then(attributes => { if (attributes[0] && attributes[0].Value) {
[var_RequireQA] = "No";
}
});
|
These Helper Functions are documented under Toolbar Buttons.
These Helper Functions allow the manipulation of a temporary data object that exists only within that record run. The data object can be pre-populated by pop data passed via External Links if enabled, specified in a Pop, or as part of an integration's pop, and can be freely read from or written to during the record.
|
Name
|
Description
|
Code
|
|
Script.Data.GetPostData
|
Returns the entire data object 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]);
|
These Helper Functions are documented in the Social Media Integration Guide for Helper Functions relating to processing and manipulating inbound mails, and Sending Emails with JavaScript for Helper Functions relating to sending outbound.
These Helper Functions are documented under Sending Events between Active Records with JavaScript.
These Helper Functions are used to manage Fields.
|
Name
|
Description
|
Code
|
|
Script.Fields.Enable
|
Enables Field(s). Enables a Field previously hidden using the Script.Fields.Disable() Helper Function or its Options tab.
|
Script.Fields.Enable("[Field1]","[Field2]","[Field3]");
|
|
Script.Fields.Disable
|
Disables Field(s). The Field will be visually "greyed-out". The Field can no longer be interacted with by the agent, but the Field is still visible and any data contained within it is still visible.
|
Script.Fields.Disable("[Field1]","[Field2]","[Field3]");
|
|
Script.Fields.Hide
|
Hides the specified Field(s) but retains a gap at the place previously occupied by the Field on the Page.
Note: if the height of a Field is altered while hidden (such as the dynamic text in a Text Label being altered), the gap where the hidden Field 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 name isn't recognised, 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 name isn't recognised, then it returns undefined.
|
Script.Fields.IsVisible("[Field1]"); //false
|
|
Script.Fields.NavigateIFrame
|
Allows the setting or alteration of an IFrame Field'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 data contained within it is still visible. Provides the same functionality as found in the Options tab.
|
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 collapses the space it previously occupied on the Page.
|
Script.Fields.Suppress("[Field1]","[Field2]","[Field3]");
|
These Helper Functions are used to format data. They can be used against a Field or Variable, or other variables within JavaScript, and allow applying similar behaviour to the Formatting tab from JavaScript.
|
Name
|
Description
|
Code
|
|
Script.Fields.Data.AlphaOnly
|
Removes any characters that aren't in the basic Latin alphabet (e.g., A-Z without accents or diacritics). Any numbers, symbols, or non-Latin characters will be removed.
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. Addition, subtraction, and decimal (+, -, .) characters are also removed.
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.If any non-numeric characters other than a single decimal point (.) are present, the Helper Function will return NaN (not a number).
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]);
|
These Helper Functions are documented under Toolbar Label - Add and Toolbar Label - Remove.
These Helper Functions are documented under Sending Messages with JavaScript.
These Helper Functions are documented under Toolbar Buttons.
These Helper Functions are documented under Popping Mechanisms.
These Helper Functions are documented under Reschedules.
These Helper Functions are documented under SMS.
These Helper Functions are documented under Toast Popup and Toast Remove.
These Helper Functions are used to fulfil a variety of purposes, including checking data types or content, or performing advanced actions.
|
Name
|
Description
|
Code
|
|
Script.Utils.ChangeRecordReference
|
Alters the Reference for the current record to the provided value. The new value must still be unique within the Campaign.
Note that when the Helper Function completes, it triggers the running of Page Calculations.
|
Script.Utils.ChangeRecordReference("NewReference");
|
|
Script.Utils.DoCalculations
|
This Helper Function triggers the running of Page calculations, as documented in the JavaScript Code Execution article. It should only be used in limited circumstances where it is specifically required, and great care should be taken to ensure that it will not lead to a loop where it is repeatedly called, as else it may lead to the Page becoming unresponsive or crashing.
|
MyPromise()
.then(response => {
[Caller Name] = response.Name;
Script.Utils.DoCalculations();
});
|
|
Script.Utils.GetAllFieldsAndVariables
|
Returns a JavaScript object containing all Fields on the current Page, and all Variables in the Workflow. The JavaScript object is formatted with the Field or Variable's 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
|
Helper 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.GetFieldMappings
|
Returns a JavaScript object of all of the Fields in the Workflow. The JavaSCript object is formatted with the Field's name as the key, and the Field's unique ID as the value.
For example:
{"Caller Name": 37, "Space_38": 38, "Outcome - Button": 39}
|
var workflowFieldMappings = Script.Utils.GetFieldMappings();
|
|
Script.Utils.GetGuid
|
Generates and 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
|
Displays an error modal containing configurable 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 parameter 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 parameter is undefined, null, or composed entirely of whitespace.
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 parameter 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 contained 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 similar core JavaScript functionality, see String Interpolation.
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 the Workflow to navigate to the named Page. Be aware that this doesn't trigger Page Validation, and isn't detected by the Check Workflow functionality, potentially leading to warnings of unlinked pages.
|
Script.Utils.Navigate("02 Next Page Name");
|
|
Script.Utils.UpdateFieldOrVariable
|
Allows setting the value of a Field on the current Page, or a Variable.
The first parameter is a string of the Field or Variable's name (excluding the surrounding square brackets).
The second parameter is a string of the value to be assigned to the Field or Variable.
|
Script.Utils.UpdateFieldOrVariable("Field 1", "My value");
|
|
Script.Utils.UpdateMultipleFields
|
Allows the immediate setting of the value of one of more Field in the Workflow, 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 key:value pairs 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 Helper 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
|
Triggers Page Validation on any Fields that have any Validation options enabled. Any Fields that fail their Validation condition 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
}
|
These Helper Functions don't fit into the other categories, and have varied functionality.
|
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 Helper 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 recorded 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 specify the record's outcome.
preserveState: A boolean (true/false) of whether to preserve the record's state.
preserveToolbar (Optional): A boolean of whether to retain the record 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 record, 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 record run, with the option to preserve the Workflow's state in the database. If the Workflow state is preserved, the record run can be resumed at a later date (via a method like JavaScript Pop), or even left in a suspended state that the agent can resume at will. If this method is used, then end-of-record data isn't submitted to any integration that may have been linked to the Campaign.
The first parameter is the outcome, a string used to specify the record's outcome.
The second parameter is a boolean (true/false) of whether to preserve the record state.
The third parameter is an optional boolean of whether to retain the record 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 include in the Campaign View's record history.
|
Close the current record, leaving the disposition as "Transferred" and the record ready to be resumed in the future:
Script.FinishScript("Transferred", true);
Suspend the current record, 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 JavaScript 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 licence parts that have been assigned to the User.
Attributes: an object of any System Attributes have been added to the User, as name:value pairs.
|
Display a Toast Popup to agents who are members of 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 record or not. This allows the override of any global setting in CTCallDisconnectOnClose (default is true) on a per-record basis. This is only usable with specific integrations.
If set to true, the interaction will be closed on record completion.
If set to false, the interaction won't be closed on record completion.
|
Script.CTI.DisconnectOnClose(false);
|
|
Script.Info.GetSessionId
|
Returns the Session ID of the current record, similarly to [var_csSessionID].
|
var sessionId = Script.Info.GetSessionId();
|
|
Script.Info.GetScriptId
|
Returns the Workflow ID of the current record, similarly to [var_csScriptID].
|
var scriptId = Script.Info.GetScriptId();
|