Variables

Variables store information entered into Discovery Questions, Stage Questions, Value Assumptions and Calculations made from the aforementioned elements. Spotlight.ai creates variables with formulas for ROI, Payback, Benefits and many other system calculations. Variables, whether populated by user's input or a calculation, can be used in Slide Templates (Google Slides and Microsoft PowerPoint) similar to a form letter with a mail merge.

Over time, there will be many variables so it’s important to have a good naming convention for them and to provide clear descriptions. Your future self or others who inherit the responsibility for configuration will thank you.

As a best practice, we recommend adding prefixes to the names of each variable followed by camel case so you can understand where the variable gets its information:

Discovery Questions - dq. Examples: dqNumFTEs, dqPercentComplete
Stage Questions - sq. Examples: sqBudgetStatus, sqChampionIdentification
Conditional Formulas - cn. Examples: cnCompetitorInAccount, cnHasBudget
Benefit Subtotals - s. Examples: sProductivityGainsSecurity, sProductivityGainsDevelopers
Formulas - f. Examples: fHoursPerYearWorked, fSavingsWithX
Value Assumptions - va. Examples: vaHoursSaved, vaPercentTimeSaved
Success Criteria - sc. Examples: scChampionQualified, scEBQualified
Google Slides - gs. Example: gsHoursSaved
Powerpoint - ppt. Example: pptHoursSaved
System-generated variables begin with c

In the examples above, the case-sensitive name of the variables are detailed and conform the valid JavaScript variable naming rules. Adding details to the name helps differentiate variables from one another removing ambiguity. If you want to use contractions, be consistent so someone could guess the name of a variable. For example:

A formula that calculates a benefit for 3 years -> fBenefit3Y
Benefits for year 2 -> fBenefitY2
Averages -> dqAvgSalesCycle
Percentages -> dqPercentUsed
Number of -> dqNumWidgets

Variables can be renamed in Spotlight.ai's Administration -> Variables page at any time and all dependent formulas that use those variables will be updated. Outputs like Google Slides or Microsoft PowerPoint have to be manually updated if your templates use a variable name that is changed.

Types

Each variable has a type:

Array - for Spotlight internal use only
Checkmark - expressed as a circular checkbox to express a boolean condition. Used for condition formulas. These are similar to Yes/No except that only Yes/No can express a null value (neither item selected).
Currency - a number displayed with a currency symbol. The currency is read from Salesforce.
Date - expressed as an input field with a date picker. It’s rare to use these in value discovery but they are common in sales qualification (Stage Activity Questions).
Duration - a measurement of time. Avoid using this type and use Number instead. Specify the units in the associated question.
Integer - be careful when dividing integers as the expectation is for the result to be an integer.
Number - a number that can have decimal places.
Percentage - the value is stored as a number but expressed in the UI as a percentage. For example, 50% is stored as 0.5.
Range - a value from 0 to 6 expressed in the UI as a slider control. These are less clear than defining a single select picklist with values such as "High", "Medium" and "Low".
Rich Text - a text field that can contain basic HTML and CSS for formatting. Currently, formatting can only be done using formulas. In release 3.0, there will be Rich Text inputs as well that have a small toolbar above the field when it has focus. This will allow basic formatting of the font style as well as ordered and unordered (bulleted) lists.
Text - basic text input.
Yes/No - stores a boolean value expressed using radio buttons. A null value is displayed with neither radio button selected. Conditional variables are always Yes/No or Checkbox.
Dropdowns - each single or multiselect dropdown defined is treated as a variable Type so that several variables can share the same dropdown. Each dropdown item has .name, .key, and .value property. Keys should be lowercase / snake case. They cannot be changed later so make them simple but informative. Keys also need to follow JavaScript naming rules so they cannot start with a digit or include special characters.

Default Values

When a variable is defined with a default value, if no value is entered by the user, the default value is used for formulas and outputs. Default values are displayed as an input with an arrow in a circle pointing to the input field. Hovering over the icon displays the default value. In the near future, the default value will be displayed as an input placeholder. In general, avoid adding these to Stage Activities because it will reduce the effectiveness of the Sales Qualification process.

Descriptions

Over time, there will be many variables and they’ll be used for several purposes. Building on the prefix, it is a best practice to add a detailed description to the variable. For example, all question variables should have a Description that starts with “Question: “ followed by the text of the question. This makes it very easy to search for variables that are for questions as well as specific questions when you are working in the formula editor. Other Description prefixes:

Condition:
Assumption:
Formula:
Subtotal:
Success Criteria:

Formulas

Formulas are created using Apache JEXL syntax. Not all features of JEXL (functions and multiline literals for example) are available. Commonly used formula operators appear as buttons above the formula editor field. Ternary expressions are very important in Spotlight.ai so be sure to brush up on these. JEXL follows JavaScript’s order of operations (multiplication is processed before addition for example). Avoid using unnecessary parentheses in your expressions as it will make formulas harder to read and understand; only use them when they are necessary.

One of the most common types of formulas in Spotlight.ai is for Conditions. These are of Type Yes/No or Checkbox and evaluate to true or false. You can reuse existing conditional variables. For example:

not cnHasValue will return false if cnHasValue is true.

Variables associated with a multiselect are stored as arrays. You can write formula to evaluate whether certain items in the list were selected or not selected. For example:

'value' =~ dqMyMultiselect.key will be true if one of the items selected for the variable qaMyMultiselect has a key of “value”.
'value' !~ dqMyMultiselect.key will be false if one of the items selected for the variable dqMyMultiselect has a key of “value”.

Do not use the eq operator for multiselect lists as the expression will always be false. This operator can be safely used on single-select lists.

Example of incorrect usage if qaMyMultiSelect is a multiselect

'something' eq dqMyMultiSelect.key

Correct usage:

(('stream' =~ dqMyMultiSelect.key) and ('edge' !~ dqMySecondMultiSelect.key))

Example of finding if a contact was selected within the Contact Select field

The Contact Select object is a special use case in Spotlight.ai. If a value was not selected, then it is considered empty, and we don't need to query its key. All we have to do is to check if it is equal to null (for empty field) or not equal to null (for populated field) .

this will return true if a champion was selected:
sqChampionName != null

Using a formula to automate selections in a multiselect

There are situations where you need formulas to select items in a multiselect based on other inputs. Spotlight supports anonymous functions in expressions to do this.

Consider a formula variable called fDeliverable that has a type associated with the multiselect picklist Deliverables which has options "SOW" and "BC" (with keys "sow" and "bc" respectively). The formula for fDeliverable could be:

x->x.set(
  dqCreateBusinessCase ? 'bc' : null,
  dqSOWNeeded ? 'sow' : null
)

This defines an anonymous function that will evaluate the input variable dqCreateBusinessCase. If its answer is true (Yes or checked), then the key 'bc' is included. Additionally, if the variable dqSOWNeeded is true, it adds the key 'sow' to the picklist. Based on changes to the questions associated with dqCreateBusinessCase and dqSOWNeeded, the multiselect for fDeliverable will check the appropriate items in the list.