[Salesforce]FormatDuration関数について（数式）

初めに

こんにちは、初めまして。
記事を開いていただきありがとうございます。

今日はSalesforceの数式項目で使用できるFORMATDURATION関数についてです。

FORMATDURATION関数とは

FORMATDURATION関数は、日付/時刻の差（＝経過した日数と時間）を計算してくれる関数です。

例えば、2024/1/1 08:30:00 から 2024/1/1 09:00:00までの経過時間を計算するようなことができます。
この場合は「30分」という形で計算されます。
（この場合、実際に戻ってくる値は"0:00:30:00"となります。）

Salesforceのヘルプでは以下のような説明がされています。

関数	説明
FORMATDURATION	日数、または times または dateTimes 間の差を HH:MI:SS として省略可能にした秒数を書式設定します。

コンテキストごとの数式の演算子と関数(help.salesforce.com)

上記リンク先だとFORMATDURATION関数の詳細なリファレンスページへのリンクはありませんでした。

必要な値（引数）

FORMATDURATION関数は２つの日時の差分を計算する関数なので、
FromとToの2つの日付/時刻データが必要となります。

• 最低限必要な値を指定したFORMATDURATION関数
  FORMATDURATION(StartDateTime__c, EndDateTime__c)
  ※StartDateTime__cとEndDateTime__cは日付/時刻形式のカスタム項目です。

帰ってくる値（戻り値）

FORMATDURATION関数の戻り値はテキスト型です。
引数として指定した２つの日時の差（秒単位）を日数＋時刻の形式で返してくれます。

注意ポイント

FORMATDURATION関数で返される値は0:00:00:00で、
時刻形式ではなく、日数＋時刻の形になっています。
そのため、関数の戻り値をそのままTIMEVALUE関数等に渡すことはできません。

余談：
動作検証しているときに、先頭部分の「0:」を見落としており、
時刻に変換できずちょっとハマってしまいました。

• ちなみに関数のリストから引用すると以下の式が挿入されます
  FORMATDURATION(numSeconds[, includeDays] | dateTime/time, dateTime/time)
  numSeconds[, includeDays] の部分に関しては、これがどういった挙動を示すか、
  細かい動作については分かっていません。
  （リファレンスのリンクをご存じの方、教えてください。）

最後に

日付時刻の計算は皆さんが独自の計算式で対応は可能されることも多いと思いますが、
始終の長さを求めたい場合にはFORMATDURATION関数も思い出してみてください。

テキストのままだとデータとして再利用が難しいですが、
独自の計算式で対応していたところを関数で対応できれば記述が明確になるので、
あるとうれしい関数かなと思います。