Variables
Contents
Learn how to use variables in Designer.
You can use two types of variables in Designer:
- User Variables - These are variables that you create. You can use these variables throughout the application and in all phases.
- System Variables - These variables are created with the application and cannot be deleted.
Tips
Variable names must be alphanumeric, but not start with a numeric character. For example:
- Valid variable names = abcdef123 or c123badef
- Invalid variable names = 123abcdef or 3abcdef21
Variable values may be:
- ECMAScript objects, such as Date().
- Valid ECMAScript expressions. Do not add an ending semi-colon (;) as typically required by ECMAScript.
- Simple values, such as numeric or string.
- If the value is a string, it must be surrounded by single quotes (for example, 'value'). If the value also uses a single quote, you can use a backslash to escape the quote character (for example 'Joe\'s Pizza').
User Variables
You can add user variables in the Initialize phase. You can assign initial values to these variables in the Initialize phase, or by setting values in an Assign block in the Initialize phase.
You can also assign a system variable as the default value of a user variable. For example, you might assign the system variable DNIS to a user variable you have created. (If the system variable does not have a value at the time of the call, the default values are used.) This is also supported for Self Service Shared Modules.
Securing Variables
Variable values can be captured in a variety of data sources when Designer applications run on the Genesys platform. If a variable contains sensitive data or personally-identifiable information (PII), you can mark a variable as Secure to prevent the value from being logged or recorded as plain text in Designer and the Genesys platform.
How secure variables work:
- Secure variable values are not captured by application logs.
- If used to store the results of a user input, the user input is masked in platform logs.
- If used to play back a prompt, the prompt message is masked in platform logs.
- Secure variables are hidden from view to prevent them from being selected in blocks that record reporting information, such as Call Data, Activity, and Milestone blocks. (See the Warning below for more details.)
- Secure variables are not reported in Designer Analytics.
If you secure variables in an application that has already been published, you'll need to re-publish the application for the new settings to take effect.
- DO NOT attach sensitive data, such as personally identifiable information (PII) or secure variables, to userdata in the Call Data block. Otherwise, this information is captured by platform logs and reported in Designer Analytics.
- Designer normally hides secure variables to prevent them from being selected in blocks that capture reporting information. However, if you secure a variable that was previously selected in a block as a non-secure variable, Designer cannot remove the variable from the block or prevent its value from being exposed. To protect those values, you must create a new secure variable and re-publish your application.
Tracing variables
At this time, Genesys recommends not enabling the Trace option for variables. Instead, use a Debug block.
System Variables
The Initialize phase has a second tab that lists system variables — these variables are created with the application and cannot be deleted.
Most system variables are initialized with appropriate values when the application session starts and can be used throughout the application, such as the ANI and DNIS. Other system variables, such as Last Milestone, are populated as the application session progresses. For example, when the application starts, the initial value of Last Milestone is an empty string. While the application runs, the Last Milestone value is set to the last milestone that the application reached.
Designer also uses certain internal system variables at various stages of the applications session. These are intended only for internal use by Designer. For more information, see Internal Designer system variables.
List of System Variables
| Variable Name | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ChatEntryPoint | Holds the point of entry for a chat interaction. Can be used in application logic at runtime to provide alternative processing or to facilitate the use of parallel testing environments. | ||||||||||||
| DNIS | Specifies the dialed number. | ||||||||||||
| ANI | The number associated with the calling party. | ||||||||||||
| MaxTime | Maximum time (in minutes) to keep this session alive. For more information, see Setting the MaxTime value. | ||||||||||||
| Timezone | The timezone used for this application, unless this value is overridden in other blocks. | ||||||||||||
| Language | The default language for this application that is used for announcements. | ||||||||||||
| AppLanguageName | The name of the default language for this application that is used for announcements. | ||||||||||||
| Persona | The persona to be used for this application. For more information, see Personas. | ||||||||||||
| RoutingSkills | A set of skills that might be specified in some blocks, such as Menu Option child blocks, that determine how the call is routed. For example, if you select a Skill in the Call Handling tab of a Menu Option block, this selection is stored in the RoutingSkills variable. Then, in a subsequent Route Call block, you can enable the Use system variables RoutingSkills and RoutingVirtualQueue set already in Menu Options check box to use the value of the RoutingSkills variable. | ||||||||||||
| RoutingVirtualQueue | A virtual queue that might be specified in some blocks, such as Menu Option child blocks, that is used for routing unless a different queue is specified in Routing blocks. For example, if you select a Virtual Queue in the Call Handling tab of a Menu Option block, this selection is stored in the RoutingVirtualQueue variable. Then, in a subsequent Route Call block, you can enable the Use system variables RoutingSkills and RoutingVirtualQueue set already in Menu Options check box to use the value of the RoutingVirtualQueue variable. | ||||||||||||
| EstimatedWaitTime | The estimated wait time for the interaction to be routed to an agent. | ||||||||||||
| TreatmentIterationCount | Keeps track of how many times a treatment has been executed. | ||||||||||||
| IVRProfileName | The IVR Profile to associate the interactions with for VAR reporting. The default value is 'auto'.
| ||||||||||||
| GVPTenantID | The tenant to associate the interactions with for VAR reporting. The default value is 'auto'.
| ||||||||||||
| SelectedTarget | The DN and the switch name of the target to which the interaction was routed or should be routed to definitively. The target format is Name@SwitchName.Type.
| ||||||||||||
| SelectedVirtualQueue | The virtual queue that was selected. | ||||||||||||
| SelectedComponent | The agent-level target to which the interaction was routed or should be routed to definitively. If the target selected for routing is of type Agent, Place, Queue, or Routing Point, this variable contains the target. If the desired target type is Agent Group, Place Group, or Queue Group, the function returns the agent, place, or queue from the corresponding group to which the interaction was sent. The target format is Name@StatServerName.Type.
| ||||||||||||
| SelectedTargetObject | This is the high-level target to which the interaction was routed or should be routed to definitively. If a skill expression is used, the function returns: ?:SkillExpression@statserver.GA or ?GroupName:SkillExpression@statserver.GA. The target format is Name@StatServerName.Type.
| ||||||||||||
| SelectedAgent | This is the Employee ID of the agent to which the interaction was routed. | ||||||||||||
| Access | (Optional) When present, this is an ECMAScript object that represents a switch access code. The table below show its properties and the corresponding switch access code fields:
| ||||||||||||
| CustomerSegment | The segment to which the customer belongs, based on information that the customer has provided. | ||||||||||||
| CustomerId | A unique identifier for the customer, based on information that the customer has provided. | ||||||||||||
| EnableSSRecording | Enable interaction recording in the Self Service phase. | ||||||||||||
| CallbackReporting | An object containing key-value pairs for callback reporting. | ||||||||||||
| PositionInQueue | The interaction's position in queue while waiting to be routed to an agent. This variable is initialized when the application enters a Route Call block. The value is then updated periodically (every x seconds) for as long as the interaction is queued for a target inside the block. The updates stop when the application exits the routing block. | ||||||||||||
| AgentsTotalSize | The total number of agents that are potentially available. For example, the total number of agents in a specified Agent Group. | ||||||||||||
| AgentsLoginSize | The number of agents that are actually logged in. | ||||||||||||
| AppCountry | The country code for this interaction (can be specified by the application). | ||||||||||||
| AppCountryName | The country name for this interaction (can be specified by the application). | ||||||||||||
| AppRegion | The region for this interaction (can be specified by the application). | ||||||||||||
| AppCallType | The type of interaction (can be specified by the application). | ||||||||||||
| AppUserDisposition | A custom disposition that the application can use to specify a user-specific outcome. | ||||||||||||
| AppUserDispositionCategory | A custom disposition category that the application can use to categorize user-specific outcomes. | ||||||||||||
| AppDeflectionMessage | The application can use this variable to track deflections by specifying the message played when a caller disconnected their call. | ||||||||||||
| AppLastMilestone | The last milestone that the application achieved. | ||||||||||||
| AppStrikeoutMilestone | The last milestone that the application achieved before strikeout. | ||||||||||||
| AppBailoutMilestone | The last milestone that the application achieved before the caller bailed out to an agent. | ||||||||||||
| AppDeflectionMilestone | The last milestone that the application achieved before the caller was deflected. | ||||||||||||
| ScriptID | The ScriptID as reported by the routing engine. | ||||||||||||
| AppSelfHelpedMilestone | Used to contain a self help milestone. | ||||||||||||
| SdrTraceLevel | Enables users to set the recording level. This variable accepts the following values:
| ||||||||||||
| AppSessionType | The type of the session. The default value is inbound for inbound calls. Survey applications must use the value survey. | ||||||||||||
| EnableRouteCallRecording | Set to true or false to enable or disable call recording for routed calls in the Assisted Service phase. Leave blank to use platform defaults.
| ||||||||||||
| GmsCallbackServiceName | The GMS Callback Service name. | ||||||||||||
| GmsCallbackServiceID | The unique identifier that GMS assigns to a scheduled callback. | ||||||||||||
| survey_sOffer | Set by the Setup Survey block to specify if a survey was offered, setup, or rejected. | ||||||||||||
| survey_iAgentScore | Holds the user satisfaction score for the agent, if this question is asked by the survey. | ||||||||||||
| survey_iCompanyScore | Holds the user satisfaction score for the company, if this question is asked by the survey. | ||||||||||||
| survey_iCallScore | Holds the user satisfaction score for the overall call, if this question is asked by the survey. | ||||||||||||
| survey_iProductScore | Holds the user satisfaction score for the product, if this question is asked by the survey. | ||||||||||||
| survey_iRecommendScore | Holds the user's rating score (on a scale of 0-10) of the company, product, or service. Used to calculate Net Promoter Score (NPS). | ||||||||||||
| ApplicationRevisionSerialID | A read-only variable that increments by 1 each time an application is revised. | ||||||||||||
| ApplicationPath | The absolute path to the application. | ||||||||||||
| InteractionSource | The source of the interaction. For example, this value could be web (desktop and mobile browsers) or mobile (apps). | ||||||||||||
| ReferrerURL | The URL that the customer came from. | ||||||||||||
| UserAgent | The type of browser that the customer is using, e.g. Chrome, Mozilla, Opera, etc. | ||||||||||||
| UserAgentOS | The type of operating system that the customer is using, e.g. Windows, Mac, etc. | ||||||||||||
| Interaction | Details about the interaction, e.g. the interaction subject and type. | ||||||||||||
| Contact | Details about the customer contact (name, phone number, email address), stored as a JSON object. For example:
{"PhoneNumber":"1234","EmailAddress":"name@domain.com","FirstName":"John","LastName":"Doe"}
Designer can obtain contact information from the interaction call data or from other services in the Genesys Multicloud CX solution (if the contact details are not available in the interaction call data). | ||||||||||||
| DefaultPartition | The default partition used to provide access control in GIR. This variable can be overridden by settings in the Record block. | ||||||||||||
| AutoStopInteraction | (Digital only) Specifies whether or not the interaction is to be automatically terminated when the session ends.
| ||||||||||||
| ChatOfferVQ | The virtual queue that was queried for an Estimated Wait Time (EWT) to determine if chat is to be offered. | ||||||||||||
| FlowEntryCount | Total number of times (including this run) that the Designer application ran to process this interaction. | ||||||||||||
| ExpirationTime | Maximum time (in minutes) from when the interaction was first processed to keep the interaction alive. For more information, see Setting the ExpirationTime value. | ||||||||||||
| isResumedFromParking | This variable indicates how many times (if any) the interaction was parked. | ||||||||||||
| LanguageForBots | The default language to be used for bots. | ||||||||||||
| enableSSML | Set as true to enable the interpretation of Speech Synthesis Markup Language (SSML) tags in TTS (Text-to-Speech) prompts. For more information, see Speech Synthesis Markup Language.
| ||||||||||||
| removeSSMLInChat | Set as true to remove SSML tags from chat messages if an omnichannel application is using the same messages for both voice and chat channels. For more information, see Speech Synthesis Markup Language.
| ||||||||||||
| stream | This variable is used to implement workstream specific application logic. The valid values for this variable are dev, qa, uat, live, and live_b.
Note: Any applications using the stream UserData KVP must be updated to use this System Variable instead. |
Setting the MaxTime value
The MaxTime value represents the maximum length of time (in minutes) that an interaction session can remain active before being automatically terminated. The default setting is 240 minutes, but Genesys strongly recommends that you keep this number higher than the longest possible wait time your customers might experience. This is to prevent the session from being terminated before it is completed normally, such as in cases where a customer has requested an ASAP callback. Designer sees the initial call and the subsequent callback as a continuation of the same session, so if the MaxTime expires before the callback is made, that session is lost. (Scheduled callbacks are not affected, as they use a separate session for the callback.)
Recommendations for setting the MaxTime value:
- Use a value that is greater than the maximum wait time on your busiest day.
- Use a value that is also greater than the Callback Purge Time set for ASAP callbacks. (For more information about callback settings, see the Callback Settings Data Table.)
Setting the ExpirationTime value
This system variable is typically more relevant to chat scenarios. It differs from the MaxTime variable in that it specifies the duration of time (in minutes) to keep the interaction active, not the overall application session. Typically, incoming chat interactions are much shorter in duration than voice calls and are processed by multiple Designer applications, back-to-back, which means a single chat interaction can often be associated with multiple sessions.
During the Finalize phase, if Designer detects that an interaction has been active longer than the time specified by the ExpirationTime value, then Designer terminates both the interaction and the session. If the session terminates and the chat is not routed, it gets automatically re-queued, a new session starts, and so on. This could go on forever. Thus, when auto-stop logic is used by the application (set by the AutoStopInteraction system variable), the ExpirationTime system variable triggers Designer to terminate the interaction.
Recommendations for setting the ExpirationTime value:
- For chats, use a value that is greater than the maximum interaction time required when processing the chat with different applications or if the interaction is going to be looped within the same application.
VAR Metrics
Use the IVRProfileName variable (User Data Key: gsw-ivr-profile-name) to associate the application VAR metrics with an IVR Profile. Use a value of auto to auto-detect the IVR Profile.
Use the GVPTenantID variable (User Data Key: gvp-tenant-id) to associate the application VAR metrics with a tenant. Designer attaches the value to user data. Use a value of auto to auto-detect the tenant.
These variables are listed in the properties of blocks once they are defined.
Internal system variables
During an application session, Designer also adds certain internal system variables at various stages. These internal variables are recorded in Designer Analytics at the end of the application, along with other system and user-defined variables. Thus, it is possible to see new variables in Analytics that are not listed in the Initialize phase block.
Although these variables may appear in variable or call data objects in Session Detail Records (SDR), they are intended only for internal use by Designer and should not be used in blocks for driving application logic. These variables can change or be removed at any time, so attempting to use them in applications can affect application resiliency and cause unexpected behavior. This type of usage is not supported or recommended. If your business operations require new functionality, contact your Genesys representative.
Assigning Values to Variables
Designer lets you assign values to variables in different ways. These examples show a few of the methods you can use to assign different types of values to a variable, including a JSON value.
Example 1: Simple Assignment
The easiest (and recommended) way is to assign a value to a variable using the Assignments tab on the Assign Variables block.
Click Add Assignment to add an assignment slot to the block, then choose a variable from the Variable column. For the Expression, you can use the name of another variable whose value should be copied in to the Variable column, a literal value (for example, "Sales Channel"), or an expression whose value should be calculated first and the results assigned to the Variable.
You must use single quotes (' ') when specifying string values, but you can assign numeric values without quotes. Note that the varZipCode above is a string data type (the single quotes tell JavaScript to treat it as a string), but it contains only numbers. It's important to remember that JavaScript treats string and numeric data types differently. For example, 1 + 2 = 3, but ‘1’ + 2 = ‘12’.
JSON data (for example, varCustomerData) is typically retrieved from an external data source, but you can also form a JSON string in the application. JSON strings must be enclosed in brackets ( ) and should follow the rules and syntax for JSON strings as defined by JavaScript. Note also that variables can easily be used to form part of the JSON string (as represented by varCustIDFromCRM, in the example shown below).
The varCustomerPrompt above shows a simple string expression, with the different string segments linked together by a +. If used in a Play Message block, it will play “Hello Joe! Welcome to Genesys." It accesses a property of the varCustomerData object using the “.” notation and combines it with the welcome message.
Here is another example of how you could build a JSON expression. It contains mostly hard-coded strings, but also uses a variable to form part of the JSON string:
Example 2: Advanced Scripting
If your application requires you to go beyond simple assignments and use JavaScript constructs like loops or multiple nested conditions, you can use the Advanced Scripting tab, which allows you to compose valid ECMAScript or JavaScript.
To use this feature, you need a basic level of familiarity and understanding of ECMAScript syntax and rules. Any errors in the script can cause erratic behavior, so test your changes to make sure that your script works correctly.
In this example, the script sets the variable varOrdersPrompt to "3 Laptop bags, 2 Phone chargers, 1 Super rare fish". Here's how it works:
The sample script below first initializes JSON data in varOrderDetails so that it becomes an array of three JSON objects. Each JSON object has properties — item, quantity, backordered. The script then proceeds to loop through orders and forms a string to play back to the caller to notify them of their order status.
Note that this script uses variables in two scopes:
- A scope exclusive or local to this script itself (“i”). This variable remains available only while this script runs, and then it disappears.
- Top level variables that were defined in the Initialize phase — these remain available throughout this application flow, but not in any modules this application calls (such as varOrdersPrompt).
