Create your own date formatting function in Flow Builder

The Call Function step offers the possibility to add your own custom step to your flow.

Use the Functions Editor to create, edit and test your function! Once you’ve done this, you can use your new function inside Flow Builder via the Call Function step.

Formatting date/time stamps

Sometimes you’ll receive timestamps in a certain format but want to use them in a different format. For example, many systems use a standardized format called RFC 3339, which formats a date/time stamp like this:

2011-01-21T12:00:00.00Z

This format is great for storing all the date, time, and time zone information in a compact way, but it is not very readable for humans! to solve this problem, let’s create a function that takes timestamps in the RFC 3339 format and returns the same value in an easy-to-read format.

We could use the JavaScript Date object to do this, passing it our RFC 3339 timestamp and using its getDate, getHours method, but that would have a few downsides. This method would only return a single format that we cannot change without changing our function, and would be further confused by location-based date formatting, such as DD/MM/YYYY vs MM/DD/YYYY, or by time zones.

But, luckily, some smart people have made a library with the sole purpose of handling date/time logic. The library is available on NPM as the date-fns module. We can use the helper functions from this library to build a date/time formatter function that can transform one format to another in a standardized way.

Building the date formatting function

1. Before we can build our function, we first need to add the date-fns module to our dependencies so we can import it into our function. Install the latest version available (at the time of writing this that was 2.16.1).

2. Next, go back to the editor tab and define the input parameters. Our function will accept a `datetime` variable containing the timestamp in RFC 3339 format (or any other format accepted by the JavaScript Date object) and a `format` variable containing the notation for the format we want according to the date-fns format method documentation. For example we could pass “1985-04-12T23:20:50.52Z” for `datetime` and “MM/dd/yyyy hh:mm:ss” for `format`.

3. In the editor below the input parameters, enter the following code:

   'use-strict';
   
   const dateFns = require('date-fns');
   
   exports.handler = async function(context, variables) {
      if (
          !variables.datetime ||
          typeof variables.datetime !== 'string' ||
          !variables.format ||
          typeof variables.format !== 'string') {
          console.error(`received invalid variables!: ${variables}`)
       }
   
      // format according to options defined in https://date-fns.org/v2.16.1/docs/format
      const formattedDate = dateFns.format(new Date(variables.datetime), variables.format)
   
      return {
          formattedDate
      }
   };

A step-by-step breakdown of the date formatting function setup

Let’s go through it part by part to explain how it works.

First, we import the date-fns module using this code:

const dateFns = require('date-fns');

On the `dateFns` variable we can now read out any method exposed by the date-fns library. For our use case, we’re interested in the `format` method.

Inside our handler function, we first do a bit of data validation:

if (
!variables.datetime ||
typeof variables.datetime !== 'string' ||
!variables.format ||
typeof variables.format !== 'string') {
console.error(`received invalid variables!: ${JSON.stringify(variables)}`)
}

This if statement makes sure the `datetime` and `format` variables exist and are of the expected type string. If any of the checks returns false, we log an error. We also log the variable input we received so we can debug our function using the logs.

Instead of logging an error and then continuing the function and letting it crash, we could also return early with some default value. This would mean our function does not crash and our flow execution would continue with the default value. Depending on your use case and flow logic you can pick one or the other. You can also skip the validation entirely if you’re sure the data your function receives is always correct.

The next line of code is where the actual formatting happens:

const formattedDate = dateFns.format(new Date(variables.datetime), variables.format)

In this line, several things happen:

1. We pass our `datetime` variable to the `new Date` constructor which creates a Date object we can format.

2. We call the `dateFns.format` method and pass it the Date object we created and the `format` variable.

3. Internally the format method will take the date object and return it formatted according to the specific format. For example, given a `datetime` value of “2021-01-25T16:37:00.582Z” and a `format` value of “MM/dd/yyyy hh:mm:ss a”, it will return “01/25/2021 04:37:00 PM”.

4. We store this value in a variable called `formattedDate` so we can use it later in Flow Builder.

By returning the value as an object, it will be available in Flow Builder as a property on the output variable. So if we name our variable `myOutput` we can read our value from `{{myOutput.formattedDate}}` in FlowBuilder.

Using an object for the return value makes it easy to add more values to it in the future without having to rewrite all the variables in our flow.

Testing the date formatting function

Now, save the function and wait for it to deploy. After this, we do a test run by using the test option on the functions list. In the test modal, enter an example value for the `datetime` and the `format` variables, and view the output your function will return.

A test run for our date formatting function could look like this:

Note that the format variable uses the details of the option in the date-fns documentation. For example `MM` means months formatted from “01” to “12” while `mm` means minutes formatted from “00” to “59”. The `a` at the end is the format for adding “AM” or “PM”. You can play with this format to find one that works best for your use case.

Set up the Call function Step

To use the date formatting function in Flow Builder, add the Call Function step to a flow and configure it like the screenshot below.

All names starting with `my` are variables that you can name however you want. Use `{{myOutput.formattedDate}}` in your flow to use the formatted date time stamp.

Tips and best practices for setting up your date formatting function

Follow these tips and best practices to adjust the date formatting function to your exact use case:

• If you always want to use the same format you can hardcode it, either in the Call Function step or in the function itself (make sure to also remove it from the validation check then)

• The date-fns module also offers lots of other methods. You can explore these in case you need other date/time-related logic or to make your function more robust in case your data is less uniformly formatted.

• If you want to handle cases where your function fails, make sure to use the “Handle failures” option on the Call Function step.