str2datetime in x++

In Dynamics 365 Finance and Operations (D365FO), handling dates and times accurately is critical when working with data transformations, reporting, and integrations. One of the core utilities provided in X++ for this purpose is the str2datetime function, which allows developers to take a plain string representation of a date and time and convert it into a utcdatetime value. This is particularly useful when importing or parsing data from external systems, user inputs, or integrations where dates may be delivered as formatted text.

str2Datetime Function: Generates a utcdatetime value from the specified string of date and time information. Its declaration follows this format:

utcdatetime str2datetime(str text, int sequence);

You use the function to convert a string into a utcdatetime value, and the second parameter (sequence) is what makes the conversion flexible. This integer tells the system the order in which the date elements appear—day, month, and year. For example, a sequence of 123 can represent day/month/year depending on the locale or formatting rules you’re working with. Here’s a simple example:

static void Demo_str2datetime(Args _args)
{
    str strDateTime = "18/03/2019 03:06:00 pm";
    utcdatetime utcDT = str2datetime(strDateTime, 123);
    info(strFmt("UTC Date Time: %1", utcDT)); 
    // Output: UTC Date Time: 3/18/2019 3:06:00 pm
}

This demonstrates how a properly formatted string is interpreted into a utcdatetime, which is time zone-agnostic and consistent across the system.

Important Considerations

• Time Component: The function requires both a date and a time in the input string. If you only need to work with a date, you should use str2date() instead.
• Sequence Parameter: This is crucial because it tells the system how to interpret the string. If the sequence doesn’t match the format of the string, you’ll either get the wrong value or an empty result.
• Return Type: The result is a utcdatetime, specifically Microsoft.Dynamics.Ax.Xpp.AxShared.utcdatetime. This type is designed to remain unaffected by time zones, making it ideal for business data that must be consistent across regions.

In some contexts, you might also encounter PredefinedFunctions.Str2Datetime(String, Int32), which is the underlying .NET method exposed to X++. The PredefinedFunctions class is a container of static helper functions that act as bridges between .NET and X++ functionality, giving you access to core framework-level utilities like date, string, and number conversions.

This function is particularly important when sending or receiving date-time values between .NET and X++. For example, when passing a datetime field through OData, it travels as an Edm.DateTime value, which must often be converted to or from a utcdatetime within X++ to remain consistent.

Related Function: date2str

While str2datetime converts a string to a utcdatetime, the date2str x++ d365fo function performs the reverse for date values. In D365FO X++, date2str allows you to specify the order of day, month, and year along with formatting details such as separators and digit lengths. For instance, you can generate strings like YYYY-MM-DD or DD/MM/YYYY depending on your parameters. To respect user regional settings, date2strUsr is often used, with -1 passed as a parameter to adopt default regional preferences automatically.

Together, str2datetime and date2str provide developers with robust tools to handle the parsing and formatting of date and time values in Dynamics 365, making sure that integrations, user interfaces, and business processes all operate with reliable and properly formatted temporal data.