frevvo Latest - This documentation is for frevvo v10.2 v10.2 is a Cloud Only release. Not for you? Earlier documentation is available too.

Skip to end of metadata
Go to start of metadata

Capturing dates and time accurately is important because frevvo forms and workflows are designed to be used anywhere in the world, streamlining our customer's business processes. This chapter will consolidate information from several other documentation chapters related to working with dates and times in frevvo.

Palette Controls

Date, Time, and Date/Time Controls

The date control allows the user to enter a date, time, or date/time combo. The designer can choose from a variety of formats for each type.

Designers can add a date picker via the Style Properties tab. 

  • The Date control denotes a day and has no dependencies on time zone.
  • The Time control denotes the time of the day and has no dependencies on time zones or offsets. It will not shift based on whether or not Daylight Savings Time is observed in a time zone.
  • The Date/Time control relies on the time zone of the browser. The time portion will be calculated based on the date and whether or not Daylight Savings Time is observed in that time zone. The Date/Time control type is meant to represent a point in time, so certain functions in the Visual Rule Builder (year, month, day, hour, minute) are not available on this control type. 

    If the form cannot infer the browser time zone, the Date/Time control will display in UTC.

For example, the time 5:00 PM is entered into a Time control and the date 2/4/2020 plus 5:00 PM into a Date/Time control by a user located in the America/New_York (Eastern Standard Time). When the submission is viewed in the EST time zone, the Time Control displays 5:00 PM. This value will not change. The time portion of the Date/Time control also displays 5:00 PM, because it takes on the timezone of the browser (EST) and it is not further adjusted because Daylight Savings Time is not observed in EST on February 4th.

If the submission is viewed in Tijuana (Pacific Standard Time), the Time Control will display 5:00 PM as it did in EST, since it has no dependency on time zone. However, the Time portion of the Date/Time control will show 2:00 PM because it will be adjusted by the browser time zone to PST. 

Business Rules can be applied to the Date/Time control in all variations. See the Rules Examples chapter containing numerous examples.

Please review the Time Zone documentation to understand how Time Zones work when initializing date, time and date/time controls using business rules and _data.

Date, Time and Date/Time Submission Values

frevvo saves Date and Time control values in the submission xml document exactly as entered, but converted to ISO format. These values will display as entered, regardless of viewer's time zone, when the submission or workflow step is viewed.

frevvo saves Date/Time control values in the submission document in Coordinated Universal Time (UTC), also in ISO format. The indicator "Z" is appended to the end of the string to denote UTC time. This value will display in the user's browser time zone when the submission or workflow step is viewed.

Here is a form with Date, Time, and Date/Time controls entered by the user at run-time in the New York time zone.

In the submissions document, notice that the date and time are saved as entered. You can see the time is '10:43:00' which is 10:43 AM in ISO format. However, the Date/Time control value is saved in UTC '14:43:00Z' which is 10:43 AM EST converted to UTC.

ISO Formats
  • Date: YYYY-MM-DD
  • Time: HH:MM:SS
  • DateTime: yyyy-mm-ddThh:mm:ssZ

Date, Time and Date/Time controls display with UTC offsets in the Submission CSV Export.

Date, Time, Date/Time Formats

Designers can select formats for Date, Time, and Date/Time controls from a variety of options. The Date Format only controls what the user sees in the form and not what is stored in the submission xml

Date Format

The Date Format property applies to Date controls and the Date portion of the Date/Time control. The default, recommended format is "Automatic", which is a locale-specific date format. The designer has the option to set a particular date format independent of the locale by using the format field, but this is not recommended. Read this documentation for more information about date controls and internationalization.  

Available Date Formats consist of three different separators (dash '-', slash '/', or period '.') and four date display formats (DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD, or Mmm/DD/YYYY). European date formatting is supported. 

When the Date Format property is set to a specific format, dates entered into the form will be translated and reformatted to match the selected format.

  1. A date typed into a form field will be reformatted to match the selected Date Format 
  2. A date entered into a form field will be translated according to the selected format. For example, if you choose a European format of DD-MM-YYYY and the user enters 10-05-2009, the date value will be translated as May 10, 2009. If you choose a US format of MM-DD-YYY the date value will be translated as October 5, 2009. 
  3. Any of the three separators will be valid for date entry but will be translated to the selected separator. For example, if you choose a format of MM/DD/YYY and the user enters 10-05-2009, the date will display 10/05/2009.
  4. Dates entered like Feb 3, 2001 will be translated into the specified format.

frevvo adjusts dates expressed with a two-digit year to be within 80 years before or 20 years after. For example, using a pattern of "MM/DD/YY" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one-digit string, a three- or more digit string, or a two-digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. frevvo will always format as 4 digit years.  

The date will be converted to the standard xsd:date format of yyyy-mm-dd in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Date control in all variations.

Time Format

The Time Format property applies to the Time control type. The default, recommended format is "Automatic", which is a locale-specific time format. The designer has the option to set a particular time format independent of the locale by using the format field, but this is not recommended. Read this documentation for more information about time controls and internationalization.  

If you keep the default "Automatic" format, you can enter data into a Time control using any of the formats shown in the table. The Time control will accept and display the values as shown:  


The Time Format dropdown provides variations of military and standard time conventions, with either colon or period separators.

When the Time Format property is set to a specific format, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00.

The time will be converted to the standard xsd:time format of hh:mm:ss in the submissions XML document. Here is an example: <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Time control in all variations.

Date/Time Format

Date/Time controls display both the Date Format and Time Format dropdown menus in the properties panel. Rules can be applied to the Date control in all variations. There are some additional considerations for the Date/Time control:

  1. When you enter a date in the date portion of the date/time control (or select the date with the date picker), it will automatically fill the time portion of the control with a value for 12:00 AM. The value displayed depends on the time format selected: For example:  

    Time FormatDefault Time Display
    hh:mm00:00
    hh:mm PM12:00 AM
    hh:mm:ss00:00:00

    hh:mm:ss PM

    12:00:00 AM

  2. The date picker is included in the date portion of the date/time control. You can hide/disable it by unchecking the Date Picker checkbox on the Style tab.
  3. You cannot enter a time value without a date value. 
  4. The time input field cannot be labeled. It is recommended that the label for the date portion be descriptive enough to include the time portion. If the date and time labels over the appropriate input fields are required, two separate controls can be used or the label for the date portion can be extended over the time input field, as shown in the image below:

The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:datetime format of yyyy-mm-ddThh:mm:ssZ in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details.

Date and Time Format on Mobile Devices

Mobile devices support limited date, time, and date/time formats. For example, if you have a date control in your form formatted mm/dd/yyyy and you use that control name as a template in the Form Action Message, you will notice that the message displayed after submitting is in the correct format on desktop view, but changes to yyyy-mm-dd on the mobile view. This is expected and may vary by device and OS. 

Similarly, if you have a date field with a default date in your form it must be formatted as YYYY-MM-DD in order for it to display correctly on mobile devices.


frevvo recommends enabling the date picker for forms that will be used on mobile devices to ensure the date is selected accurately.

Date Picker Property


To display the date picker, check the checkbox on the Style Property panel. If checked, you will see the date picker inside the date control and the date portion of the date/time input control. The Date Picker's large font makes it easy to see.

Clicking on the today link in the date picker brings you to the current date. If you are looking at another month and you click on the today link, the date picker will automatically bring you to the current month with today’s date highlighted(bold). Select the date to populate the field in your form/workflow. To close the Date Picker, click the close link.

Month and year menus facilitate quick navigation to earlier/later dates. For example, selecting a past date when entering a Date of Birth is much easier when utilizing the dropdown menus. When selecting a date in the past, select the year first.

The Date Picker described above only applies to the desktop view. Date and Date-Time controls on mobile devices display device specific date pickers.

Automatic Locale-Aware Format

frevvo supports localization from the browser's locale setting. frevvo will recognize the browser locale and alter displays and input formats as well as language according to the user's setting. Setting this preference is browser-specific. Refer to this website for information about language preferences and how to change those in a number of popular browsers. 

Multi Language Support
Date, Time, and Date/Time controls are locale-aware for both parsing and format. When the Automatic format is selected, both date and time entry and display formatting will be locale-specific. The designer has the option to set a particular date or time format independent of the locale by using the date format or time format property, but this is not recommended because it is not responsive to user locale.

Here is an image of Date/Time controls with the browser language set for German and the Date/Time controls set for Automatic. Notice the date format is DD.MM.YYYY and the time format is HH:MM:

Changing the Firefox browser language setting to Lithuanian displays the dates and times using the format YYYY-MM-DD and HH:MM respectively:

The automatic locale-specific formatting and parsing for date, time, and date/time controls can be configured by manually adding the following properties in the locale properties file:

Property NamePurposeNotes
frevvo.date.formatAllows the admin to configure the locale-specific format pattern for date controls and the date portion of date/time controls.  If not set it falls back to the system default value for the locale as derived from the Java runtime.See  http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for date and time formatting pattern rules.
frevvo.time.formatAllows the admin to configure the locale-specific format pattern for time controls and the time portion of date/time controls.  TIf not set it falls back to the system default value for the locale as derived from the Java runtime.See  http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for date and time formatting pattern rules.

For example, let's say you want to change the MM.DD.YYYY to display as "Day of the week, Month Day, year" in the German locale. Simply add the following to the ger locale file located in the WEB-INF/data/locale directory as explained above:

frevvo.date.format="EEE, MMM d, ''yy"

After replacing the /WEB-INF/data directory file with the updated one, the date will display as shown in the Firefox browser set for the German locale:

To translate AM and PM in time / date-time control formats, assign the value "h:mm a" to the frevvo.time.format property in the concerned locale file.

Date Picker

The Date picker will be automatically translated according to the browser locale. You can override the browser setting by adding the properties shown below to the locale file. This localization only applies to the date picker on the desktop as the native date picker will be shown on mobile devices. You can translate  (locale-specific) month names and abbreviated day of week names (two characters).  The days of the week will always be shown as Sunday through Saturday, left to right on the date picker.  Only the Gregorian calendar system is supported.

To localize the date picker on the desktop, manually add the following properties in the appropriate locale properties file in the WEB-INF/data/locale directory as explained above.

Property NamePurpose
frevvo.date.month.1Allows the admin to override the locale-specific short name for the 1st month of the year (January).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.2Allows the admin to override the locale-specific short name for the 2nd month of the year (February).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.3Allows the admin to override the locale-specific short name for the 3rd month of the year (March).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.4Allows the admin to override the locale-specific short name for the 4th month of the year (April).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.5Allows the admin to override the locale-specific short name for the 5th month of the year (May).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.6Allows the admin to override the locale-specific short name for the 6th month of the year (June).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.7Allows the admin to override the locale-specific short name for the 7th month of the year (July).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.8Allows the admin to override the locale-specific short name for the 8th month of the year (Aug).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.9Allows the admin to override the locale-specific short name for the 9th month of the year (Sept).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.10Allows the admin to override the locale-specific short name for the 10th month of the year (Oct).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.11Allows the admin to override the locale-specific short name for the 11th month of the year (Nov).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.month.12Allows the admin to override the locale-specific short name for the 12th month of the year (Dec).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.1Allows the admin to override the locale-specific short name for the 1st day of the week (Sunday).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.2Allows the admin to override the locale-specific short name for the 2nd day of the week (Monday).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.3Allows the admin to override the locale-specific short name for the 3rd day of the week (Tuesday).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.4Allows the admin to override the locale-specific short name for the 4th day of the week (Wednesday).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.5Allows the admin to override the locale-specific short name for the 5th day of the week (Thur).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.6Allows the admin to override the locale-specific short name for the 6th day of the week (Fri).  This overrides the system default value for the locale as derived from the Java runtime.
frevvo.date.weekday.7Allows the admin to override the locale-specific short name for the 7th day of the week (Saturday).  This overrides the system default value for the locale as derived from the Java runtime.

For example, Let's say you add the properties below to a Chinese translation file named zh:

frevvo.date.month.1=JaC
frevvo.date.month.2=FeC
frevvo.date.month.3=MaC
frevvo.date.month.4=ApC
frevvo.date.weekday.1=Mc
frevvo.date.weekday.2=Tc
frevvo.date.weekday.3=Wc
frevvo.date.weekday.4=Tc  

After replacing the modified /WEB-INF/data directory file, restarting frevvo and setting the Firefox browser to Chinese - zh, the date picker will display as shown in the image:

Notice the month is displayed as JaC and the days of the week show Mc, Tc, Wc and Tc for Sunday - Wednesday as specified by the format properties we added to the locale file. Thursday, Friday, and Saturday display in Chinese - the language setting of the browser in this example. 

Entries for the Today and Close buttons on the Date Picker are already included in the default locale file so all you need to do is add your translations for them in the locale file you are going to use. 

Internationalization of Date Picker for iOS.

The locale of the date picker on the safari browser changes with the iPhone/iPad's "Region Format" settings, not the language settings. After setting the language in iOS, set the appropriate country/region format in the iPhone general settings.

Navigate these settings to change the Country/Region Format on iOS devices: General>International>Region Format: Select the Appropriate Country.

Time Zones

frevvo automatically infers the time zone from the user’s browser time zone upon login or first access (anonymous users). Once a form is loaded in a given time zone, that time zone cannot be changed. When you browse a form's share URL, you will notice that frevvo automatically appends the _formTz parameter to it based on the detected browser time zone. For example, here is the Link (email/web page) for a Contact Form:

https://staging-app.frevvo.com/frevvo/web/tn/frevvodocs/u/e1dd0efb-f368-4e60-937a-fe08849485d5/app/_prvukdAbEeqgkvXTAjBEIA/formtype/_6-LdwPlHEeuztqyQmKh8FQ/popupform

Browsing it in the America/New York Time zone automatically appends the _formTz parameter as follows:

https://staging-app.frevvo.com/frevvo/web/tn/frevvodocs/u/e1dd0efb-f368-4e60-937a-fe08849485d5/app/_prvukdAbEeqgkvXTAjBEIA/formtype/_6-LdwPlHEeuztqyQmKh8FQ/popupform?_formTz=America%252FNew_York

Browsing the same URL in the Africa/Lagos time zone automatically appends the _formTz parameter as follows:

https://staging-app.frevvo.com/frevvo/web/tn/frevvodocs/u/e1dd0efb-f368-4e60-937a-fe08849485d5/app/_prvukdAbEeqgkvXTAjBEIA/formtype/_6-LdwPlHEeuztqyQmKh8FQ/popupform?_formTz=Africa%252FLagos

Imagine that a user in New York enters the date, time and a date/time on the first step in a workflow.

A subsequent step will be viewed by the assigned user in a different time zone. Here is the exact form above viewed in Paris' time zone. The Date and Time controls display their values exactly as entered above. However, because Date/Time controls rely on the browser time zone, the Date/Time originally entered in New York as '10:43 AM' is displayed in Paris time as '3:43 PM'. 

_formTz URL Parameter

It is possible to override the browser time zone by appending the &_formTz=<tz> parameter to the form URL. Replace <tz> with a Modern Time Zone String (See this list of tz database time zones). Other time zone formats are not supported.

The _formTz parameter is automatically set to the user's browser time zone upon login or first access (anonymous users). It is only necessary to provide it in the share link if wish to override the user's time zone. 

Example

Here is a Product Order form running in the PST time zone, but with the &_formTz=America/Tijuana. The _formTz parameter overrides the browser time zone, and the form displays the date/time control data in the America/Tijuana time zone.

http://localhost:8082/frevvo/web/tn/qa.com/user/rap1/app/_cm8JIGR7EeG4D7_jeDNSHQ/formtype/_XyC2wGbsEeG2-p_Sm3q9pA/popupform?locale=&_formTz=America/Tijuana

Some time zones may not return the expected results. This is a known issue with the JVM. Contact Customer Support for assistance.

Time Zones and Business Rules

Current Date and Time Functions

Designers may use functions like today(), timeofday(), or now() to set Date, Time, or Date/Time control values in the form. These functions typically run in the user's browser time zone. If the _formTz parameter is used to override the user's browser time zone, the rules will run in the specified time zone.

Correct Date and Time Formatting in Rules

frevvo converts times into the browser's local time zone before displaying them in the form. However, if time data is not correctly formatted frevvo will make multiple attempts to parse the time but will always display the time with NO time zone conversion. Here are examples of correct time formats:

t1.value = "20:30:00"; //No time zone specified, will be displayed as is.
t2.value = "20:30:00Z"; //The special "Z" character specifies UTC time zone.
t3.value = "20:30:00-04:00" //UTC Offset using +/-. -04:00 is EDT (America/New_York) time zone.
dt1.value = "2020-08-23T20:30:00"; //DateTime controls must have the "T" character separating the date part of the string from the time part.
// Any combination of valid date and time formats are allowed for DateTime controls.

If the browser is running in EDT America/New_York, then "20:30:00" is equivalent to "20:30:00-04:00". So, in this case t1 and t3 in the above example would display the exact same times.

The following time formats are incorrect. Though the time and date/time controls get initialized, no time zone conversion occurs.

// BAD time formats
DateTime.value=["2020-8-23","20:20:20"];
Time.value="20:30";

Displayed Values

  • The Time control is independent of any time zone and simply displays the value as set regardless of which time zone you are accessing it from.
  • The Date/time control displays in the browser's local time zone.

Here are some examples to clarify proper time initialization and how they display at run-time. 

In the following examples the brower's time zone is UTC-05:00 which is the winter time zone for America/New_York.

In this rule, the time data is specified as UTC-05:00. Thus when the control named date/time is initialized with a date of August 23rd, which falls in the summer UTC-04:00 time zone, the time gets converted and displayed as 21:20:20, one hour ahead. Time controls are not affected by time zone, so if a user enters 20:30:30 into a Time control it will always appear as 20:30:30 even if viewed by a browser in a different time zone.

if (ESTOffset.clicked) { // UTC-05:00 (winter)
  Date.value= frevvo.currentDate();
  DateTime.value="2020-08-23T20:20:20-05:00";
  Time.value="20:30:30";
}

In this rule the time data is specified as UTC-04:00. The date/time control has no conversion since August 23rd falls in UTC-04:00 time zone. The control named Time is not affected by the time zone so it displays whatever is specified in the rule.

if (EDTOffset.clicked) { // UTC-04:00 (summer) 
  Date.value= frevvo.currentDate(); 
  DateTime.value="2020-08-23T20:20:20-04:00"; 
  Time.value="19:30:30";
}

These two rules both specify the time data in UTC time zone because the special character "Z" is equivalent to an offset of UTC-00:00. The Time control is not affected by the time zone so it displays the value specified in the rule data. The date/time control is a date of August 23rd, which falls in the summer UTC-04:00 time zone so the rule data is converted and displayed as four (4) hours behind UTC.

if (ZOffset.clicked) { 
  Date.value= frevvo.currentDate();
  DateTime.value="2020-08-23T20:20:20Z";
  Time.value="15:20:20";
}
if (OOOO.clicked) { 
  Date.value= frevvo.currentDate();
  DateTime.value="2020-08-23T20:20:20-00:00";
  Time.value="15:20:20";
}

This rule has incorrect UTC syntax. The Time control initialization is missing the required seconds and the date/time control is using an array syntax that is not a valid UTC time initializer. frevvo makes an attempt to parse the times and does fairly well in this case. But due to the incorrect syntax the date/time control's time zone is unknown and the rule is unable to do the proper conversion to the brower's time zone. The Time control's value is ok as it is not affected by time zone. The date/time control's value is clearly wrong as the browser is running in UTC-05:00 while August 23rd is in daylight savings time UTC-04:00. 

 

Business Rules for Dates and Times

Built-in Methods

frevvo provides built-in helper methods for common functionality required by business rules.

Date and Time Methods

Here is the list of available methods for working with dates and times:

  • Time - frevvo.currentTime() - returns the current time in the user's local time zone. This method should only be used to set the value of a Time control.
  • Date - frevvo.currentDate() - returns the current date in the user's local time zone. This method should only be used to set the value of a Date control.
  • DateTime - frevvo.currentDateTime() - returns the current date and time in the user's local time zone. This method should only be used to set the value of a Date/Time control.
  • DateUtil.todayISO() - returns today's date in 'yyyy-mm-dd' format. The date is returned in the server's time zone.
  • frevvo.beforeDate(Date1.Date2) - true if Date2 is earlier than Date1.
  • frevvo.afterDate(Date1, Date2.value) - true if Date2 is after Date1. Date1 and Date2 are controls in your form.
  • frevvo.addToDate(date, "m, d, or y", "number of days, months or years you want to add") - Add years,days or months to a date. See an example here.

Here is an example of setting a Time control named Tm, a Date control named  Dt, and a Date/Time control named DtTm. See the dates and times rule examples for more samples.

  Tm.value = frevvo.currentTime();
  Dt.value = frevvo.currentDate();
  DtTm.value = frevvo.currentDateTime();

The methods listed below have been deprecated and will be removed in a future release.

  • frevvo.currentTime(form)
  • frevvo.currentDate(form)
  • frevvo.currentDateTime(form)
  • String DateUtil.today()

If these methods are used in rules, the designer will see a message in the Debug Console urging that the methods listed above be used instead.

Business Rules and Time Zones

Date and Time functions run in the context of a time zone. However, if your rules run before the form infers the browser time zone (on initialization and outside of a Space/Task List), these functions will return the server time in UTC. You should consider whether to add the _formTz parameter to specify the time zone where the rules should run. See the Time Zones and Business Rules documentation for more details.

Rule Considerations for Dates and Times

Working with Rules
There are several special considerations when writing rules using date, time and date/time controls. You can also find many working samples in the Rules Examples chapter.

To initialize a date control, the data must be in the correct format. Here are examples of correct date formats:

d1.value = "2012-01-13"; //yyyy-mm-dd
d2.value = "01-13-2012"; //mm-dd-yyyy
d3.value = "jan 13 2012"; //using string for month

 The following formats will not correctly initialize a date control. They will either cause unexpected results or be flagged as an invalid value when the form is used.

//adjusted or invalid date formats
d4.value = "2012-13-01"; //yyyy-dd-mm
d5.value = "13-01-2012"; //dd-mm-yyyy
d6.value = "13-2012-01"; //dd-yyyy-mm
d7.value = "01-2012-13"; //mm-yyyy-dd

In general, it is not recommended to rely on either the browser's locale or the server's locale when writing date, time (time of day) and date/time literals in frevvo rules. The recommended method is to use locale independent formats that are listed below. These are standard ISO formats.

Date - yyyy-MM-dd

Date/Time - yyyy-MM-ddTHH:mm:ssZ - The trailing Z indicates UTC.). 

Time - HH:mm:ss (or HH:mm). Time is really time of day and is not affected by time zones at all.

yyyy-MM-ddTHH:mm:ss is also supported but will convert to the server's timezone. The rule author has no control of this, so it is not recommended.

Here is an example rule:

if (form.load) {
  date.value = "2020-02-20";
  timeofday.value = "13:10:02";
  datetime.value = "2020-02-20T18:10:02Z"; 
}

This rule will initialize a date control in a form with 02-20-2020, a time control with 1:10 PM and a date and time control with 02-20-2020 in the date portion and 1:10 PM in the time portion.  

Notice the special character "Z" at the end of the date/time value. This is equivalent to an offset of UTC-00:00 and indicates that the time of 18:10:02 is given in UTC. 18:10:02 UTC is equal to 1:10 PM Eastern Standard time. 

Date and Time Rule Examples

Rule Examples
Working with dates and times is very common in most forms. Some common scenarios are:
  • Populate a Date control with Today's date when the form/workflow loads
  • Populate a Date control when the user signs
  • Show the Date and Time of a Sales Order
  • Create a Date Time Stamp
  • Calculate the Number of Days between two dates

The samples below show you how to create the most common business logic with dates and times. 

Working with Date and Time Rules

  • frevvo dates can be set in the user's local time zone by using the built-in date, time and date/time methods such as frevvo.currentDateTime(). See Built-in Methods for a complete method list. If you use the base JavaScript date object you will get the UTC time zone.
  • Many of the samples below use the JavaScript Date() object. Since business rules run on the form server these dates will be in the time zone where the form server was installed. There are techniques below to convert to different timezones as you need.
  • The Date/Time control uses a "T" to separate the date and time when initializing from a business rule. For example, the syntax shown below will initialize a Date/Time control named DtTm to May 15, 2012 at 4:20 am.

    DtTm.value = "5/15/2012T4:20";

A Date or Date/Time control can be converted to a js Date object: 

var date = new Date(Field.value);

A Time field can be converted to a js Date object:

var time = new Date('1970-01-01T'+Field.value);

Date controls will successfully initialize via a rule or an xml document when the data provided has a single digit for the month and/or the day, however Date/Time controls must have a 2-digit month and day.  The rule below can be used to initialize a form with a date and date/time control.  

if(form.load)
{
// Date control may have a single digit for the month and/or day
Date.value = "2020-7-1";
// DateTime control must have a double digit month and day
Date_Time.value = "2020-07-01T20:20:20";
}

The Date/Time control will display an "Invalid Value" error if single digits for the month and/or day are used .


Date and Time functions typically run in the user's browser time zone. See the Time Zones and Business Rules documentation for more details.

Our Rule Examples chapter provides several examples of setting, validating, and calculating dates and times using business rules. Visit the Date and Time Control Rule Examples.

Initializing Date, Times, and Date/Times from _data or XML Documents

The section below explains initializing date, time and date/time values from _data. Similar rules and concepts apply when initializing values from an XML document. See Initializing Forms with XML Documents and Viewing XML Documents for further information.

Initializing Forms with Data
When you initialize controls with Date or Time values, they will always display the exact value passed. However, the Date/Time control is time zone dependent, and will behave differently depending on how the time zone is provided:
  • If the time zone is provided in the Date/Time value, the value will be converted to the timezone of the browser and displayed in the form accordingly. The time for the Date/Time control is proceeded by a capital "T" (Time Zone) and followed by a "Z" (UTC timezone,) such as '2021-08-20T11:13:00Z'.
  • If the time zone is provided in the URL using the _formTz parameter, the Date/Time value will be converted to and displayed in the time zone specified in the parameter. This will also override the browser time zone.
  • If the time zone is not provided using either method, you will see a parsing error such as "Error: The most likely reason in a syntax error in _data." This applies to Date/Time controls only.

Successful initialization cannot be guaranteed if the time zone for a Date/Time control is not provided (either in the XML document or in the _formTz URL Parameter). This does not apply if your form only has Date and/or Time controls.

Here is an example of a URL that initializes a date only, time only, and date/time control. Notice that the Date/Time value does not have a 'Z' or another timezone indicator, but the appended &_formTz parameter supplies the timezone, America/New York.

https://app.frevvo.com/frevvo/web/tn/frevvodocs/u/e1dd0efb-f368-4e60-937a-fe08849485d5/app/_WtkW4A9KEeOGyY8morCUKA/formtype/_5wQPkAHuEeyZEcN_1gjwxA/popupform?_data=(OrderDate:2021-08-20,OrderTime:'11:13',OrderDateAndTime:'2021-08-20T11:13:00')&_formTz=America/New_York

The local time will be converted to and saved in a valid UTC format for the time portion of the date/time control in the submission XML document. You may see the time in UTC format with a trailing "Z" (UTC) time or the time value plus or minus the UTC offset. See Initializing Forms with XML Documents and Viewing XML Documents for further information.

Use Case Examples

 This section is under construction.

Example 1: Initializing a Form with the Current Date and a Time

Designers commonly use business rules to initialize the current date and the current time when a form loads, which ensures accurate data and saves the user one or two points of data entry. Here's a simple Contact Us form, which we want to initialize with the current date and time. We're using two Date controls, one is set to Control Type 'Date' and the other to Control Type 'Time'. Since we will prefill them using rules, we have removed decorators and the date picker and set them to disabled.

Then we used the Visual Rule Builder to initialize the form with the Date and the Time.

Now we're ready to share the form with users, so we need to decide whether or not to use the _formTz URL parameter in our Share link.

If we share the form without the _formTz parameter and outside of a Space, the rules to initialize the Date and Time controls will return and display the current date and time UTC. Even though this is accurate, it could confuse our users because the time (and potentially the date) displayed is different from their own time zone.

Another option is to use the _formTz parameter to always run the rules and display the date and time in a particular time zone. Perhaps our company is based in New York, and we expect this Contact Us form to only be used by people in the America/New_York time zone. We would append the parameter _formTz=America/New_York to our share URL and our users would see this result.

We can also choose to share this form inside a frevvo Space, which will automatically include the user's browser time zone in it's own _formTz parameter, and therefore the dates and times will resolve and display in the user's own time zone.

Whether or not you choose to use the _formTz parameter, the submitted values of these controls will be the exact value displayed to the user but in ISO format. 

  • The submission XML for the form without _formTz would show the time value as 19:36:00.
  • The submission XML for the form with fomTz=America/New_York would show the time value as 15:35:00.

What if our company is global, and people from any time zone might fill out our Contact Us form? In that case, we may want to replace our Date-type and Time-type controls with a single Date/Time control, and update our rule to get the current Date/Time. Date/Time controls store data in UTC but display them in the user's browser time zone.

So a user in New York would see the Date/Time is 8/9/21 at 4:05 PM. . .

. . . while a user opening the form at the exact same time in Paris would see the Date/Time is 8/9/21 at 10:05 PM.

In both the form completed in New York and the one completed in Paris, the forms' submission XML will show an entry with the Date/Time value in UTC time zone, and also in ISO format.

 <TodaySDateAndTime>2021-08-09T20:05:55Z</TodaySDateAndTime>


Example 2: Workflow Steps Completed in Different Time Zones

Coming soon...

Example 3: Meeting Scheduler

Coming soon...










  • No labels