Function

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

Subtracts the specified increments of time from 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

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.

Subtracting 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.

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.

Subtract date and time values to a single date

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

Returns 11/29/2000 10:58 PM GMT+00:00

Subtract date and time value to multiple dates

1
2
3
4
5
6
7
8
a!subtractDateTime(
   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 11/29/1999 10:58 PM GMT+00:00; 11/29/2000 10:58 PM GMT+00:00

Subtract 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 1/25/2000 12:00 AM GMT+00:00

Feature compatibility