Variables

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Designer User's Guide for version Current of Designer.

Learn how to use variables in Designer.

Related documentation:

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').
Important
The block properties page will indicate if single quotes are required.

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.

Important
User variables may not be initialized correctly if their value is set to one or more system variables in the Initialize phase itself. This phase should be used to declare variables, but their values should be assigned later using an Assign block if the value or the value expression involves a system variable.
Warning
You can delete a variable even if it is required by the application. Designer validates the application when you click Publish, at which time it checks for deleted variables.

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.

Des secure variables.png

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.

Warning
  • 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.

Des variables trace do not use.png


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.

Important
Do not update system variables in the Assisted Service phase while an asynchronous Start Treatment is running. Instead, update system variables before the Start Treatment starts or within the Self Service treatment itself.

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:
Access property Switch access code field
prefix Code
rtype Route Type
destination Destination Source
location Location Source
dnis DNIS Source
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:
  • 100 — Debug level and up. Currently, there are no Debug messages.
  • 200 — Standard level and up. This setting shows the existing blocks array in the SDR.
  • 300 — Important level and up. This setting filters out all blocks except those containing data that can change from call to call (such as the User Input block).
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.
  • If set to true, the interaction is automatically terminated just before the application session wraps up.
  • When set to auto (default), the application decides whether to stop the interaction or not based on the interaction media type.
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

Important
VAR action IDs are stripped of spaces and pipe characters (|). This includes implicit actions that are generated when a caller enters a shared module.

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.

Des assignvar ex1.png

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.

Important
Although the terms ECMAScript and JavaScript are used interchangeably throughout this Help, Designer technically supports ECMAScript and does not support JavaScript functions that are typically used for web-browser based applications, such as pop-up windows, alerts, and so on.

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:

Des assignvar json ex1.png

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.

Important
Advanced Scripting is an optional feature and might not be enabled on your system. To enable this functionality, contact Genesys.

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.

Warning
Use caution! Designer can check your script for syntax errors, but cannot validate it nor check for runtime errors that might occur when the script runs during a call.

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).
Des assignvar advanced ex2.png
Retrieved from "https://all.docs.genesys.com/DES/Current/Designer/Variables (2024-12-11 12:52:06)"
Comments or questions about this documentation? Contact us for support!