Transforming text & dates

Transformation helpers change the structure or content of a value — not just how it looks.

---

Concat

Combines any number of values into a single string.

concat value1 value2 ...

Example

{{concat vessel.name ' — ' portCall.port}}    => Ocean Star — Rotterdam
{{concat 'ETA: ' portCall.eta}}               => ETA: 2024-03-10

---

Coalesce

Returns the first non-null, non-empty value from its arguments. The strings null and undefined are also treated as empty.

coalesce value1 value2 ...

Argument	Type	Description
value1, ...	any	Values evaluated in order; the first non-empty one is returned.

Example

{{coalesce portCall.berth 'TBA'}}              => TBA  (when berth is null or empty)
{{coalesce portCall.agent vessel.defaultAgent}} => Maas Bulk Agency
{{coalesce 'Hamburg' 'Rotterdam'}}             => Hamburg

---

Brackets

Wraps a value in parentheses, with optional prefix and suffix text placed inside the brackets.

brackets value prefix suffix

Argument	Type	Description
value	string	The value to wrap.
prefix	string	Optional: text before the value, inside the brackets.
suffix	string	Optional: text after the value, inside the brackets.

Example

{{brackets portCall.berth}}              => (Berth 7)
{{brackets portCall.berth 'Berth: '}}    => (Berth: 7)
{{brackets cargo.tonnage '' ' MT'}}      => (45000 MT)

---

Replace

Replaces every occurrence of a substring with a replacement string.

replace originalText replaceMatch replaceWith

Argument	Type	Description
originalText	string	The string to search inside.
replaceMatch	string	The substring to find.
replaceWith	string	The replacement string.

Example

{{replace portCall.remarks 'TBC' 'Confirmed'}}

Input: 'ETA TBC, berth TBC' → Output: 'ETA Confirmed, berth Confirmed'

---

Replace (regular expression)

Like replace, but the search pattern is a regular expression.

regexReplace originalText replaceMatch replaceWith

Argument	Type	Description
originalText	string	The string to search inside.
replaceMatch	string	Regular expression pattern to find.
replaceWith	string	The replacement string.

Example

{{regexReplace portCall.berth '[0-9]+' 'TBA'}}

Input: 'Berth 12' → Output: 'Berth TBA'

---

Substring

Extracts a portion of a string by start index and optional length.

substring startIndex length

Argument	Type	Description
startIndex	number	Zero-based starting position.
length	number	Optional: number of characters to extract. Omit to go to end of string.

Example

{{substring vessel.imoNumber 2 7}}    => 9876543  (chars 2–8 of 'IMO9876543')
{{substring voyage.reference 0 4}}   => 2024

---

Trim

Removes whitespace (or a specified character) from both ends of a string.

trim

Example

{{trim portCall.remarks}}                      => 'Berth 7 confirmed'
{{trim portCall.berth '.'}}                    => 'Berth 7'

---

Truncate

Shortens a string to a maximum length. When an ellipsis is provided, the total output length (including the ellipsis) stays within maxLength.

truncate value maxLength ellipsis

Argument	Type	Description
value	string	The string to truncate.
maxLength	number	Maximum output length (including ellipsis if provided).
ellipsis	string	Optional: suffix appended when truncated, e.g. .... Defaults to no suffix.

Example

{{truncate vessel.name 8}}           => 'Ocean St'
{{truncate vessel.name 8 '...'}}     => 'Ocean...'
{{truncate 'LNG' 10 '...'}}          => 'LNG'

---

Newline

Replaces a specified string with line breaks.

newline stringToReplace

Example

{{newline portCall.itinerary ', '}}

Input: 'Amsterdam, Rotterdam, Antwerp'

Output:

Amsterdam
Rotterdam
Antwerp

---

Text to HTML

HTML-encodes a string and converts \r\n line breaks into <br/> tags. Useful when displaying user-entered plain text inside HTML templates.

textToHtml text

Argument	Type	Description
text	string	The plain-text string to transform.

Example

{{textToHtml portCall.remarks}}

Input: 'Berth <7>\r\nConfirmed' → Output: Berth &lt;7&gt;<br/>Confirmed

---

Zero if null

Replaces a null number value with 0 instead of an empty string (which is the default engine behaviour).

zeroIfNull

Example

{{zeroIfNull cargo.tonnage}}    => 45000   (or 0 if null)
{{zeroIfNull null}}             => 0

---

Encrypt

Generates an encrypted, reversible string — used primarily for passing unreadable tokens to the SHIPM8 backend, not for storing sensitive data.

encrypt seed validityInHours

Argument	Type	Description
seed	string	Optional: seed that directs the encryption mechanism.
validityInHours	number	Optional: hours before the encrypted token expires.

Example

{{encrypt voyage.reference 'shipm8' 24}}    => 'SB25ibaSIDB3i3u0sa8=='

---

Date — add

Adds or subtracts a time amount from a date. Output format is always dd-MM-yyyy HH:mm.

dateAdd date amount type

Argument	Type	Description
date	string	The date to adjust.
amount	number	Amount to add; use a negative value to subtract.
type	string	Unit of time: d / day / days, H / hour / hours, m / minute / minutes.

Example

{{dateAdd vessel.eta 2 'days'}}       => 12-03-2024 14:00
{{dateAdd vessel.eta 6 'hours'}}      => 10-03-2024 20:00
{{dateAdd vessel.eta -30 'minutes'}}  => 10-03-2024 13:30

---

Date — from UTC

Converts a UTC datetime to a local datetime in the specified timezone (or the server's local timezone if omitted). The input is always treated as UTC.

dateFromUtc date timezoneId format

Argument	Type	Description
date	string	The UTC datetime to convert.
timezoneId	string	Optional: Windows timezone ID, e.g. W. Europe Standard Time. Defaults to server local.
format	string	Optional: output format. Defaults to dd-MM-yyyy HH:mm.

Example

{{dateFromUtc vessel.etaUtc}}
  => 10-03-2024 16:00  (server in W. Europe Summer Time, UTC+2)

{{dateFromUtc vessel.etaUtc 'W. Europe Standard Time'}}
  => 10-03-2024 16:00

{{dateFromUtc vessel.etaUtc 'Eastern Standard Time' 'HH:mm'}}
  => 10:00

---

Date — to UTC

Converts a local datetime in the specified timezone to UTC.

dateToUtc date timezoneId format

Argument	Type	Description
date	string	The local datetime to convert.
timezoneId	string	Optional: Windows timezone ID of the input date. Defaults to server local.
format	string	Optional: output format. Defaults to dd-MM-yyyy HH:mm.

Example

{{dateToUtc vessel.eta}}
  => 10-03-2024 12:00  (server in W. Europe Summer Time, UTC+2)

{{dateToUtc vessel.eta 'W. Europe Standard Time'}}
  => 10-03-2024 13:00

{{dateToUtc vessel.eta 'Eastern Standard Time' 'HH:mm'}}
  => 19:00

---

Time — add

Adds or subtracts a time amount from a timespan value (e.g. 14:00:00).

timeAdd time amount type

Argument	Type	Description
time	string	Timespan string, e.g. 14:00:00.
amount	number	Amount to add; use a negative value to subtract.
type	string	Unit of time: H / hour / hours, m / minute / minutes.

Example

{{timeAdd vessel.berthingTime 2 'hours'}}     => 16:00:00
{{timeAdd vessel.berthingTime 45 'minutes'}}  => 14:45:00

---

Timeline

Expands an array of date-ranged items into a timeline — one row per interval period covered. This is a block helper.

timeline inputArray dateFrom dateTo interval outputFieldKey outputFormat appendData

Argument	Type	Description
inputArray	array	The array to expand.
dateFrom	string	Field name for the start date.
dateTo	string	Field name for the end date.
interval	string	hourly, daily, monthly, quarterly, or yearly.
outputFieldKey	string	Name of the field added to each output item containing the timeline key.
outputFormat	string	Date format for the timeline key.
appendData	string	Optional: fillgap creates empty records for intervals with no matching item.

Example

{{timeline portCalls 'eta' 'etd' 'daily' 'timelineDate' 'dd-MM-yyyy'}}
  {{#each this}}
    {{timelineDate}} -> {{port}}
  {{/each}}
{{/timeline}}

Data:

{
  "portCalls": [
    { "eta": "2024-03-10T08:00", "etd": "2024-03-11T18:00", "port": "Rotterdam" },
    { "eta": "2024-03-12T08:00", "etd": "2024-03-13T12:00", "port": "Antwerp"   }
  ]
}

Result:

10-03-2024 -> Rotterdam
11-03-2024 -> Rotterdam
12-03-2024 -> Antwerp
13-03-2024 -> Antwerp