---
title: "ConvertTo-DateString"
slug: "scripting-convertto-datestring"
updated: 2024-06-10T12:24:42Z
published: 2024-06-10T12:24:42Z
canonical: "help.agilityblue.com/scripting-convertto-datestring"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.agilityblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ConvertTo-DateString

## 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](https://en.wikipedia.org/wiki/ISO_8601). 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).

```powershell
ConvertTo-DateString    
    -DateTime
    -DateTimeOffset
    -TimeZone
    -IncludeTime
```

Returns a string.

## Parameters

| Parameter | Type | Required? | Notes |
| --- | --- | --- | --- |
| DateTime | DateTime object | One of DateTime or DateTimeOffset is required. | For example, provide the results of the `Get-Date` command to use the current date/time. |
| DateTimeOffset | DateTimeOffset object | One of DateTime or DateTimeOffset is required. |  |
| TimeZone | String | No, Defaults to UTC | Changes 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. |
| IncludeTime | Switch | No, Defaults to false | Includes 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

```powershell
# 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:

```none
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
```