Token Reference
A Logi "token" is a place-holder variable that represents a value and is resolved at runtime. They're essential for creating dynamic visualizations and reports and are discussed in depth in this topic.
- About Tokens
- "Nesting" Tokens
- Token Types
- @Function Tokens
- @Date Tokens
- File Upload Tokens
- Other Special Tokens
For information about functions and operators, see Intrinsic Functions and Operators.
For information about special query string parameters, see Query String Parameter Reference.
About Tokens
Tokens act as variables in Logi applications and are the primary means of accessing the values of data, request and session variables, cookies, constants, and more. They're resolved into their values at runtime and inserted into the HTML generated by the Logi engine.
Tokens take this general format: @<TokenType>.<Identifier>~ and here are some examples:
- @Data.CustomerID~
- @Request.StartDate~
- @Function.UserName~
They must start with the @ symbol and end with the ~ (tilde) symbol, and they're case-sensitive. That bears repeating as developers typically run afoul of these two things: tokens must end with a ~ and they're case-sensitive.
@Data.CustomerID~ does not equal @Data.customerid~
Tokens can be used in many, but not all, element attributes to provide a dynamic value. Here are three examples of tokens in action:
1. In the example above, a token is used to provide part of a Label element Caption. At run time, the real server name will be substituted for the token. The output will look like this:
My server name is: MyTestServer
Tokens are extremely literal and are "data type neutral". For instance, in the above example, even though the server name is a string, there is no need to concatenate the "My server name is:" part of the caption (using + or & symbols) and the token.
2. As mentioned earlier, tokens are case-sensitive. In the example above, a Data token is used to represent the value in the ProductID column of each row of data in the datalayer. The spelling and capitalization of the column name in the token must exactly match that of the column name in the datalayer.
3. In our final example, shown above, a token is used in a Division element's Condition attribute. This attribute controls whether or not the Division, and all its child elements, are displayed: if the attribute evaluates to True, it's shown; if it evaluates to False, the element is hidden. A token can be used in this attribute in a formula that evaluates to True or False. More information is available about this in Work with Conditions.
The example uses a Request-type token, which represents data either POSTed by an HTML form or values from parameters in the query string used to call reports. Therefore, if the URL for this report was:
http://localhost/helloworld/rdPage.aspx?&rdReport=Default&Mode=1
then the Division element would be shown. These URLs:
http://localhost/helloworld/rdPage.aspx?&rdReport=Default&Mode=2
http://localhost/helloworld/rdPage.aspx?&rdReport=Default
would cause the Division element to not be shown. If the Mode parameter in the query string is non-existent, as in the third URL above, then the token is empty and the formula evaluates to False.
When you're comparing a token to a string value, be sure to surround the token and the string in quotation marks, as shown in the second set of attributes above.
Beginning in v11.0.43, Logi Studio includes a token validator feature which will display an "Invalid Token" warning if it detects a malformed token (usually a missing tilde) in an element attribute. Click the warning image to be taken to the offending token in the report definition.
Logi Studio also includes an "Intelligent Token Completion" feature that makes it easy to enter tokens in attribute values, thus avoiding spelling and case-related errors. For more information, see the Intelligent Token Completion Feature section of Use Studio 11.
"Nesting" Tokens
Because the token is a placeholder that gets resolved at runtime, it's possible to make tokens themselves dynamic. This is done by making part of the token identifier itself a token. Consider this token construction:
@Request.@Local.VarName~~
Notice that it has two @ signs and two tildes. For clarity in understanding how it's processed, imagine there are parenthesis in there, like this:
@Request.(@Local.VarName~)~
As you can probably now guess, when the report runs, the "inner token" (inside the parenthesis) is resolved first, then the "outer token", which now includes the literal value of the inner token as its identifier. So, for example, if:
- A Local Data element returns data in a column named VarName, value = "Mode", and
- A Request variable exists named Mode, with a value of "Standard"
Then the token @Request.@Local.VarName~~ would resolve to "Standard".
Limitations
Nesting only works with Request, Local, Data, and Constant tokens, and only one level of nested tokens will be resolved, so this won't work:
NO: @Request.@Local.@Local.VarName~~~
You may find that it's possible to nest the token type as well and even insert literal text into the token and make it work, but those combinations are not supported officially and may break from one Info version to the next - proceed down that path at your own risk.
Token Types
The following tokens types are available in Logi reporting products:
| Token Type | Description |
|---|---|
| @Application | Represent values set in the Application object, either in the Web.config file or in an integrated .NET application. These values are for global variables that span all instances of the application. Format: @Application.<session param ID> Example: @Application.LogFileFolder~ |
@Chart | Represents a data value from the child datalayer of a Chart or Chart Canvas element. Format: @Chart.<column name>~ Example: @Chart.OrderDate~ |
| @Compare | Represents the True or False result of a Compare Filter evaluation. (v11.0.127+) Not available in Logi Report. |
@Constant | Represents the value of a user-defined constant, as defined in the _Settings definition in the Constant element. Format: @Constant.<Name Attribute>~ Example: @Constant.CompanyName~ |
@Cookie | Represents the value of a cookie. Cookies can be set in Logi applications using the Save In Cookie attribute of certain Input elements or, in Logi Info, by using the Set Cookie Vars procedure element. Format: @Cookie.<Input Element ID>~ Example: @Cookie.Order~ |
@Data | Represents the data value from the child datalayer of an element, such as a Data Table, that is not a chart. Format: @Data.<Column Name>~ Example: @Data.CustomerID~ |
@Date | Represents relative dates for reports and report scheduling (see Date Identifiers list below). Format: @Date.<date identifier>~ Example: @Date.Yesterday~ |
| @FileUpload | Returns information in a procedure task about a file upload process (see File Upload Tokens, below). |
@Function | Represents the value of predefined functions (see Function Identifiers below). Format: @Function.<function name>~ Example: @Function.DateTime~ |
@Heatmap | Represents a data value from the child datalayer of a Heat Map element (deprecated in v11.0.727). Format: @Heatmap.<column_name >~ Example: @Heatmap.StoreSales~ |
@Input | Input parameter variable, used inside external JavaScript files. Not available in Logi Report. Format: @Input.<value ID>~ Example: @Input.FileName~ |
| @Local | Represents a data value from the first row of the child datalayer of a Local Data element (see Introducing Datalayers). Local data is accessible anywhere within the report definition. Note that child elements of this datalayer, such as a Calculated Column or Condition Filter, reference the data with @Data tokens. Format: @Local.<value ID>~ Example: @Local.ReportTitle~ |
| @Measure | Represents the value of XOLAP measures; used only in the XOLAP Formula attribute of the XOLAP Calculated Measure element. (v10.2.224+) Format: @Measure.[<measure name>]~ Example: @Measure.[Sales Amount]~ |
@Procedure | Represents results of operations by Process task procedures, including datasource interactions, file system and email operations, and associated error messages (see Special Identifiers below). Not available in Logi Report. Format: @Procedure.<procedure ID>.<value ID>~ Example: @Procedure.GetTaxes.SalesTax~ |
| @Repeat | Represents a data value from the child datalayer of a Repeat Elements element. (v11.1.033+) Format: @Repeat.<Column Name>~ Example: @Repeat.data_type~ |
@Request | Represents values supplied in a URL's query string and in Link Parameters, and the values of User Input elements POSTed by an HTML form. Format: @Request.<request variable name>~ Example: @Request.EmployeeID~ |
@Session | Represents the values of the application's Session variables, which are unique for each user session. Format: @Session.<session param ID> Example: @Session.SessionID~ |
@SingleQuote | A token prefix that provides special processing for other tokens. Prefix a token with @SingleQuote to wrap its values in single quotes. Used primarily to put single quotes around a comma-separated string of values, so they can be used in SQL queries. For example, values before: 'Red, White, Blue' and after: 'Red','White','Blue'. Cannot be used with @Data, @Chart and @Heatmap tokens. Format: @SingleQuote.<token>.<identifier>~ Example: @SingleQuote.Request.MyElementID~ |
@Summary | Deprecated. No longer a valid token. |
@Function Tokens
The identifiers listed in the table below are used with the @Function token. For example, to return the current date and time, use @Function.DateTime~.
Token | Resolves To |
| @Function.AppPhysicalPath | The complete physical path of the application's virtual directory on the web server. Example: C:\inetpub\wwwroot\MyLogiApp |
| @Function.AppCachePath | The physical path of the application's rdDataCache folder on the web server. Example: C:\inetpub\wwwroot\MyLogiApp\rdDataCache |
| @Function.AppDownloadPath | The physical path of the application's rdDownload folder on the web server. Example: C:\inetpub\wwwroot\MyLogiApp\rdDownload |
| @Function.AppVirtualPath | The HTTP Request.Path string. |
| @Function.Browser | The HTTP Request.Browser string. |
| @Function.BrowserDecimalChar | The client browser's decimal character. |
| @Function.BrowserMajorVersion | The HTTP Request.Browser.MajorVersion string. |
| @Function.BrowserMinorVersion | The HTTP Request.Browser.MinorVersion string. |
| @Function.BrowserThousandsSeparatorChar | The client browser's thousand separator character. |
| @Function.BrowserUserAgent | The HTTP Request.UserAgent string. |
| @Function.BrowserVersion | The HTTP Request.Browser.Version string. |
@Function.Date | The current web server date as a short date string. |
@Function.DateTime | The current web server date and time as a general date string. |
| @Function.ErrorDataLayerID | When the If Data Error element is processed, provides the element ID of the datalayer that encountered the error. (v10.0.319) |
| @Function.FileUpload | The information in a procedure task about a file upload process. |
| @Function.FUID | A Functional Unique Identifier string, a unique 16-byte identifier used in Windows Portable Devices. |
@Function.GUID | A random Globally Unique Identifier string. This function is useful for creating unique filenames. |
| @Function.HostAddress | The IP address of the client (browser) computer. |
| @Function.InstanceID | The Instance ID value of a Dashboard Panel, in dashboards that have Multiple Instances set to True. (v10.0.337) |
| @Function.LastErrorMessage | The last error message string for any process task executed in the current session. |
| @Function.PageCount | The number of data table pages. Only valid when Interactive Paging or Printable Paging elements are in use. |
| @Function.PageNumber | The current data table page number. Only valid when Interactive Paging or Printable Paging elements are in use. |
| @Function.QueryString | The entire query string (everything after the "?"). |
| @Function.Referer | The complete URL of the calling web page. |
| @Function.RowNumber | The current data table row number. |
| @Function.ServerName | The name of the web server. E.g.: localhost |
| @Function.SessionID | The current web server session ID. |
| @Function.TimeUtc | The current web server time, translated to UTC (Greenwich Mean Time) time, in 24-hour format, as hh:mm:ss |
| @Function.UserCulture | The browser's primary language string. |
@Function.UserID | The current, logged-in user ID or name, when Logi Security is in use. See Introduction to Logi Security 10. |
| @Function.UserRights | A comma-delimited list of the current, logged-in user's security rights, when Logi Security is in use. See Introduction to Logi Security 10. |
| @Function.UserRoles | A comma-delimited list of the current, logged-in user's security roles, when Logi Security is in use. See Introduction to Logi Security 10. |
@Date Tokens
The token identifiers listed in the table below all deal with dates. For example, to return yesterday's date, enter @Date.Yesterday~.
Dates are expressed by default in the yyyy-M-d format, which does not include leading zeros for single-digit day or month values. Examples: April 1st = "2009-4-1", April 25th = "2009-4-25", October 31st = "2009-10-31".
If needed, you can override this default format by specifying a new format in the Globalization element's Default Input Date Reformat attribute. The Default Input Date Reformat attribute ensures that dates entered by the user are formatted identically to dates returned from @Date tokens. This is especially useful if you are using the @Date tokens with the Validation.Date element.
The Globalization element can be added in the _Settings definition.
To work with the @Date.FiscalQuarter~ and @Date.FiscalYear~ tokens, use the Globalization element to set the first day of the fiscal year.
@Date.TodayUtc~ returns the UTC (Greenwich Mean Time) date.
The Time Period Columns element can also be used to parse specific date parts out of @Date token values.
@Date Token Identifiers | |||
Today | ThisWeekStart | ThisQuarterStart | ThisFiscalQuarterStart |
TodayUtc | ThisWeekEnd | ThisQuarterEnd | ThisFiscalQuarterEnd |
Yesterday | NextWeekStart | NextQuarterStart | NextFiscalQuarterStart |
Tomorrow | NextWeekEnd | NextQuarterEnd | NextFiscalQuarterEnd |
10DaysAgo | LastWeekStart | LastQuarterStart | LastFiscalQuarterStart |
30DaysAgo | LastWeekEnd | LastQuarterEnd | LastFiscalQuarterEnd |
60DaysAgo |
| ||
90DaysAgo | ThisMonthStart | ThisYearStart | ThisFiscalYearStart |
180DaysAgo* | ThisMonthEnd | ThisYearEnd | ThisFiscalYearEnd |
365DaysAgo | NextMonthStart | NextYearStart | NextFiscalYearStart |
| NextMonthEnd | NextYearEnd | NextFiscalYearEnd | |
| LastMonthStart | LastYearStart | LastFiscalYearStart | |
| LastMonthEnd | LastYearEnd | LastFiscalYearStart | |
* introduced in v11.4.046
File Upload Tokens
A file upload is a two-step operation, as follows:
- An Input File Upload element is used in a report definition to receive the file and path information for the file to be uploaded and it passes this information to a process task when the report is submitted.
- The task uses a Save File Upload procedure to save the uploaded file.
Two different types of tokens are used to return the data from the steps in the upload operation. Due to the nature of the
upload protocol, the values in the tokens are provided after the upload has already occurred. For more information, see the DevNet topic Upload Files.
Token | Resolves To |
| @FileUpload.UploadFileName~ | The file name and extension entered in the Input File Upload element by the user, without any path information. |
@FileUpload.UploadFileExtension~ | The file extension of the file name entered in the Input File Upload element. |
@Procedure.myProcedureID. | The file name and extension of the uploaded file. |
@Procedure.myProcedureID. | The file extension of the uploaded file. |
@Procedure.myProcedureID. | The MIME type or content type string of the uploaded file. |
@Procedure.myProcedureID. | The size of the uploaded file, in bytes. |
Other Special Tokens
These tokens are used for special purposes:
Token | Resolves To |
@Chart.rdCrosstabColumn-n~ | A specific datalayer column value, in a crosstab chart, where n equals the index, beginning with 1, of the column. |
@Chart.rdExtraColumnID~ | References different parts of the data (such as bar segments) when using an Extra Data Column element. Useful in determining which bar segment was clicked, for example. This token is only available for Classic static XY-type charts, not animated or Chart Canvas charts. |
@Data.rdCrosstabColumn~ | The crosstab column header. |
@Data.rdCrosstabValue~ | The crosstab row value. |
@Data.rdCrosstabValCount~ | The number of rows that were used to calculate a crosstab row value. |
@Data.rdSalesforceTable~ | A list of table names returned from a LIST TABLES query to Salesforce.com. |
@Data.rdSalesforceField~ | A list of field names returned from a LIST <tablename> query to Salesforce.com. |
@Procedure.myProcedureID.ColumnName~ | The data returned in the first row for the named column after Procedure.SQL executes. The element's SQL Return Type attribute must be set to FirstRow. |
@Procedure.myProcedureID.ErrorMessage~ | The last error message string for the procedure with the specified ID. |
@Procedure.myProcedureID.MethodName~ | The data returned from an external web service after Procedure.Web Service executes. The Web Service Method element used in the procedure must have its Return Type attribute set to String. |
@Procedure.myProcedureID.rdReturnValue~ | The value of the stored procedure's Return Value, if any, after Procedure.SP executes. |
@Procedure.myProcedureID.Stored ProcedureOutputParamID~ | The data in an SP output parameter with the specified ID, after Procedure.SP executes. |
@Procedure.RowsAffected~ | The number of rows affected by an INSERT, UPDATE, or DELETE statement, after Procedure.SQL executes. Procedure.SQL element's SQL Return Type attribute must be set to RowsAffected. |
@Request.rdReportFormat~ | Sets/gets the exported report format as one of: PDF, NativeExcel, NativeWord, CSV, HtmlExport, HtmlEmail, Excel, Word, XML, or GoogleSpreadsheet. Doesn't exist (is null) for reports in browser. |
@Session.SessionID~ | The current session ID. |
@Session.rdLastErrorLogFilename~ | The error log file name, in the application's rdErrorLog folder, when error logging is enabled. |