The optional [User] section defines variables that are set from user input and are passed as parameters on the query string. You use these variables in other sections of your template, such as to select (filter) a different Id each run.
This topic contains the following sections:
For each name/value pair in this section:
The template cannot be processed without values being assigned to the entries in the [User] section. These values are passed as parameters on the query string (see Running a template).
Input variables can be used in the Output, Calculated and Filter sections of a template.
[User] UserID(Id) = "User ID to process."
This defines a user variable UserID of type Id. You then use the variable UserID in other sections of your template.
For example, in the Filter section, you could add the filter User = Equals(UserID) to filter on a specific user.
Once you define a variable in the [User] section, you set the value by passing it as a parameter on a query string, as shown above. In this case, the value of the UserId variable has been set to 123456.
[User] Radius(Distance,Feet) = "Marker's radius in feet"
This defines a user variable Radius of type Distance. The Distance type also has a unit of measure: Feet. Which unit of measure you can use depends on the specific data type. For most types, implied type conversions are straightforward. For example, you do not need to indicate how to convert between kilometers and miles.
Suppose that you want to fetch transactions by dates that are specified at run-time, so that you do not have to change the template each time. You can add a [User] section to define a variable for each run-time parameter. You can set this up with a few steps:
[Template] TemplateVersion = 1.0 TableID = FuelTransaction-1.0 TemplateName = ReadByDriver Intent = Retrieve OrderBy = PurchaseTime [User] Driver(Text) = "" ReportStart(Timestamp) = "" ReportEnd(Timestamp) = "" [Filter] PurchaseTime = Between(ReportStart,ReportEnd) DriverName = Equals(Driver) [Output] DriverName = Input.DriverName Account = Input.AccountNumber ...
What if you need a template that can find more than one driver by Id? You can use the In filter condition to specify the set of Ids against which TDE will find matches. Using this condition lets you add variables to your [User] section to transform the template into one that takes multiple Ids as run-time parameters:
The values to filter against can be specified as a dynamic collection of values using the Set or Array DataType and a comma-separated query string value:
[Template] TemplateVersion = 1.0 TableID = Driver-1.0 TemplateName = RetrieveDriverByIds Intent = Retrieve OrderBy = Input.Nickname [User] ExtIds(Set<Text>) = "" [Filter] Id(AcmeDriver) = In(ExtIds) [Output] Nickname = Input.Nickname EmployeeNo = Input.EmployeeNo ...
Using variables, you can dynamically set the units of measure (for any measurement Data types) and time zones used throughout your template.
For example, if your drivers work in different time zones, when you retrieve their HOS events over a period of time, you may prefer to retrieve the events in the driver’s local time zone. You can accomplish that by dynamically setting the time zone used throughout the template with a user variable.
When running the template, add the driver, preferred time zone, start, and end times to the query string:
Driver=12345&DriverTimeZone=CST&Start=10/1/2015 00:00:00&End=10/2/2015 23:59:59
In the template, define four user variables:
The order in which you define user variables matters, if you want to define one user variable using the definition of another one, as is the case with the Start and End variables: both use the DriverTimeZone variable to specify a time zone. In this case, the DriverTimeZone must be defined before Start and End.
[Template] TemplateVersion = 1.0 TableID = HosEvent-1.0 TemplateName = RetrieveHosEventInDriverLocalTime Intent = Retrieve Format = CSV OrderBy = Input.EventTime [User] Driver = "driver" DriverTimeZone = "timezone" Start(Timestamp,DriverTimeZone) = "start" End(Timestamp,DriverTimeZone) = "end" [Filter] DriverId(Ext) = Equals(Driver) EventTime = Between(Start,End) [Output] DriverId(Ext) = input.DriverId EventTime(DriverTimeZone) = Input.EventTime EventType = Input.EventType