Date & Time Handling

Dealing with dates & times can be tricky, but Flow XO has some built-in logic that should make manipulating dates as painless as possible.

The Date/Time Field

A date/time field is a service input field that expects a date (and sometimes a time too). You'll recognise them because of the date/time picker, and the link to this article. Here's an example:

The field is like any other in Flow XO - it can accept some predefined text, or you can drag a property from a previous task on the right hand side of the screen and drop into the field. You can of course use a combination of an output property and some extra text.

Recognised Formats

Most services that output dates in Flow XO do so in ISO 8601 format (although we do omit the T and Z from the format), and that's how our date/time fields prefer to receive dates & times (although they are quite forgiving, as you'll see in a moment). An ISO 8601 date/time looks like this:

2015-01-18 18:31:50

You'll see that's a date in the format yyyy-mm-dd, then a space, followed by the time in hh:mm:ss format. If you provide a date/time like this, you can be certain that it will be dealt with consistently.

However, we'll try our best to interpret any date/time we receive, regardless of the format. So you can throw any of these formats at us and we should be able to deal with them:

  • now
  • today
  • tomorrow
  • next week
  • next month
  • next year
  • 11pm
  • 11:30pm
  • 23:30
  • Friday, January 9th 2015
  • January 9th 2015
  • friday at 10am
  • this friday at 10am
  • next friday at 10am
  • may 25th of next year
  • 2014-01-18 09:30:00
  • 2014-01-18 09:30:00 -0400

If we don't recognise the date/time, it's equivalent to leaving the field empty - i.e. we won't send any date/time across. Of course, that might cause an error, so you need to make sure that if the field is required there will always be a valid date in it.

There's actually a fairly limitless number of acceptable date formats. To see how your date/time is interpreted, you can type it into this form to see (note that this checker doesn't prefer the future when date/times are ambiguous, see the next section for details).

Ambiguity

We prefer the future when there's ambiguity about a date/time. For example, we take 10:00 to mean the next time it will be 10am (either today or tomorrow), rather than always 10am today.

For example, if it's currently 9am and you use the date/time 10:00, we'll assume you mean 10am today. If it's 3pm and you use that, we'll take that to mean 10am tomorrow.

You can always use:

  • today 10:00
  • tomorrow 10:00

These are unambiguous and will always be taken literally.

Offsetting Your Date/Time

You'll often want to 'offset' your date/time by a number of days, hours or and/or minutes. For example, if your flow is triggered by a new event in a calendar, you might want to create a task in your CRM 1 hour before the event's date/time. For that, you can use a modifier -1h:

{{new_event_in_calendar.event_due}} -1h

There's 3 different offsets you can use in combination. These are d (days), h (hours) and m (minutes). Some examples of valid offsets:

  • +1d (1 day in the future)
  • -3h -30m (3 hours, 30 minutes in the past)
  • +2d +12h +10m (2 days, 12 hours and 10 minutes in the future)

Important: Make sure you stick exactly to this format otherwise your offset won't be recognised. There must be a space between your date and each offset, and you must use a single whole number as your offset (not a decimal).

These are examples of invalid offsets:

  • +0.5d (use +12h to express half a day instead)
  • {{service.date}}-1h (always use a space between the date and the offset, {{service.date}} -1h)
  • +1d+2h (use a space between the offsets, +1d +2h)
  • +5days (days isn't recognised, always use +5d)

Timezones

Dates and times are processed and output in the timezone set at the account level, except where a timezone offset is provided as part of the date (for example, -05:00 or +0100).

Examples

Remember you can use outputs from previous tasks, fixed dates, or a combination of those in date/time fields. Here are some valid date/times:

  • {{service.date}} (use an output from another field directly as an input)
  • 2015-07-01 (a fixed date, useful if you have an upcoming event that you want to run your flow around)
  • 2015-07-01 13:00:00 -0500 (a fixed date & time, including a timezone offset)
  • {{service.date}} 17:00:00 (a combination of an output for date and fixed time)
  • {{service.date}} -2h (2 hours before a date/time from an output)
  • {{service.year}}-{{service.month}}-{{service.day}} (a date made up of 3 outputs for year, month and day

Let us know how we can improve Flow XO on our feedback site.

Still need help? Contact Us Contact Us