Introduction

There are a few functions dedicated to dealing with datetime data. They make formatting time and changing between time zones much easier than it would be if datetime was treated as a string.

What will I learn?

After following this guide, you'll be able to:

• Fetch the current time.
• Create datetime objects from strings.
• Add time increments to datetime objects.
• Format datetime to a string of any format.

Prerequisites

You'll need access to a Documotor tenant and a basic understanding of the platform. Also, you should be familiar with JSON data types and JMESPath expressions.

Sample data

We won't need any sample data - we'll simply create all the datetime instances in the transformations.

Transformations

There are only four datetime functions: add_time, current_time, format_datetime_to_timezone and to_datetime. First, let's fetch current time, and then we'll apply the other datetime functions to the current time.

	// Fetch the current time.
	currentTime: current_time(`0`),
  // "currentTime": "2024-02-07T14:13:41.581541Z"

The only argument of the current_time function is the offset of the current time in hours, meant to represent a timezone. For the sake of trying out the function, we leave it at zero. Now we'll do some formatting, conversions and time calculations.

{
	// Set the current time to the CET timezone, convert to string and  display only hours and minutes.
	currentTimeCETString: format_datetime_to_timezone($.currentTime, 'H:m', 'da-DK', 'CET'),
  // "currentTimeCETString": "15.13",

	// Convert the previous result back to datetime to perform more calculations.
	currentTimeCETDatetime: to_datetime($.currentTimeCETString, 'H:m', 'da-DK'),
  // "currentTimeCETDatetime": "2024-02-07T15:13:00",

	// Add an hour to the current time.
	movingTheClock: add_time($.currentTimeCETDatetime, `1`, 'h'),
  // "movingTheClock": "2024-02-07T16:13:00",

	// Convert the time to a string again. Notice that the datetime timezone is treated as GMT every time.
	newTimeString: format_datetime_to_timezone($.movingTheClock, 'H:m, d.M.yyyy.', 'da-DK', 'CET')
  // "newTimeString": "17.13, 7.2.2024."
}

Result

Here is the result of this transformation:

{
  "currentTime": "2024-02-07T14:13:41.581541Z",
  "currentTimeCETString": "15.13",
  "currentTimeCETDatetime": "2024-02-07T15:13:00",
  "movingTheClock": "2024-02-07T16:13:00",
  "newTimeString": "17.13, 7.2.2024."
}

Learn more

• Check out the reference page for datetime functions for a full overview of datetime functions.
• The full list of the IANA tags used for languages and regions used in format_datetime_to_timezone and to_datetime can be found here.
• The full list of date and time format strings can be found here, provided by Microsoft.
• Full timezone names from IANA and Microsoft are supported, as well as some of the more common abbreviations.