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.  

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.

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 Format	Default Time Display
   hh:mm	00:00
   hh:mm PM	12:00 AM
   hh:mm:ss	00: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:

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.

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.

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. 

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

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  

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.

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

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 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 DebugConsole urging that the methods listed DateandTimeMethods be used instead.

Rule Considerations for Dates and Times

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

//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

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

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

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

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 portal, 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 portal, which will automatically include the user's browser time zone in its 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...