Date and Time - 6/6 - Conclusion
Let's wrap it up.
Finally, we reached the end of this guide. We did a deep dive, figured out all the details, now we can create the checklist.
When communicating with the external system by timestamps:
- Type: Use Date objects in the codebase (parameters, object fields, variables...).
- GS Reading: Read the GS file using the getValue(s) method. You will get a Date. Use the getTime method on a Date to get the timestamp in milliseconds. Adjust the timestamp value to match the external system timestamp resolution.
- GS Writing: Adjust the timestamp received from the external system to the milliseconds resolution. Convert it to Date. Write the Date to the GS file using the setValue(s) method.
When communicating with the external system by date and/or time strings:
- Type: Use strings in the codebase.
- GS Reading: Read the GS file using the getValue(s) method. You will get a Date. The external system expects the string. Use the GS file time zone to transform the Date to the string.
- GS Writing: Parse the string received from the external system to Date using the GAS project time zone. Convert it to a string with the expected format (GS file column) by using the GAS project time zone. Write a string to the GS file using the setValue(s) method.
Tips and Tricks
- When parsing a string into a Date, it will be executed in the GAS project time zone. "yyyy-MM-dd" format is the exception, it uses the UTC time zone, you'll have to force it to the GAS project time zone (for example: add the dummy time part).
- When parsing the string with two digit year "yy" JavaScript will guess the full year and you will get the years 1950 to 2049. Make sure the expected data don't have a problem with this range, otherwise, ask for the four digit year "yyyy" upstream.
- Try to align the GAS project time zone to the GS file time zone if possible. It will make your reading of the debugger/logger easier.
- GS file preserves the string representation and moves the timestamp when the time zone is changed. That feature is convenient for the end user, just don't be confused when it happens.
Before starting the project or a feature that involves date and time - I stop, go to this checklist, think for a while and make a plan.
It serves me well, you can try the same. If you need the details, they are in the guide. Also, you can read the full guide from time to time if you need to refresh your memory.
Questions, Corrections and Suggestions are appreciated: contact me.
