Overview
The Variable Processor serves as the core component of SmartSimple, responsible for processing and substituting variable references (e.g., @firstname@) with actual values (e.g., John Doe) within templates and calculations. This functionality enables the configuration of a generic template or calculation to be interpreted and applied across multiple records.
A straightforward illustration of the concept of variable translation can be observed in the display of your name in the header menu of SmartSimple following your login. To accomplish this, the SmartSimple application first requires a generic web page template that contains a variable reference to user name in the header menu. Upon logging into SmartSimple, the application processes the generic template and replaces the variable reference for user name with your actual name, resulting in the display you see in your browser.
Configuration - Essentials
Areas of Use
- Email Templates
- Custom Fields
- Template Formulas
- Workflows
Basic Syntax
The primary application of the Variable Processor involves referencing a field value. Variable references are generally denoted by a field name enclosed by the @ symbol. The most fundamental form of a variable is:
@fieldname@
Here, fieldname represents the name of a custom field or one of the pre-defined standard fields as outlined in the appendix for each record type. This form is utilized when the field exists on the record currently being viewed. For instance, if we are examining a user profile and wish to reference that user's first name, we can configure a variable @firstname@.
Record Level
It is also possible to reference information from other records by specifying the record level of the field using the following syntax:
@record.fieldname@
In this case, record indicates a different record from which you wish to reference a field. For example, if we are once again viewing a user profile but want to reference the company name of that user, we can configure a variable @parent.name@. In this example, we are currently on a user profile, and to reference information from the user's parent company, we refer one level up using 'parent'.
Record levels can also be nested to refer to records that are multiple levels apart. For instance, if we wish to reference the company name of the user currently logged in, we can configure a variable @me.parent.name@. Here, we observe two records mentioned: the first for 'me' pertains to the user presently logged in, and then 'parent' is used to traverse one level up. Another example of valid syntax could be @parent.parent.parent.fieldname@.
The following are examples that can be utilized in a variable reference. For these examples, assume the following scenario:
- You are logged in as 'SmartSimple Support'
- Your parent company is the 'Customer Support' department
- The root company of the instance is 'SmartSimple Software Inc.'
| Syntax | Description | Format | Example |
|---|---|---|---|
| parent | References the parent of the current record being viewed. | @parent.fieldname@ | @parent.name@ -> Customer Support |
| me | References the user currently logged in. | @me.fieldname@ | @me.email@ -> support@smartsimple.com |
| level1/level2/level3 | Specific within the area of UTA template formulas. This is required to explicitly denote the record level in a formula since multiple levels can be referenced. | @level[1/2/3].fieldname@ | @level2.Grant Name@ = "@level1.name"<end> is an example of a UTA Level 2 template formula that copies the Level 1 name standard field value to a Level 2 Grant Name custom field. |
| rootcompany | References the root company of the instance. | @rootcompany.fieldname@ | @rootcompany.name@ -> SmartSimple Software Inc. |
Field Attributes
Specific attributes of a field can also be referenced to obtain different information about that field. The general syntax for this is:
@record.fieldname.attribute@
The following are examples that can be utilized in a variable reference. For these examples, assume the following scenario:
- A custom field with ID '132547', named 'Gender' that is configured as a Select One - Combo Box field with options '1=Male;2=Female;'
- A custom field with ID '243657', named 'Text' that is configured as a Text Box - Single Line field with caption 'Enter Text Here'
- A record where we have entered Gender as male and Text as 'Lorem Ipsum'
| Syntax | Description | Format | Example |
|---|---|---|---|
| value | Returns the stored value of a field. | @fieldname.value@ | @Gender.value@ -> 1 |
| combovalue | Specific to Select One - Combo Box custom field type. Returns the stored value of a field. | @fieldname.combovalue@ | @Gender.combovalue@ -> 1 |
| length | Returns the character length of the stored value of a field. Commonly used to check whether a field is empty by checking for a length of 0. | @fieldname.length@ | @Text.length@ -> 11 |
| id | Returns the custom field ID of a custom field. | @fieldname.id@ | @Gender.id@ -> 132547 |
| caption | Returns the caption of the custom field. Commonly used when creating custom forms with the Display Only – Web Page View custom field type. | @fieldname.caption@ | @Text.caption@ -> Enter Text Here |
| numoffiles | Specific to Link - Multiple Files custom field type. Returns the total number of files uploaded to the field. | @fieldname.numoffiles@ | |
| numofpages | Specific to Link - Single File and Link - Multiple Files custom field type. Returns the total number of pages within files uploaded to the field. | @fieldname.numofpages@ | |
| files | @fieldname.files@ | ||
| uploadlink | @fieldname.uploadlink@ | ||
| compressedfiles | @fieldname.compressedfiles@ | ||
| compressedlink | @fieldname.compressedlink@ | ||
| filenames()??? | @fieldname.filenames()@ |
| Syntax | Description | Format | Example |
|---|---|---|---|
| html | @xml.fieldname.section.html@ / @grid.fieldname.html@ | ||
| xml | @xml.fieldname.section. | ||
| xmlpre | Pre-processed variables | ||
| xmlvalue | @xml.fieldname.xmlvalue@ | ||
| grid | Inline data grid | @grid.fieldname. |
Functions
Date Formatting
The following syntax is available to explicitly specify the display format of a date field. For instance, to consistently display the date in 'YYYY-MM-DD HH:MM am/pm', you may define a variable
@year(fieldname)@-@month(fieldname)@-@day(fieldname)@ @hour(fieldname)@:@minute(fieldname)@ @ampm(fieldname)@
The following are examples that can be utilized in a variable reference. For these examples, assume the following scenario:
- A record where we have entered the standard field Start Date as '2017-01-02' at '22:52'
| Syntax | Description | Example | |
|---|---|---|---|
| year | Specific to date formatted fields. Returns the full year. | @year(fieldname)@ | @year(fullstartdate)@ -> 2017 |
| month | Specific to date formatted fields. Returns the month number. | @month(fieldname)@ | @month(fullstartdate)@ -> 01 |
| monthname | Specific to date formatted fields. Returns the month name. | @monthname(fieldname)@ | @monthname(fullstartdate)@ -> January |
| day | Specific to date formatted fields. Returns the day. | @day(fieldname)@ | @day(fullstartdate)@ -> 02 |
| dayweek | Specific to date formatted fields. Returns the day of the week. | @dayweek(fieldname)@ | @dayweek(fullstartdate)@ -> Monday |
| hour | Specific to date formatted fields. Returns the 12-hour format of hour. | @hour(fieldname)@ | @hour(fullstartdate)@ -> 10 |
| hour24 | Specific to date formatted fields. Returns the 24-hour format of hour. | @hour24(fieldname)@ | @hour24(fullstartdate)@ -> 22 |
| minute | Specific to date formatted fields. Returns the minute. | @minute(fieldname)@ | @minute(fullstartdate)@ -> 52 |
| ampm | Specific to date formatted fields. Returns the am/pm value of the 12-hour time. | @ampm(fieldname)@ | @ampm(fullstartdate)@ -> pm |
| date | Specific to date formatted fields. Returns the date ???. | @date(fieldname)@ | @date(fullstartdate)@ -> 2017-01-02 ??? |
| datetime | Specific to date formatted fields. Returns the date time ???. | @datetime(fieldname)@ | @datetime(fullstartdate) -> 2017-01-02 22:52 ??? |
| formatdate | Returns the date formatted to the current user preference | @fieldname.formatdate@ ??? |
Number Formatting
The following syntax is available in order to format a numeric field value (e.g. currency, percent formats).
| Syntax | Description | Example |
|---|---|---|
| format | Specific to number formatted fields. Returns the specified formatted value of the number. Possible format options include currency, decimal, and percent | @format(fieldname,currency,us)@ @format(fieldname,decimal,'')@ @format(fieldname,percent,'')@ |
Miscellaneous Variables
Record Level
Record levels are utilized within a variable reference to specify the record in question.
Below are several examples that may be employed in a variable reference.
| Syntax | Description | Format | Example |
|---|---|---|---|
| system | References global system variables. | @system.variablename@ | |
| system2 | References global system variables. | @system2.variablename@ | |
| system.library | @system.library | ||
| levelone / leveltwo | Specific to contact, company, or transaction associations to a Level 1 or Level 2 (e.g., Level 1 Contacts association). References the associated Level 1 or Level 2 record. | @levelone.fieldname@ | |
| company / contact | Specific to contact and company associations to a Level 1 or Level 2 (e.g., Level 1 Contacts association). References the company or contact record from the association (e.g., L1 or L2 multiple contacts). | @company.name@ | @company.name@ -> SmartSimple Software Inc. |
| linkparent | References | @linkparent.fieldname@ | |
| sessioncompany | References your current association company (in instances of logging in from multiple companies). | @sessioncompany. |
Field Attributes
Specific attributes of a field may also be referenced. Below are several examples that can be utilized in a variable reference.