変数とヘルパー関数

Actions の フォーム で変数を使用する方法について説明します。

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

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

• 変数は中かっこ {{ variable }} で囲みます。
• 変数が存在しない場合、または解決できない場合は、undefined 変数と同様に扱われます。
• null 合体演算子を使用して、null または undefined の変数を処理できます。例: {{fields.foo ?? fields.bar}}。

​

利用可能な変数

フォームとフローで顧客から収集したデータを参照・変換するために、さまざまな種類の変数を使用できます。

変数	構文	使用箇所	説明
コンテキスト	{{context.*}}	フォーム / フロー	現在のトランザクションのコンテキストデータを参照します
フォームフィールド	{{fields.*}}	フォーム / フロー	フォームフィールドおよび非表示フィールドのデータを参照します
共有変数	{{vars.*}}	フォーム / フロー	共有変数として保存されたデータを参照します
フローアクションの出力	{{actions.*}}	フロー	前のフローアクションの出力レスポンスのデータを参照します
ヘルパー関数	{{functions.*}}	フォーム / フロー	データを変換するためのヘルパー関数です

​

コンテキスト変数

フォームとフローは、現在のトランザクションからコンテキスト変数を自動的に継承します。アクセスできるコンテキスト変数は次のとおりです。

• 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 オブジェクト。以下のプロパティにアクセスできます。

  • custome_domain.domain
  • custome_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 のアクションの出力 code を参照します。

​

共有変数

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

共有変数には次の特性があります。

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

​

ヘルパー関数

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

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

関数	説明	例
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)	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)	開始インデックスから終了インデックスまでの value 配列または文字列の一部を返します。	{{ functions.slice( 'example', 3, 5) }} // 'mp'
toString(value)	value を文字列に変換します。	{{ functions.toString(123) }} // '123'
substring(value, start, end)	値の 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?)	配列内で指定した要素が最初に見つかる位置の index を返し、存在しない場合は -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 を使用する

フォームフィールドまたはフローの フローアクション を追加すると、ID は自動的に生成されます。

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

​

既存の ID を更新する際は注意が必要です

変数がすでに使用されていて ID を変更する必要がある場合は、その ID を参照している箇所を特定し、未定義または空の値にならないよう、該当箇所の ID も更新してください。

​

フローの実行を確認する

予期しない変数値が表示された場合は、変数をトラブルシューティングするために Executions ビューを使用します。

​

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

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