a!addDateTime() Function

Function

a!addDateTime( startDateTime, years, months, days, hours, minutes, seconds, useProcessCalendar, processCalendarName )

Adds the specified increments of time to the startDateTime and returns a date and time value. You can select a process calendar to ensure the return value falls within the specified working days and time.

Parameters

Keyword Type Description

startDateTime

Date and Time

The starting Date and Time value. Use the datetime() function to convert a given date and time into a serial number that holds the Date and Time data type. This parameter is required.

years

Number (Integer)

The number of years to add to the start value.

months

Number (Integer)

The number of months to add to the start value.

days

Number (Integer)

The number of days to add to the start value.

hours

Number (Integer)

The number of hours to add to the start value.

minutes

Number (Integer)

The number of minutes to add to the start value.

seconds

Number (Integer)

The number of seconds to add to the start value.

useProcessCalendar

Boolean

Determines if a process calendar is used to calculate the result. The returned value will fall within the work time defined in the calendar. Default is false.

processCalendarName

Text

The name of the process calendar to use. If useProcessCalendar is true and this parameter is not specified, the default process calendar is used. This parameter is case-sensitive.

Returns

Date and Time

Usage considerations

Using the startDateTime parameter

The startDateTime parameter can accept values of type Text, Date, Date and Time, Integer since the epoch, Decimal since the epoch, and Array types. Time values are not supported.

If you use a Date data type, the value will be automatically cast to a Date and Time data type. When the value is cast to Date and Time, the time component will be 12:00 AM GMT unless you've specified a process calendar. If you specified a process calendar, then the time component will be 12:00 AM in the calendar's specific timezone.

If multiple values are passed to the startDateTime parameter, or the value is type Array, the function will return a Date and Time array.

Using a process calendar

Process calendars are configured by your system administrators to determine your environment's working days and hours. Consider setting the useProcessCalendar parameter to true when you want your calculation to return a date and time within the specified working hours. The return value will be in the calendar's specified timezone.

If you have multiple calendars configured, you can use the processCalendarName parameter to specify the correct calendar configuration to use in your calculation.

Learn how to configure process calendar settings.

Adding increments of time

You can use a combination of years, months, days, hours, minutes, or seconds in your calculation. The calculation will be performed on the largest unit of time (years) to the smallest (seconds). If any of these parameters are 0 or null, it will be ignored in the calculation.

You cannot add negative values in any of these parameters. For example, year: -2 will return an error.

The total amount of time added to the start date cannot exceed 100 years.

Limitations

You cannot use this function in a process event, like a Timer Event or Start Event.

Instead, you should use the calendar functions caladddays() or caladdhours() to add increments of time to a start date in a process event.

Examples

Copy and paste the following examples into an Appian Expression Editor to experiment with this function.

Add date and time values to a single date

1
2
3
4
5
6
7
8
a!addDateTime(
   startDateTime: datetime(2000,1,1,0,0,0),
   months: 1,
   days: 1,
   hours: 1,
   minutes: 1,
   seconds: 1,
)

Returns 2/2/2000 1:01 AM GMT+00:00

Add date and time value to multiple dates

1
2
3
4
5
6
7
8
a!addDateTime(
   startDateTime: {datetime(2000,1,1,0,0,0),datetime(2001,1,1,0,0,0)}
   months: 1,
   days: 1,
   hours: 1,
   minutes: 1,
   seconds: 1,
)

Returns 2/2/2000 1:01 AM GMT+00:00; 2/2/2001 1:01 AM GMT+00:00

Add date and time values using a process calendar

In this example, there are multiple process calendars, so we've specified the default process calendar to use in our calculation. This calendar has working hours defined as weekdays only from 9am to 5pm GMT.

1
2
3
4
5
6
a!addDateTime(
   startDateTime: datetime(2000,2,1,0,0,0), /*Tuesday*/
   days: 5,
   useProcessCalendar: true, 
   processCalendarName: "Default Calendar"
)

Returns 2/8/2000 9:00 AM GMT+00:00

Feature compatibility

The table below lists this function's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Compatible
Sync-Time Custom Record Fields Compatible

Can be used to create a custom record field that only evaluates at sync time.

Real-Time Custom Record Fields Incompatible
Process Reports Incompatible

You cannot use this function to configure a process report.

Process Events Incompatible

You cannot use this function to configure a process event node, such as a start event or timer event.

Open in Github Built: Wed, Dec 07, 2022 (10:13:19 PM)

On This Page

FEEDBACK