formatDateTimeStr Integration Builder Utility Script

Context

As of the time of this writing, the internal EcmaScript engine does not support all of the nice formatting options available with JavaScript Date objects like Date.toLocaleString/toLocaleDateString/toLocaleTimeString.  The newer engines support an optional JSON array of control flags that let one decide how to convert a date object to a string.  Well, until the engine we embed supports those, I needed to convert an ISO date string into a human readable, and/or text-to-speech pronounceable version.  The following script intends to satisfy that need.

Usage

// Create "speakable" version of the reported date and time
trigger.properties.xM_Reported_Date = formatDateTimeStr( incidentReportedDate, false, true, " " );
console.log("trigger.properties.xM_Reported_Date = [" + trigger.properties.xM_Reported_Date + "]");

// Setup Time of Event value
var tzOffset = getTzOffset( incidentReportedDate );
trigger.properties.xM_Event_Time = formatDateTimeStrTZ( new Date(), tzOffset, true, false, ":" );
console.log("trigger.properties.xM_Event_Time = [" + trigger.properties.xM_Event_Time + "]");

Code

/** 
 * ---------------------------------------------------------------------------------------------------------------------
 * formatDateTimeStr
 *
 * inputTimestamp - String - A Date Time String as from the XML
 * e.g. 2016-08-14T11:58:24-05:00"
 * includeYear - Boolean - If true, append the year to the date portion
 * includeAt - Boolean - If true, put the literal phrase '"at", '' before the time value
 * timeSep - String - The character to put between the hours and minutes value
 * 
 * Return a Text-To-Speech compatible string representing the Day, Month, Date, hour, minutes and am/pm
 * e.g Sunday, August 14th, "at", 11 58 AM (..., false, true, " ")
 * e.g. Sunday, August 14th, 2016, 11:58 AM (..., true, false, ":")
 * ---------------------------------------------------------------------------------------------------------------------
 */
function formatDateTimeStr(inputTimestamp, includeYear, includeAt, timeSep )
{
 console.log("formatDateTimeStr - inputTimestamp: [" + inputTimestamp + "]");

 // Parse out the timezone offset value
 var tzOffset = getTzOffset( inputTimestamp );
 console.log("formatDateTimeStr - tzOffset = [" + tzOffset + "]");
 
 // Convert the string to a date object, which autoconverts to UTC
 var d0 = new Date(inputTimestamp);
 var utcValue = d0.valueOf();
 console.log("formatDateTimeStr - utcValue = [" + utcValue + "]");
 
 // Adjust the time to make it relative to the originating timezone offset
 utcValue += tzOffset;
 console.log("formatDateTimeStr - Updated utcValue = [" + utcValue + "]");
 var d = new Date(utcValue);

 // Start to create the literal date string
 var dateStr = getDayName(d.getDay()) + ", " + 
 getMonthName(d.getMonth()) + " " + 
 ordinal_suffix_of(d.getDate()) + ", ";
 if (includeYear)
 {
 dateStr += d.getFullYear() + ", ";
 }
 if (includeAt)
 {
 dateStr += "\"at\", ";
 }
 console.log("formatDateTimeStr - First part of dateStr = [" + dateStr + "]");
 
 // Convert to AM/PM based time
 var hours = d.getHours();
 var ampm = (hours >= 12)?"PM":"AM";
 var hourStr = "12";
 if (hours > 12)
 {
 hourStr = "" + (hours - 12);
 }
 else if ((hours > 0) && (hours < 12))
 {
 hourStr = "" + hours;
 }
 var minuteStr = (d.getMinutes() > 10) ? ""+d.getMinutes() : "0"+d.getMinutes();
 var timeStr = hourStr + timeSep + minuteStr + " " + ampm;
 console.log("formatDateTimeStr - timeStr: [" + timeStr + "]");
 
 var result = dateStr + timeStr;
 console.log("formatDateTimeStr - result: [" + result + "]");

 return result;
 
}


/** 
 * ---------------------------------------------------------------------------------------------------------------------
 * getTzOffset
 *
 * Accepts a Date Time String as from the XML
 * 
 * Return a numeric value representing the timezone offset from UTC
 * ---------------------------------------------------------------------------------------------------------------------
 */
function getTzOffset( inputTimestamp )
{
 console.log("getTzOffset - inputTimestamp: [" + inputTimestamp + "]");

 // First separate the date from the time
 var tsParts = inputTimestamp.split("T");
 console.log("getTzOffset - tsParts = [" + tsParts.join(" | ") + "]");
 
 // Parse out the timezone offset value
 var tzOffset = 0;
 if (tsParts[1].indexOf("+") >= 0) 
 {
 var tParts = tsParts[1].split("+");
 var tzo = tParts[1].split(":");
 var tzoHours = Number(tzo[0]);
 var tzoMinutes = Number(tzo[1]);
 tzOffset = (((tzoHours * 60) + tzoMinutes) * 60) * 1000;
 }
 else
 {
 var tParts = tsParts[1].split("-");
 var tzo = tParts[1].split(":");
 var tzoHours = Number(tzo[0]);
 var tzoMinutes = Number(tzo[1]);
 tzOffset = ((((tzoHours * 60) + tzoMinutes) * 60) * 1000) * -1;
 }
 console.log("getTzOffset - tzOffset = [" + tzOffset + "]");
 
 return tzOffset;
}


/**
 * ---------------------------------------------------------------------------------------------------------------------
 * getMonthName
 *
 * Returns a string containing the name of the month based on the ordinal value passed in
 * 0 = January
 * 
 * ---------------------------------------------------------------------------------------------------------------------
 */
function getMonthName(monthNo)
{
 var monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
 return monthNames[monthNo];
}


/**
 * ---------------------------------------------------------------------------------------------------------------------
 * getDayName
 *
 * Returns a string containing the name of the day based on the ordinal value passed in
 * 0 = Sunday
 * 
 * ---------------------------------------------------------------------------------------------------------------------
 */
function getDayName(dayNo)
{
 var dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 return dayNames[dayNo];
}


/**
 * ---------------------------------------------------------------------------------------------------------------------
 * ordinal_suffix_of
 *
 * Returns a string that would be the proper speakable suffix for a given integral value
 *
 * st is used with numbers ending in 1 (e.g. 1st, pronounced first)
 * nd is used with numbers ending in 2 (e.g. 92nd, pronounced ninety-second)
 * rd is used with numbers ending in 3 (e.g. 33rd, pronounced thirty-third)
 * As an exception to the above rules, all the "teen" numbers ending with 11, 12 or 13 use -th (e.g. 11th, pronounced eleventh, 112th, pronounced one hundred [and] twelfth)
 * th is used for all other numbers (e.g. 9th, pronounced ninth).
 *
 * @ref http://stackoverflow.com/questions/13627308/add-st-nd-rd-and-th-ordinal-suffix-to-a-number
 * ---------------------------------------------------------------------------------------------------------------------
 */
function ordinal_suffix_of(i) 
{
 var j = i % 10,
 k = i % 100;
 if (j == 1 && k != 11) 
 {
 return i + "st";
 }
 if (j == 2 && k != 12) 
 {
 return i + "nd";
 }
 if (j == 3 && k != 13) 
 {
 return i + "rd";
 }
 return i + "th";
}


/** 
 * ---------------------------------------------------------------------------------------------------------------------
 * formatDateTimeStrTZ
 *
 * Accepts a Date Time Object and an integral timezone offest representing +/- milliseconds from UTC

 * inputDate - Date - An initialized Date Object
 * tzOffset - Integer - A value representing the number of milliseconds +/- from UTC that this date represents
 * includeYear - Boolean - If true, append the year to the date portion
 * includeAt - Boolean - If true, put the literal phrase '"at", '' before the time value
 * timeSep - String - The character to put between the hours and minutes value
 * 
 * Return a Text-To-Speech compatible string representing the Day, Month, Date, hour, minutes and am/pm
 * e.g Sunday, August 14th, "at", 11 58 AM (..., false, true, " ")
 * e.g. Sunday, August 14th, 2016, 11:58 AM (..., true, false, ":")
 * ---------------------------------------------------------------------------------------------------------------------
 */
function formatDateTimeStrTZ(inputDate, tzOffset, includeYear, includeAt, timeSep )
{
 console.log("formatDateTimeStrTZ - inputTimestamp: [" + inputDate + "]");

 // Display the timezone offset value
 console.log("formatDateTimeStrTZ - tzOffset = [" + tzOffset + "]");
 
 // Convert the string to a date object, which autoconverts to UTC
 var utcValue = inputDate.valueOf();
 console.log("formatDateTimeStrTZ - utcValue = [" + utcValue + "]");
 
 // Adjust the time to make it relative to the originating timezone offset
 utcValue += tzOffset;
 console.log("formatDateTimeStrTZ - Updated utcValue = [" + utcValue + "]");
 var d = new Date(utcValue);

 // Start to create the literal date string
 var dateStr = getDayName(d.getDay()) + ", " + 
 getMonthName(d.getMonth()) + " " + 
 ordinal_suffix_of(d.getDate()) + ", ";
 if (includeYear)
 {
 dateStr += d.getFullYear() + ", ";
 }
 if (includeAt)
 {
 dateStr += "\"at\", ";
 }
 console.log("formatDateTimeStrTZ - First part of dateStr = [" + dateStr + "]");
 
 // Convert to AM/PM based time
 var hours = d.getHours();
 var ampm = (hours >= 12)?"PM":"AM";
 var hourStr = "12";
 if (hours > 12)
 {
 hourStr = "" + (hours - 12);
 }
 else if ((hours > 0) && (hours < 12))
 {
 hourStr = "" + hours;
 }
 var minuteStr = (d.getMinutes() > 10) ? ""+d.getMinutes() : "0"+d.getMinutes();
 var timeStr = hourStr + timeSep + minuteStr + " " + ampm;
 console.log("formatDateTimeStrTZ - timeStr: [" + timeStr + "]");
 
 var result = dateStr + timeStr;
 console.log("formatDateTimeStrTZ - result: [" + result + "]");

 return result;
 
}