Difference between revisions of "Variable Processor"

From SmartWiki
Jump to: navigation, search
m (Chin moved page Variable processor to Variable Processor without leaving a redirect: capitalizing title)
Line 1: Line 1:
 +
{{UnderConstruction}}
 +
 +
<!--
 
#REDIRECT [[The Musings of Chin - Correct Variable Processor Use]]
 
#REDIRECT [[The Musings of Chin - Correct Variable Processor Use]]
 +
-->
 +
 +
=Overview=
 +
The Variable Processor is the engine within SmartSimple that processes and replaces variable references (e.g. @firstname@) with actual values (e.g. John Doe) within templates and calculations. This allows you to configure a generic template or calculation to be translated and applied across multiple records.
 +
 +
A simple example of the concept of variable translation can be seen in the display of your name in the header menu of SmartSimple after having logged in. To achieve this the SmartSimple application would first require a generic web page template with a variable reference to ''user name'' in the header menu. When you log into SmartSimple the application processes the generic template and replaces the variable reference for ''user name'' with your actual name and the result is what you see in your browser.
 +
 +
=Configuration - Essentials=
 +
 +
==Areas of Use==
 +
*Email Templates
 +
*Custom Fields
 +
*Template Formulas
 +
*Workflows
 +
 +
==Basic Syntax==
 +
The most common use of the Variable Processor is to reference a field value. Variable references are denoted in general by a field name encapsulated by the @ symbol. The most basic form of variable is:
 +
 +
<code>@''fieldname''@</code>
 +
 +
Where ''fieldname'' is simply the name of a custom field or one of the pre-defined standard fields as listed in the appendix for each of the record types. This form is used when the field exists on the record that you are viewing. For example, if we are viewing a user profile and wish to reference that user's first name we can configure a variable '''@firstname@'''.
 +
 +
You can also reference information from other records by defining the record level of the field with the following syntax:
 +
 +
<code>@''record''.''fieldname''@</code>
 +
 +
Where ''record'' defines a different record that you wish to reference a field from. For example, if we are again viewing a user profile but wish 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 in order to reference information from the user's parent company we reference one level up using 'parent'.
 +
 +
Record levels can also be nested to refer to records that are multiple levels apart. For example, if we wish to reference the company name of the user that is currently logged in we can configure a variable '''@me.parent.name@'''. Here we see two records mentioned, the first for 'me' starts at the user currently logged in, and then 'parent' to traverse one level up. Another example of valid syntax could be '''@parent.parent.parent.''fieldname''@'''.
 +
 +
===Record Level===
 +
Record levels are used within a variable reference to define the record in question. The following are some examples that can be used 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.'
 +
 +
{| class="wikitable"
 +
|-
 +
! 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. The following are some examples that can be used 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'
 +
 +
{| class="wikitable"
 +
|-
 +
! 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()@
 +
|
 +
|-
 +
|}
 +
 +
{| class="wikitable"
 +
|-
 +
! 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 in order to explicitly specify the display of a date formatted field. For example, to always display the date in 'YYYY-MM-DD HH:MM am/pm' you can define a variable '''@year(''fieldname'')@-@month(''fieldname'')@-@day(''fieldname'')@ @hour(''fieldname'')@:@minute(''fieldname'')@ @ampm(''fieldname'')@'''.
 +
 +
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'
 +
 +
{| class="wikitable"
 +
|-
 +
! 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).
 +
 +
{| class="wikitable"
 +
|-
 +
! 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)@<br>
 +
@format(''fieldname'',decimal,<nowiki>''</nowiki>)@<br>
 +
@format(''fieldname'',percent,<nowiki>''</nowiki>)@
 +
|-
 +
|}
 +
 +
===Miscellaneous Variables===
 +
 +
<!--
 +
@now@
 +
@currentdate@
 +
@objemail@ (object email address)
 +
@SmartFields@ @SmartFields(fieldidlist)@ @SmartFieldsIncludeTab@ @SmartFieldsEdit@ (appears in edit mode)
 +
@lat@ @lng@
 +
-->
 +
 +
=Configuration - Advanced=
 +
 +
==Advanced Syntax==
 +
 +
===Record Level===
 +
Record levels are used within a variable reference to define the record in question. The following are some examples that can be used in a variable reference.
 +
 +
{| class="wikitable"
 +
|-
 +
! 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, 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 (logging in from multiple companies)
 +
| @sessioncompany.
 +
|
 +
|-
 +
|}
 +
 +
===Field Attributes===
 +
Specific attributes of a field can also be referenced. The following are some examples that can be used in a variable reference.
 +
 +
==Lists==
 +
 +
==Functions==
 +
 +
===Controls===
 +
 +
===Calculations===
 +
 +
===ReportProperty===
 +
 +
=Appendix=
 +
 +
==Standard Field Variable Names==
 +
 +
===User===
 +
<!--
 +
@inRole(rolename)@
 +
-->
 +
 +
===Company===
 +
 +
===UTA Level 1===
 +
 +
<!--
 +
@company. or @client.
 +
@person. or @people.
 +
-->
 +
 +
===UTA Level 2===
 +
 +
===UTA Level 3===
 +
 +
===Email Broadcast Templates===
 +
 +
===Workflow Email Templates===
 +
 +
=Recommended Reading=
 +
 +
<!--
 +
@rootcompanyid@
 +
@ssformtoken@ (security token) @ssformtoken.html@ (hidden input HTML with security token)
 +
@url@
 +
@now@
 +
@currentdate@
 +
@logourl@
 +
@primaryroleid@ (primary role when logged in, using prole parameter from login)
 +
@dateformat@ (user setting, used in scripting)
 +
@sstimezone@ (user setting)
 +
@ssget()@
 +
@object@ (from a transaction will go to the user/company depending on transaction type, can also use @parent@)
 +
@company. or @client. (for invoice to get company information)
 +
 +
 +
note: change record context to level
 +
-->

Revision as of 15:33, 13 October 2017

Template:UnderConstruction


Overview

The Variable Processor is the engine within SmartSimple that processes and replaces variable references (e.g. @firstname@) with actual values (e.g. John Doe) within templates and calculations. This allows you to configure a generic template or calculation to be translated and applied across multiple records.

A simple example of the concept of variable translation can be seen in the display of your name in the header menu of SmartSimple after having logged in. To achieve this the SmartSimple application would first require a generic web page template with a variable reference to user name in the header menu. When you log into SmartSimple the application processes the generic template and replaces the variable reference for user name with your actual name and the result is what you see in your browser.

Configuration - Essentials

Areas of Use

  • Email Templates
  • Custom Fields
  • Template Formulas
  • Workflows

Basic Syntax

The most common use of the Variable Processor is to reference a field value. Variable references are denoted in general by a field name encapsulated by the @ symbol. The most basic form of variable is: 

@fieldname@

Where fieldname is simply the name of a custom field or one of the pre-defined standard fields as listed in the appendix for each of the record types. This form is used when the field exists on the record that you are viewing. For example, if we are viewing a user profile and wish to reference that user's first name we can configure a variable @firstname@.

You can also reference information from other records by defining the record level of the field with the following syntax: 

@record.fieldname@

Where record defines a different record that you wish to reference a field from. For example, if we are again viewing a user profile but wish 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 in order to reference information from the user's parent company we reference one level up using 'parent'.

Record levels can also be nested to refer to records that are multiple levels apart. For example, if we wish to reference the company name of the user that is currently logged in we can configure a variable @me.parent.name@. Here we see two records mentioned, the first for 'me' starts at the user currently logged in, and then 'parent' to traverse one level up. Another example of valid syntax could be @parent.parent.parent.fieldname@.

Record Level

Record levels are used within a variable reference to define the record in question. The following are some examples that can be used 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. The following are some examples that can be used 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 in order to explicitly specify the display of a date formatted field. For example, to always display the date in 'YYYY-MM-DD HH:MM am/pm' you can define a variable @year(fieldname)@-@month(fieldname)@-@day(fieldname)@ @hour(fieldname)@:@minute(fieldname)@ @ampm(fieldname)@.

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

Configuration - Advanced

Advanced Syntax

Record Level

Record levels are used within a variable reference to define the record in question. The following are some examples that can be used 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, 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 (logging in from multiple companies) @sessioncompany.

Field Attributes

Specific attributes of a field can also be referenced. The following are some examples that can be used in a variable reference.

Lists

Functions

Controls

Calculations

ReportProperty

Appendix

Standard Field Variable Names

User

Company

UTA Level 1

UTA Level 2

UTA Level 3

Email Broadcast Templates

Workflow Email Templates

Recommended Reading

Retrieved from ‘https://wiki.smartsimple.com/index.php?title=Variable_Processor&oldid=31262’