変数とヘルパー関数

変数を使用して、フォームと Flows 内のユーザーデータにアクセスして変換する方法を学びます。

変数を使うと、フォーム や Flows に含まれるデータにアクセスして、カスタムのビジネスロジックや自動化を実現できます。

変数を使用する際の基本的な注意点は次のとおりです。

• 変数は波かっこ {{ variable }} で囲みます。
• 変数が存在しない場合や解決できない場合は、undefined 変数と同じように扱われます。
• null または undefined の変数を扱うには、null 合体演算子を使用できます。たとえば {{fields.foo ?? fields.bar}} のように記述します。

​

利用可能な変数

Forms や Flows では、顧客から収集したデータを参照したり変換したりするために、さまざまな種類の変数を使用できます。

Variable	Syntax	Where	Description
Context	{{context.*}}	Forms / Flows	現在のトランザクションのコンテキストデータを参照します
Form fields	{{fields.*}}	Forms / Flows	フォームフィールドや非表示フィールドのデータを参照します
Shared variables	{{vars.*}}	Forms / Flows	共有変数として保存されているデータを参照します
Flow actions output	{{actions.*}}	Flows	前のフローアクションの出力レスポンスのデータを参照します
Helper functions	{{functions.*}}	Forms / Flows	データを変換するためのヘルパー関数

​

コンテキスト変数

フォーム と Flows は、現在のトランザクションからコンテキスト変数を自動的に引き継ぎます。以下のコンテキスト変数を利用できます。

• user オブジェクト。以下のプロパティを利用できます。

  • user.user_id
  • user.username
  • user.name
  • user.given_name
  • user.family_name
  • user.nickname
  • user.email
  • user.email_verified
  • user.phone_number
  • user.phone_verified
  • user.picture
  • user.user_metadata
  • user.app_metadata
  • user.created_at
  • user.updated_at
  • user.last_password_reset
  • user.identities

• organization オブジェクト。以下のプロパティを利用できます。

  • organization.id
  • organization.name
  • organization.display_name
  • organization.metadata

• client オブジェクト。以下のプロパティを利用できます。

  • client.client_id
  • client.name

• tenant オブジェクト。以下のプロパティを利用できます。

  • tenant.name

• transaction オブジェクト。以下のプロパティを利用できます。

  • transaction.state
  • transaction.correlation_id

• custom_domain オブジェクト。以下のプロパティを利用できます。

  • custom_domain.domain
  • custom_domain.domain_metadata

コンテキストオブジェクトの例

{
  "user": {
    "user_id": "auth0|658409...",
    "name": "[e-mail]",
    "nickname": "ana",
    "email": "[e-mail]",
    "email_verified": true,
    "picture": "https://s.gravatar.com/avatar/8eb1b522f6...",
    "user_metadata": {},
    "app_metadata": {},
    "created_at": "2023-12-21T09:46:40.487Z",
    "updated_at": "2024-05-07T10:44:26.271Z",
    "last_password_reset": "2023-12-21T09:49:08.932Z",
    "identities": [
      {
        "user_id": "6584...",
        "isSocial": false,
        "provider": "auth0",
        "connection": "Username-Password-Authentication"
      }
    ]
  },
  "client": {
    "client_id": "xpeg5...",
    "name": "My App"
  },
  "tenant": {
    "name": "tenant-testing"
  },
  "transaction": {
    "state": "hKFo2SBId2M0..."
  },
  "custom_domain": {
    "domain": "example.com",
    "domain_metadata": {
      "key": "value"
    }
  }
}

たとえば、{{context.user.user_id}} は user オブジェクトの user_id を参照しています。

​

フォームフィールド変数

フィールド変数には、フォーム内の入力フィールドでユーザーが入力したデータと、非表示フィールドのデータが含まれます。各フィールドのデータは、フィールドの種類によって異なります。たとえば、{{fields.first_name}} は、ID が first_name のフィールドの入力値を参照します。

​

フロー出力アクション変数

フローアクションが実行されると、後続のアクションから参照できる出力オブジェクトのレスポンスが生成されます。たとえば、{{actions.generate_otp.code}} は、ID が generate_otp のアクションの出力コードを参照します。

​

共有変数

後続の Flows や、同じトランザクション内のフォームコンポーネントで共有するための変数を保存できます。共有変数は一時的なもので、特定のフォームジャーニーに関連付けられます。これらの値にアクセスできるのは、そのジャーニー内のみです。たとえば、{{vars.external_id}} は、ID が external_id の共有変数の値を参照します。

共有変数:

• は内部 (サーバー側) で管理され、ブラウザー (クライアント側) には公開されません。
• フォームコンポーネント内で共有変数を参照した場合、解決されてブラウザーに公開されることがあります。
• 機微な情報が含まれている可能性があるため、不要または意図しない公開を避けるために、共有変数にアクセスする際は注意してください。

​

ヘルパー関数

ヘルパー関数を使うと、データを変換したり、簡単な処理を行ったりできます。たとえば、{{functions.toString(fields.privacy_policies)}} は、ID が privacy_policies のフィールドの値を toString() 関数で変換します。

使用できるヘルパー関数は次のとおりです。

関数	説明	例
toArray(value)	値を配列に変換します。	{{ functions.toArray('abc') }} // ['abc']
toBoolean(value)	値を真偽値に変換します。	{{ functions.toBoolean(1) }} // true<br /><br />\{\{ functions.toBoolean(0) }} // false
length(value)	引数の値の長さを返します。	{{ functions.length('auth0') }} // 5
mask(value)	Executionsで値が表示されないようにマスクします。	{{ functions.mask('my_awesome_secret') }} // ███
toNumber(value)	値を数値に変換します。	{{ functions.toNumber('123') }} // 123
random(min, max, [boolean])	min 以上 max 以下の範囲のランダムな数値を返します。	{{ functions.random(0, 6) }} // 4 <br /><br />\{\{ functions.random(0, 6, true) }} // 3.8523497...
slice(value, start, end)	開始インデックスから終了インデックスまでの、値の配列または文字列の一部を返します。	{{ functions.slice( 'example', 3, 5) }} // 'mp'
toString(value)	値を文字列に変換します。	{{ functions.toString(123) }} // '123'
substring(value, start, end)	値の開始インデックスから終了インデックスまでの部分を返します。slice 関数と substring 関数の違いについてご覧ください	{{ functions.substring( 'example’', 3, 5) }} // 'mp'
toTimestamp()	現在の UNIX タイムスタンプを返します。	{{ functions.toTimestamp() }} // 1628761483
toTimestamp(date)	指定した日付をUNIX時刻で返します。	{{ functions.toTimestamp('2021-04-30T10:02:50.876Z') }} // 1619776970
toTimestamp(date)	指定した日付をUNIX時刻で返します。	{{ functions.toTimestamp('2021-04-30T10:02:50.876Z') }} // 1619776970
toLowerCase(value)	小文字に変換された新しい文字列を返します。	{{ functions.toLowerCase('JohnDoe 1234') }} // johndoe 1234
toUpperCase(value)	大文字に変換された新しい文字列を返します。	{{ functions.toUpperCase('JohnDoe 1234') }} // JOHNDOE 1234
replaceAll(value, string, replacement)	パターンに一致するすべての箇所を置換文字列に置き換えた新しい文字列を返します。	{{ functions.replaceAll('2021-04-30', '-', '/') }} // 2021/04/30
replace(value, string, replacement)	パターンに一致する箇所を置換文字列に置き換えた新しい文字列を返します。pattern が文字列の場合は、最初に出現した箇所のみが置き換えられます。	{{ functions.replace('2021-04-30', '-', '/') }} // 2021/04-30
split(value, separator, limit?)	区切り文字で分割した部分文字列の順序付きリストを返します。	{{ functions.split('2021-04-30', '-') }} // ['2021', '04', '30']
now()	現在の日時を ISO 8601 形式で返します。	{{ functions.now() }} // 2021-04-30T10:31:28.576Z
includes(collection, item, fromIndex?)	配列に特定の値が含まれているかどうかを返します。	{{ functions.includes(['auth0', 'identity', 'authentication'], 'identity') }} // true
indexOf(collection, item, fromIndex?)	配列内で指定した要素が最初に見つかるインデックスを返し、存在しない場合は -1 を返します。	{{ functions.indexOf(['auth0', 'identity', 'authentication'], 'identity') }} // 1
merge(base, value)	ベースのデータ型に応じて、配列やオブジェクトをマージするか、文字列を連結した結果を返します。	{{ functions.merge(['auth0', 'identity'], ['authentication']) }} // ['auth0', 'identity', 'authentication']
md5(value)	MD5 ハッシュ値を返します。	{{ functions.md5('auth0') }} // 7bbb597...
sha1(value)	SHA1ハッシュ値を返します。	{{ functions.sha1('auth0') }} // b4ec5339...
sha256(value)	SHA256ハッシュ値を返します。	{{ functions.sha256('auth0') }} // d9082bdc...
sha512(value)	SHA512ハッシュ値を返します。	{{ functions.sha512('auth0') }} // c0d588069d...
uuid()	ランダムな v4 UUID を返します。	{{ functions.uuid() }} // 36b8f84d-df4e-4d49-b662-bcde71a8764

​

変数のベストプラクティス

​

意味のあるIDを使用する

FormフィールドやFlowアクションを追加すると、IDは自動的に生成されます。

IDは、どの情報が入っているか分かるように、より具体的で分かりやすい値に更新してください。たとえば、ユーザーの名を保存するFormフィールドを作成する場合は、IDをfirst_nameに変更します。

​

既存のIDを更新する際は注意してください

変数がすでに使用されていてIDを変更する必要がある場合は、そのIDをどこで参照しているかを確認し、undefined や空の値が発生しないよう、該当箇所のIDもあわせて更新してください。

​

Flow の実行を確認する

想定外の変数の値が表示された場合は、Executions ビューを使って変数の問題を調査してください。

​

オートコンプリートメニューを使用する

オートコンプリートメニューを使うと、既存の変数を見つけて正しく参照できます。