Contents x
    ConvertTo-DateString
    • 2 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Contents

    ConvertTo-DateString

    • 2 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Article summary

    Summary

    This is a convenience command that converts a DateTime or DateTimeOffset to a string representation that Agility Blue expects for any date property.

    Agility Blue expects dates with time zone offsets formatted using the ISO 8601 standard. This command will convert the provided date/time to the following string format representations:

    • Date (without time included): yyyy-MM-ddK
    • Date (with time included): yyyy-MM-ddTHH:mm:ssK

    For instance, the date "November 16th, 2023 at five o'clock PM" would become formatted as "2023-11-16T17:00:00-06:00" using the ISO 8601 format. Breaking down the format:

    • 2023-11-16: The date part, in the format of year-month-day.
    • T: A separator that indicates the start of the time part.
    • 17:00:00: The time part, in the format of hours:minutes:seconds (can sometimes be followed by a fractional second component).
    • -06:00: This represents the time zone offset from UTC. In this case, it indicates that the time is 6 hours behind UTC. This part may sometimes be represented as the letter "Z" in place of "-00:00", or Coordinated Universal Time (UTC).
    ConvertTo-DateString    
    -DateTime
    -DateTimeOffset
    -TimeZone
    -IncludeTime

    Returns a string.

    Parameters

    ParameterTypeRequired?Notes
    DateTimeDateTime objectOne of DateTime or DateTimeOffset is required.For example, provide the results of the `Get-Date` command to use the current date/time.
    DateTimeOffsetDateTimeOffset objectOne of DateTime or DateTimeOffset is required.
    TimeZoneStringNo, Defaults to UTCChanges the provided date/time to a specific time zone that the formatted string shows. For example "Central Standard Time", "Eastern Standard Time". Daylight savings will be automatically applied depending on the provided date/time.
    IncludeTimeSwitchNo, Defaults to falseIncludes the time part in the formatted string. It's recommended that you include this switch for best date/time precision, even if the field is date-only.

    Examples

    Convert a date/time object to a string

    # Get the current date and time. This will always be the UTC time.
$currentDateTime = Get-Date

Write-Output "The current system date/time is: $($currentDateTime)"

# Use the ConvertTo-DateString command to convert the date to a format that can be used
# with Agility Blue date fields. Note that it is a good practice to include the time portion
# for the best percision, even if fields are displayed as date-only.
$date = ConvertTo-DateString -DateTime $currentDateTime -IncludeTime

Write-Output "The AB formatted date/time is: $($date)"

# Use the ConvertTo-DateString command to convert the date to a specific time zone:
$date = ConvertTo-DateString -DateTime $currentDateTime -TimeZone "Central Standard Time" -IncludeTime

Write-Output "The AB formatted date/time in Central Standard Time is: $($date)"

# Or the pacific time zone:
$date = ConvertTo-DateString -DateTime $currentDateTime -TimeZone "Pacific Standard Time" -IncludeTime

Write-Output "The AB formatted date/time in Pacific Standard Time is: $($date)"

    Execution results:

    The current system date/time is: 04/18/2024 13:41:50
The AB formatted date/time is: 2024-04-18T13:41:50+00:00
The AB formatted date/time in Central Standard Time is: 2024-04-18T08:41:50-05:00
The AB formatted date/time in Pacific Standard Time is: 2024-04-18T06:41:50-07:00
    What's Next