Formatting or Parsing Date & DateTime in Salesforce
Over my career I’ve done a number of things, from ColdFusion then developing printer drivers, to .NET, PHP, Dynamics CRM, and now Salesforce, while playing around with things like python and android development in my spare time. I’m not sure why, but I’ve never had as much of a problem with Date Formats anywhere else as I have with Salesforce.
I think part of this is due to the fact that DateTime objects were rarely really needed in my work during my other Salesforce gigs, but it seems to be a more recurring necessity now that I’m in Fintech. I reached a point earlier this week where I had accumulated too much “personal technical debt”; that is, I got sick of hacking my way through date formats each time the need arose, and decided it was time to learn once and for all what I should have learned five years ago!
Ideally, you’re binding to variables, but there are times when you need a text representation, such as queries or integrations with third party APIs. That’s the motivation I’ve got for finally getting this down.
The first option I stumbled across – and I think I’ve actually seen this used in code written by colleagues here – is JSON.serialize(). This would look something like:
system.debug(JSON.serialize(Datetime.now()));
This works, but my issue with this is your string will actually be wrapped in double quotes – perhaps not a big problem if you’re simply outputting information to the debugger as in this example, but if you’re using the string elsewhere it may not be desirable.
A less graceful way, but something that gives you the most control, is to use one of the Datetime.format() methods. This is my preferred option. The DateTime class gives a number of methods we can use to format dates:
- format(dateFormatString)
- format(dateFormatString, timezone)
- formatGmt(dateFormatString)
- formatLong()
I’ve become a fan of the formatGmt(dateFormatString) method because it seems the easiest – do everything in one timezone then display based on user locale settings.
What I’ve settled on as a preferred option, because it works, is
system.debug(Datetime.now().formatGMT(‘yyyy-MM-dd\’T\’HH:mm:ss.SSS\’Z\”));
and when I need to format this for display, it’s a cinch to do so!
That got me thinking about other DateFormatStrings available in Salesforce and how advanced you can get with them. The answer: you can get quite complex!
Based on the Java SimpleDateFormat, Salesforce understands a wide range of codes:
| Letter | Date or Time Component | Presentation | Examples |
|---|---|---|---|
| G | Era designator | Text | AD |
| y | Year | Year | 1996; 96 |
| Y | Week year | Year | 2009; 09 |
| M | Month in year (context sensitive) | Month | July; Jul; 07 |
| L | Month in year (standalone form) | Month | July; Jul; 07 |
| w | Week in year | Number | 27 |
| W | Week in month | Number | 2 |
| D | Day in year | Number | 189 |
| d | Day in month | Number | 10 |
| F | Day of week in month | Number | 2 |
| E | Day name in week | Text | Tuesday; Tue |
| u | Day number of week (1 = Monday, …, 7 = Sunday) | Number | 1 |
| a | Am/pm marker | Text | PM |
| H | Hour in day (0-23) | Number | 0 |
| k | Hour in day (1-24) | Number | 24 |
| K | Hour in am/pm (0-11) | Number | 0 |
| h | Hour in am/pm (1-12) | Number | 12 |
| m | Minute in hour | Number | 30 |
| s | Second in minute | Number | 55 |
| S | Millisecond | Number | 978 |
| z | Time zone | General time zone | Pacific Standard Time; PST; GMT-08:00 |
| Z | Time zone | RFC 822 time zone | -0800 |
| X | Time zone | ISO 8601 time zone | -08; -0800; -08:00 |
These patterns are typically repeated & combined, and their number determines the exact presentation based on the list of rules outlined in the Javadocs.
That gives you the power to come up with combinations such as the following:
| Date and Time Pattern | Result |
|---|---|
| “yyyy.MM.dd G ‘at’ HH:mm:ss z” | 2001.07.04 AD at 12:08:56 PDT |
| “EEE, MMM d, ”yy” | Wed, Jul 4, ’01 |
| “h:mm a” | 12:08 PM |
| “hh ‘o”clock’ a, zzzz” | 12 o’clock PM, Pacific Daylight Time |
| “K:mm a, z” | 0:08 PM, PDT |
| “yyyyy.MMMMM.dd GGG hh:mm aaa” | 02001.July.04 AD 12:08 PM |
| “EEE, d MMM yyyy HH:mm:ss Z” | Wed, 4 Jul 2001 12:08:56 -0700 |
| “yyMMddHHmmssZ” | 010704120856-0700 |
| “yyyy-MM-dd’T’HH:mm:ss.SSSZ” | 2001-07-04T12:08:56.235-0700 |
| “yyyy-MM-dd’T’HH:mm:ss.SSSXXX” | 2001-07-04T12:08:56.235-07:00 |
| “YYYY-‘W’ww-u” | 2001-W27-3 |
Click through the link above to peruse the rules from the Javadocs. As I said, I always hacked my way around date formats but seeing the underlying rules for formatting and parsing really helped clear things up for me.
And finally, remember Salesforce has a list of Date Literals you can use as well – a definite time-saver for anybody working with dates!