Skip to main content

convertToEpoch

A Workflow Engine function that converts a date string to epoch seconds using an optional date mask.

This function is available as a feature of the Add-ons v2.4 download and later.

This function is available for event, alert, and Situation workflows.

The workflow sweep up filter applies to this function.

Back to Workflow Engine Functions Reference.

Available Macros

The date mask uses a set of macros to represent the “atomized” parts of a date - hours, minutes, seconds, date, month, year, and so on. The available macros are loosely based on a subset of those available from the strftime library:

Table 1. 

Macro

Value

%z

Local timezone offset as +/-hhmm. Example: +0000

%y

The year in short form. Example: “21”

%p

“pm” or “am”.

%m

Month number: 01-12

%-m

Unpadded month numbers: 1-12

%d

The day of the month: 00-31

%-d

The unpadded day of the month: 0-31

%b

The month in short form. Example: “Feb”

%a

The day in short form. Example: “Mon”

%j

The day of the year: 001-35[56]

%-j

The unpadded day of the year: 1-35[56]

%f

Fractions of seconds: .012345

%Y

The year in long form. Example: “2021”

%M

Minutes as a decimal : 00-59

%-M

Minutes as an unpadded decimal: 0-59

%h

12hr representation of the hour : 01-12

%-h

12hr representation of the hour (unpadded): 1-12

%H

24hr representation of the hour: 00-23

%-H

24hr representation of the hour (unpadded): 0-23

%B

The month in long form. Example: “February”

%A

The day in long form. Example: “Monday”

%S

Seconds : 00-59

%-S

Seconds (unpadded): 0-59

%Z

Time Zone: specific non-location. Example: PDT



The above macros can be mixed with standard string characters to match the date format being used. For example, the default mask:

%Y-%m-%dT%H:%M:%S.%fZ

Would match the default JavaScript UTC date string:

2022-01-18T14:47:25.718Z

Arguments

Workflow Engine function convertToEpoch takes the following arguments:

Name

Required

Type

Description

date

yes

string

The date string to convert. Use substitutions to take the value from the event or workflow context.

mask

no

string

The date mask to use for the conversion. See the action documentation for acceptable macros. Defaults to: %Y-%m-%dT%H:%M:%S.%fZ

destination

yes

string

The CEVent or workflow context to write the epoch time to.

Example

The following example demonstrates typical use of Workflow Engine function convertToEpoch.

The following arguments are used to convert a time string from the event field custom_info.date to set a new value for the agent_time:

Table 2. 

date

$(custom_info.date)

mask

%d %B %Y %H:%M:%S

destination

agent_time



This is displayed in the UI as:

{"date":"$(custom_info.date)","mask":"%d %B %Y %H:%M:%S","destination":"agent_time"}

The resulting event will contain:

    "agent_time": 1640012988,
    ...
    "custom_info": {
        "date": "20 December 2021 15:09:48",
        ...
    }

The agent_time has been set to 1640012988 by converting the date string 20 December 2021 15:09:48 using the date mask %d %B %Y %H:%M:%S.

If the date string had included a timezone, such as 20 December 2021 15:09:48 GMT+0800, we could use the mask %d %B %Y %H:%M:%S GMT%z to parse the timezone as well. This would produce:

    "agent_time": 1639984188,
    ...
    "custom_info": {
        "date": "20 December 2021 15:09:48 GMT+0800",
        ...
    }

Which sets the agent time to 8 hours (28800 seconds) earlier than the same date time in GMT.

In this section: