Implement custom date time format support with configurable NXF_DATE_FORMAT (#6013)

pditommaso · claude · web-flow · commit 163cd37b4264 · 2025-08-14T23:54:02.000+02:00
- Add configurable date formatting via NXF_DATE_FORMAT environment variable
- Support ISO format with timezone (NXF_DATE_FORMAT=iso)
- Default format changed to 'dd-MMM-yyyy HH:mm:ss'
- Add OffsetDateTime support to SysHelper.fmtDate()
- Update all notification templates to use configurable formatting:
  * Email notifications (HTML and text)
  * HTML execution reports
  * ANSI console output
- Add comprehensive test coverage for all date format variations
- Fix template binding to support SysHelper in notification templates


Signed-off-by: Paolo Di Tommaso &lt;paolo.ditommaso@gmail.com&gt;
Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/docs/migrations/25-10.md b/docs/migrations/25-10.md
@@ -29,6 +29,29 @@ workflow {
 
 This syntax is simpler and easier to use with the {ref}`strict syntax <strict-syntax-page>`. See {ref}`workflow-handlers` for details.
 
+<h3>Configurable date and time formatting</h3>
+
+:::{versionadded} 25.07.0-edge
+:::
+
+You can now customize the date and time format used in notifications, reports, and console output using the `NXF_DATE_FORMAT` environment variable. This addresses previous inconsistencies in timestamp representations:
+
+```bash
+# Use ISO format with timezone
+export NXF_DATE_FORMAT=iso
+nextflow run workflow.nf
+# Output: 2016-08-11T09:40:20+02:00
+
+# Use custom format  
+export NXF_DATE_FORMAT="yyyy-MM-dd HH:mm"
+nextflow run workflow.nf
+# Output: 2016-08-11 09:40
+
+# Default format includes seconds
+nextflow run workflow.nf
+# Output: 11-Aug-2016 09:40:20
+```
+
 ## Breaking changes
 
 - The AWS Java SDK used by Nextflow was upgraded from v1 to v2, which introduced some breaking changes to the `aws.client` config options. See {ref}`the guide <aws-java-sdk-v2-page>` for details.
diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
@@ -54,6 +54,11 @@ The following environment variables control the configuration of the Nextflow ru
   :::
 : When `true`, override the container entrypoint with `/bin/bash` (default: `false`).
 
+`NXF_DATE_FORMAT`
+: :::{versionadded} 25.07.0-edge
+  :::
+: Defines the format for date and time representations in notifications and reports. Supports custom formats (e.g., `yyyy-MM-dd HH:mm:ss`) or `iso` for ISO 8601 format with timezone (default: `dd-MMM-yyyy HH:mm:ss`).
+
 `NXF_DEFAULT_DSL`
 : :::{versionadded} 22.03.0-edge
   :::
diff --git a/modules/nextflow/src/main/groovy/nextflow/script/WorkflowNotifier.groovy b/modules/nextflow/src/main/groovy/nextflow/script/WorkflowNotifier.groovy
@@ -22,6 +22,7 @@ import groovy.text.GStringTemplateEngine
 import groovy.transform.CompileStatic
 import groovy.util.logging.Slf4j
 import nextflow.mail.Attachment
+import nextflow.util.SysHelper
 import nextflow.mail.Mail
 import nextflow.mail.Mailer
 import nextflow.mail.Notification
@@ -214,6 +215,8 @@ class WorkflowNotifier {
             map.putAll(variables)
         if( binding )
             map.putAll(binding)
+        // Add SysHelper to template binding so it can be used in templates
+        map.put('SysHelper', SysHelper)
 
         def template = new GStringTemplateEngine().createTemplate(new InputStreamReader(source))
         template.make(map).toString()
diff --git a/modules/nextflow/src/main/groovy/nextflow/trace/AnsiLogObserver.groovy b/modules/nextflow/src/main/groovy/nextflow/trace/AnsiLogObserver.groovy
@@ -23,6 +23,7 @@ import jline.TerminalFactory
 import nextflow.Session
 import nextflow.trace.event.TaskEvent
 import nextflow.util.Duration
+import nextflow.util.SysHelper
 import nextflow.util.Threads
 import org.fusesource.jansi.Ansi
 import org.fusesource.jansi.AnsiConsole
@@ -347,7 +348,7 @@ class AnsiLogObserver implements TraceObserverV2 {
 
         if( session.isSuccess() && stats.progressLength>0 ) {
             def report = ""
-            report += "Completed at: ${new Date(endTimestamp).format('dd-MMM-yyyy HH:mm:ss')}\n"
+            report += "Completed at: ${SysHelper.fmtDate(new Date(endTimestamp))}\n"
             report += "Duration    : ${new Duration(delta)}\n"
             report += "CPU hours   : ${stats.getComputeTimeFmt()}\n"
             report += "Succeeded   : ${stats.succeedCountFmt}\n"
diff --git a/modules/nextflow/src/main/groovy/nextflow/trace/ReportObserver.groovy b/modules/nextflow/src/main/groovy/nextflow/trace/ReportObserver.groovy
@@ -29,6 +29,7 @@ import nextflow.processor.TaskId
 import nextflow.script.WorkflowMetadata
 import nextflow.trace.config.ReportConfig
 import nextflow.trace.event.TaskEvent
+import nextflow.util.SysHelper
 import nextflow.util.TestOnly
 /**
  * Render pipeline report processes execution.
@@ -213,6 +214,8 @@ class ReportObserver implements TraceObserverV2 {
         final tpl_fields = [
             workflow : getWorkflowMetadata(),
             payload : renderPayloadJson(),
+            // Add SysHelper to template binding so it can be used in templates
+            SysHelper : SysHelper,
             assets_css : [
                 readTemplate('assets/bootstrap.min.css'),
                 readTemplate('assets/datatables.min.css')
diff --git a/modules/nextflow/src/main/groovy/nextflow/trace/ReportSummary.groovy b/modules/nextflow/src/main/groovy/nextflow/trace/ReportSummary.groovy
@@ -64,8 +64,6 @@ class ReportSummary {
         }
     }
 
-
-
     /**
      * Hold the summary for each series ie. cpu, memory, time, disk reads, disk writes
      */
diff --git a/modules/nextflow/src/main/resources/nextflow/mail/notification.html b/modules/nextflow/src/main/resources/nextflow/mail/notification.html
@@ -54,12 +54,12 @@ <h2>Execution summary</h2>
     <table cellpadding="4" >
         <tr>
         <td>Launch time</td>
-        <td>${workflow.start.format('dd-MMM-yyyy HH:mm:ss')}</td>
+        <td>${SysHelper.fmtDate(workflow.start)}</td>
         </tr>
 
         <tr>
         <td>Ending time</td>
-        <td>${workflow.complete.format('dd-MMM-yyyy HH:mm:ss')} (duration: ${workflow.duration})</td>
+        <td>${SysHelper.fmtDate(workflow.complete)} (duration: ${workflow.duration})</td>
         </tr>
         
         <tr>
diff --git a/modules/nextflow/src/main/resources/nextflow/mail/notification.txt b/modules/nextflow/src/main/resources/nextflow/mail/notification.txt
@@ -22,8 +22,8 @@ The command used to launch the workflow was as follows:
 
 ** Execution summary **
 
-  Launch time       : ${workflow.start.format('dd-MMM-yyyy HH:mm:ss')}
-  Ending time       : ${workflow.complete.format('dd-MMM-yyyy HH:mm:ss')} (duration: ${workflow.duration})
+  Launch time       : ${SysHelper.fmtDate(workflow.start)}
+  Ending time       : ${SysHelper.fmtDate(workflow.complete)} (duration: ${workflow.duration})
   Total CPU-Hours   : ${workflow.stats.computeTimeFmt ?: '-'}
   Tasks stats       : Succeeded ${workflow.stats.succeedCountFmt}; Cached ${workflow.stats.cachedCountFmt}; Ignored ${workflow.stats.ignoredCountFmt}; Failed ${workflow.stats.failedCountFmt}
   Launch directory  : ${workflow.launchDir}
diff --git a/modules/nextflow/src/main/resources/nextflow/trace/ReportTemplate.html b/modules/nextflow/src/main/resources/nextflow/trace/ReportTemplate.html
@@ -137,7 +137,7 @@ <h4>Workflow execution completed unsuccessfully!</h4>
       <dl>
         <dt>Run times</dt>
         <dd>
-          <span id="workflow_start">${workflow.start.format('dd-MMM-yyyy HH:mm:ss')}</span> - <span id="workflow_complete">${workflow.complete.format('dd-MMM-yyyy HH:mm:ss')}</span>
+          <span id="workflow_start">${SysHelper.fmtDate(workflow.start)}</span> - <span id="workflow_complete">${SysHelper.fmtDate(workflow.complete)}</span>
           (<span id="completed_fromnow"></span>duration: <strong>${workflow.duration}</strong>)
         </dd>
 
diff --git a/modules/nf-commons/src/main/nextflow/util/SysHelper.groovy b/modules/nf-commons/src/main/nextflow/util/SysHelper.groovy
@@ -19,12 +19,14 @@ package nextflow.util
 
 import java.lang.management.ManagementFactory
 import java.text.SimpleDateFormat
+import java.time.OffsetDateTime
 
 import com.sun.management.OperatingSystemMXBean
 import groovy.transform.CompileStatic
 import groovy.transform.Memoized
 import groovy.transform.PackageScope
 import groovy.util.logging.Slf4j
+import nextflow.SysEnv
 import nextflow.file.FileHelper
 /**
  * System helper methods
@@ -37,7 +39,7 @@ class SysHelper {
 
     public static final String DEFAULT_DOCKER_PLATFORM = 'linux/amd64'
 
-    private static String DATE_FORMAT = 'dd-MMM-yyyy HH:mm'
+    private static final String DATE_FORMAT = 'dd-MMM-yyyy HH:mm:ss'
 
     /**
      * Given a timestamp as epoch time convert to a string representation
@@ -66,11 +68,34 @@ class SysHelper {
      *      The formatted date string
      */
     static String fmtDate(Date date, TimeZone tz=null) {
-        def formatter=new SimpleDateFormat(DATE_FORMAT, Locale.ENGLISH)
+        final formatter=new SimpleDateFormat(fmtEnv(), Locale.ENGLISH)
         if(tz) formatter.setTimeZone(tz)
         formatter.format(date)
     }
 
+    /**
+     * Given a {@link java.time.OffsetDateTime} object convert to a string representation
+     * according the {@link #DATE_FORMAT}
+     *
+     * @param dateTime
+     *      The OffsetDateTime to render as a string
+     * @return
+     *      The formatted date string
+     */
+    static String fmtDate(OffsetDateTime dateTime) {
+        // Convert to Date while preserving the original timezone
+        final date = Date.from(dateTime.toInstant())
+        final timezone = TimeZone.getTimeZone(dateTime.getOffset())
+        fmtDate(date, timezone)
+    }
+
+    static private String fmtEnv() {
+        final result = SysEnv.get('NXF_DATE_FORMAT', DATE_FORMAT)
+        return result.toLowerCase() == 'iso'
+            ? "yyyy-MM-dd'T'HH:mm:ssXXX"
+            : result
+    }
+
     /**
      * Read the system uptime as returned by the {@code uptime} Linux tool
      *
@@ -105,7 +130,7 @@ class SysHelper {
     }
 
     static String getBootTimeString() {
-        new SimpleDateFormat(DATE_FORMAT).format(new Date(getBootTimeMillis()))
+        fmtDate(new Date(getBootTimeMillis()))
     }
 
     /**
diff --git a/modules/nf-commons/src/test/nextflow/util/SysHelperTest.groovy b/modules/nf-commons/src/test/nextflow/util/SysHelperTest.groovy
@@ -17,10 +17,16 @@
 package nextflow.util
 
 import java.lang.management.ManagementFactory
+import java.time.Instant
+import java.time.OffsetDateTime
+import java.time.ZoneOffset
 
 import com.sun.management.OperatingSystemMXBean
+import nextflow.SysEnv
 import nextflow.file.FileHelper
 import spock.lang.Specification
+import spock.lang.Unroll
+
 /**
  *
  * @author Paolo Di Tommaso <paolo.ditommaso@gmail.com>
@@ -72,8 +78,12 @@ class SysHelperTest extends Specification {
         SysHelper.hostName == (System.getenv('HOSTNAME') ?: InetAddress.getLocalHost().getHostName())
     }
 
+    @Unroll
     def 'should format date string' () {
         given:
+        def env = dateFormat ? [NXF_DATE_FORMAT:dateFormat] : [:]
+        SysEnv.push(env)
+        and:
         def defLocale = Locale.getDefault(Locale.Category.FORMAT)
         def useLocale = new Locale.Builder().setLanguage(locale).build()
         Locale.setDefault(Locale.Category.FORMAT, useLocale)
@@ -85,11 +95,62 @@ class SysHelperTest extends Specification {
 
         cleanup:
         Locale.setDefault(Locale.Category.FORMAT, defLocale)
+        SysEnv.pop()
 
         where:
-        dateInMilis | locale | expected
-        1470901220000  | 'en' | '11-Aug-2016 09:40'
-        1470901220000  | 'es' | '11-Aug-2016 09:40'
+        dateInMilis    | locale | dateFormat                    | expected
+        1470901220000  | 'en'   | null                          | '11-Aug-2016 09:40:20'
+        1470901220000  | 'es'   | null                          | '11-Aug-2016 09:40:20'
+        and:
+        1470901220000  | 'en'   | 'iso'                         | '2016-08-11T09:40:20+02:00'
+        1470901220000  | 'es'   | 'iso'                         | '2016-08-11T09:40:20+02:00'
+        and:
+        1470901220000  | 'en'   | "yyyy-MM-dd'T'HH:mm:ss.SSS"   | '2016-08-11T09:40:20.000'
+        1470901220000  | 'es'   | "yyyy-MM-dd'T'HH:mm:ss.SSS"   | '2016-08-11T09:40:20.000'
+    }
+
+    def 'should format OffsetDateTime preserving timezone' () {
+        given:
+        SysEnv.push([:])
+        and:
+        def defLocale = Locale.getDefault(Locale.Category.FORMAT)
+        def useLocale = new Locale.Builder().setLanguage('en').build()
+        Locale.setDefault(Locale.Category.FORMAT, useLocale)
+        and:
+        // Create OffsetDateTime with specific timezone +02:00 (epoch time 1470901220000 = 2016-08-11T07:40:20Z)
+        def dateTime = OffsetDateTime.ofInstant(Instant.ofEpochMilli(1470901220000), ZoneOffset.ofHours(2))
+
+        when:
+        String fmt = SysHelper.fmtDate(dateTime)
+        then:
+        // Should format using the original timezone (+02:00), which gives 09:40:20 local time
+        fmt == '11-Aug-2016 09:40:20'
+
+        cleanup:
+        Locale.setDefault(Locale.Category.FORMAT, defLocale)
+        SysEnv.pop()
+    }
+
+    def 'should format OffsetDateTime with ISO format preserving timezone' () {
+        given:
+        SysEnv.push([NXF_DATE_FORMAT: 'iso'])
+        and:
+        def defLocale = Locale.getDefault(Locale.Category.FORMAT)
+        def useLocale = new Locale.Builder().setLanguage('en').build()
+        Locale.setDefault(Locale.Category.FORMAT, useLocale)
+        and:
+        // Create OffsetDateTime with specific timezone +05:00 (epoch time 1470901220000 = 2016-08-11T07:40:20Z)
+        def dateTime = OffsetDateTime.ofInstant(Instant.ofEpochMilli(1470901220000), ZoneOffset.ofHours(5))
+
+        when:
+        String fmt = SysHelper.fmtDate(dateTime)
+        then:
+        // Should preserve the original +05:00 timezone, giving 12:40:20 local time
+        fmt == '2016-08-11T12:40:20+05:00'
+
+        cleanup:
+        Locale.setDefault(Locale.Category.FORMAT, defLocale)
+        SysEnv.pop()
     }
 
 }

Original file line number	Diff line number	Diff line change
`@@ -64,8 +64,6 @@ class ReportSummary {`
`64`	`64`	`}`
`65`	`65`	`}`
`66`	`66`
`67`		`-`
`68`		`-`
`69`	`67`	`/**`
`70`	`68`	`* Hold the summary for each series ie. cpu, memory, time, disk reads, disk writes`
`71`	`69`	`*/`