ボット変数は、さまざまなタスク、ノード、その他のボット要素で共通して使用される値を取得するのに役立ちます。ボット変数は、ボットの設定でキーと値の組み合わせとして設定することができ、会話の流れの中で実行時にキーと値を置き換えることができます。頻繁に使用される値を一箇所で取得することで、ボット変数は再利用性と一貫性という利点をもたらします。例えば、ステージングエンドポイントを使用してフライト予約ボットをテストしているとします。このエンドポイントを変数として設定した場合、複数の場所から素早くAPIを呼び出すことができるようになります。ボットの公開中にステージングエンドポイントを本番環境に変更したい場合も、簡単に行えます。同様に、変数を使使用して、ダイアログフローの定義からメッセージとプロンプトのコンテンツを外部に置くことができます。Kore.aiプラットフォームでは、ボットの開発者は、環境とコンテンツの2種類の変数を定義することができます。

環境変数

（以前はグローバル変数と呼ばれていた）環境変数は、キーと値の組み合わせを定義し、その変数をボット全体で使用する、主要なタイプのボット変数です。環境変数はグローバルに宣言されているため、ボットの設定のどの時点でも使用することができます。開発者が環境変数を使用する典型的なユースケースは、次の通りです。

• 異なるエンドポイントURLを持つ環境間でボットを管理する場合。環境に応じてボットをエクスポートおよびインポートすることができ、インフラストラクチャチームは変数設定ファイルのみを変更する必要があります。
• ボットの設定内で繰り返されるボットの応答を変数として定義および管理する場合。
• 認証トークン
• チャネルに関連するトークンとURL

プラットフォームのバージョン8.1リリース以降、オンプレミスのインストールでは、コレクションを使用してこれらの環境変数に複数の値のセットを保存することができます。詳細はこちらを参照してください。

コンテンツ変数

基本的に、ボットの構築には大規模なコンテンツ管理が必要です。多言語対応のボットの場合には、開発者と世界各地に散らばるコンテンツ作成者や著作権管理チームとの間で、面倒な調整作業が必要になります。コンテンツ変数は、コンテンツの制作や編集からボットフローの開発作業を抽象化することで、この問題を解決します。プログラマーは、コンテンツ変数を使用して、ユーザーに提示されるプロンプト、メッセージ、またはデータなどのボットコンテンツをボットコンポーネントにハードコーディングすることを回避し、代わりに各ボット言語の一元管理されたコンテンツ変数ファイル内の特定の変数を指定することができます。この言語固有のコンテンツ変数ファイルは、ボットの設定を公開することなく、コンテンツ編集者にエクスポートすることができます。ライターは、エクスポートされたファイル内のコンテンツを制作し、ボットにインポートすることができます。

ボット変数の定義

ボット変数を追加または編集するには、以下の手順に従います。

1. 変数を追加すｒボットを開いて、設定 > 環境設定を選択します。
2. 環境変数またはコンテンツ変数セクションのいずれかを選択します。
3. 変数ページで変数を追加をクリックして、以下の詳細を入力します。
   • 変数名：「ボット環境」など、特殊文字を使用しない名前を入力します。
   • 値：文字列式を追加します。この文字列は、起動されたあらゆる場所で変数を置き換えます。
     注意：コンテンツ変数の場合は、ボットの言語ごとに異なる値を入力する必要があります。方法については、次のセクションを参照してください。
   • メモフィールドに開発者のメモを入力します。これは任意のフィールドですが、有用なメモを入力することで、ターゲットボットを担当する開発者が関連する値を把握し提供するのに役立ちます。
   • グループは、変数を分類するために使用することができます。
   • 有効な場合は、名前空間を割り当てます（）。
4. [保存] をクリックします。
5. さらに変数を追加または編集する場合は、ステップ3～5を繰り返します。

言語固有の値の入力

コンテンツ変数に言語固有の値を追加するには、まず、ボットの言語を切り替える必要があります。言語の切り替えは、ボットのページの右上にある現在有効な言語名をクリックし、以下の手順で別の言語を選択することで行うことができます。言語を切り替えた後、設定 > 環境設定 > コンテンツ変数ページに移動し、該当する変数の横にある編集アイコンをクリックします。有効になっている言語の値フィールドのテキストを置き換えます。

環境変数の使用

プレーンテキストモード（標準エディター）では、の構文を使用して環境変数を呼び出すことができます。JavaScriptモードで使用している場合は、env.variableNameとなります。JavaScriptモードで使用している場合は、env.variableNameとなります。ここでは、botTypeおよびparametersと呼ばれる2つの環境変数を使用して、開発、テスト、本番といった様々なボット環境を決定しているボットの例をご紹介します。ボットのタスクの1つにある以下のスクリプトノードは、現在のボット環境に応じて、ボットのベースURLを取得します。次のサービスノードのURLは、取得したURLに基づいて変更されます。

コンテンツ変数の使用

プレーンテキストモード（標準エディター）では、の構文を使用してコンテンツ変数を呼び出すことができます。JavaScriptモードで使用している場合は、content.variableNameとなります。ここでは、ユーザーの出発地の空港を取得する、多言語のフライト予約ボットのエンティティノードをご紹介します。これは、ハードコードのユーザープロンプトの代わりにコンテンツ変数を使用しています。ユーザーとのやり取りの一環としてボットがこのノードに到達すると、ユーザープロンプトはやり取りを行っている言語に応じて変化します（有効なすべての言語に対してそれぞれの変数値を入力した場合）。

インポートとエクスポート

ボット変数をボット間でインポートおよびエクスポートすることができます。

1. 設定 > 環境設定 > （環境/コンテンツ）変数からアクセス可能なボット変数のページで、
2. 変数を追加の隣にある楕円をクリックします。
3. インポートするには：インポートを選択してJSONファイルまたはCSVファイルから変数をインポートします。
   • インポートは既存の変数を置き換えるため、バックアップを取ることをお勧めします。
   • バックアップを取った後、インポートを続行します。
   • インポートするJSONファイルまたはCSVファイルを選択します（ファイル形式については以下をご確認ください）。
4. エクスポートするには：エクスポートエクスポートファイルの形式を選択します。
   • ボット変数は、選択した内容に応じてJSONファイル、CSVファイルの形式でエクスポートされます。
   • このファイルには、環境変数とコンテンツ変数の両方が含まれています。

ボット変数ファイルには以下の情報が含まれており、インポートファイルにも同じ情報が必要です。CSVファイルにはヘッダー行が必要です。エクスポートファイル（またはバックアップファイル）を参照し、インポートファイルにも同じ形式を使用することをお勧めします。

• key（必須） – 変数の名前
• scope – 変数の範囲は、変数宣言時の設定オプションに対応しており（提供されない場合はprePopulatedに設定されます）、以下のいずれかになる可能性があります。
  • prePopulated
  • askOnInstall
  • hidden
• value – 変数の値
• variableType（設定されていない場合、デフォルトではenv）-
  • 環境に対してenv
  • コンテンツ変数に対してlocale
• audioTag  – IVRが有効な場合、プレーヤーの詳細用
• group – グループ名
• hint – 変数の説明

サンプルのCSVファイル;： サンプルのJSONファイル：

[ {"key":"hosturl", "value":"https://bots.kore.ai", "hint":"これは、ボットに設定されたエンドポイントで使用することができる環境のURLです", "audioTag":"", "variableType":"env", "scope":"prePopulated", "group":"URLS"} ]

Bot variables help you capture values that are commonly used by different tasks, nodes, and other bot elements. You can configure a bot variable as a key-value pair once in the bot settings and substitute key with value at runtime during the conversation flow.

By capturing frequently used values in a single place, bot variables provide the advantages of reusability and consistency.

For example, let’s say you are testing a flight booking bot using a staging endpoint. If you configure the endpoint as a variable, it helps you to call the API from several places quickly. When you want to change the staging endpoint to production while publishing the bot, it is easy.

Similarly, variables can be used to externalize content for messages and prompts from the dialog flow definition.

Kore.ai platform allows bot developers to define two types of variables – Environment and Content.

Environment Variables

(Previously called Global Variables)

Environment variables are a primary type of bot variables where you define a key-value pair and use the variable across the bot. As the variables are declared globally, they can be used at any point in the bot configuration.

Some of the typical use-cases where a developer can use environment variables are:

• To manage the bot across environments having different endpoint URLs. The bot can be exported and imported based on the environment, and the infrastructure team will need to modify only the variable configuration file.
• To define and manage the bot response that is repeated within the bot configuration as variables.
• Authorization Token
• Channel-related tokens and URLs

Post the release of v8.1 of the platform, for on-prem installations, multiple value sets can be stored for these environment variables using Collections, refer here for more.

Content Variables

Bot building essentially requires extensive content management efforts. When it comes to multi-language bots, it also involves tedious coordination efforts between the developers and globally-distributed content authors or copyright team.

Content variables enable you to overcome that by abstracting bot flow development efforts from authoring or editing the content. Using Content Variables, programmers can avoid hard-coding the bot content, such as prompts, messages, or any data presented to the user, into bot components, and instead point to specific variables in centrally managed Content Variables files for each bot language.
You can export the language-specific content variable files to content editors, without exposing any bot configurations. The writers can author the content in the exported file, which you can import back into the bot.

Defining Bot Variables

Follow these steps to add or edit bot variables:

1. Open the bot for which you want to add the variables
2. Select the Build top menu
3. From the left menu, under Configurations, select either Environment Variables or Content Variables
4. On the Variables page, click Add Variable and enter the following details:
   • Variable Name: Enter a name without any special characters, for example, Bots Environment.
   • Value: Add a String expression. This string replaces the variable everywhere it is invoked.
     Note: For content variables, you need to enter different values for each bot language. Refer to the next section to learn how.
   • Enter developer notes in the Notes field. While this is an optional field, entering useful notes can help the developer working on the target bot to understand and provide relevant values.
   • Group can be used to categorize the variable.
   • Assign a Namespace if enabled (refer here for more).
5. Click Save.
   
6. Repeat steps 3-5 to add or edit more variables.

Entering Language-Specific Values

To add language-specific values for content variables, you first need to switch the bot language. You can switch the language by clicking the name of the currently-enabled language from the top-right corner of the bot’s page and then selecting another language as follows:

After switching the language, go to Build > Configurations > Content Variables page and click the edit icon next to the relevant variable. Replace the text in the Value field in the enabled language.

Using Environment Variables

You can invoke an environment variable in plain text mode (Standard editor) using the following syntax:
{{env.variableName}}

If you are using it in JavaScript mode, it is env.variableName
Here’s an example from a bot that uses two environment variables called botType and parameters to determine different bot environments such as development, testing, and production. The following script node in one of the bot’s tasks captures the base URL of the bot, depending on the current bot environment.

The URL in the following service node changes based on the captured URL

Using Content Variables

You can invoke a content variable in plain text mode (Standard editor) using the following syntax.
{{content.variableName}}

If you are using it in JavaScript mode, it is content.variableName
Here’s an entity node of a multi-language flight booking bot that captures the source airport of the users. It uses a content variable instead of a hard-coded user prompt.

When the bot reaches this node as a part of the user interaction, the user prompt changes depending on the language of the interaction (provided you entered the respective variable values for all the enabled languages).

Importing and Exporting

You can import and export bot variables between bots.

1. On any of the Bot Variables page accessible from Build > Configurations -> (Environment/Content) Variables,
2. Click the ellipses next to Add Variables
3. To Import: Select Import to import variables from a JSON or CSV file
   • Since the import will replace the existing variables, you are advised to take a backup of the same.
   • After taking a Backup, Proceed with the Import
   • Select a JSON or CSV file to import (see below for the file format)
4. To Export: From Export select the preferred format for the export file:
   • Bot variables are exported in the form of a JSON, CSV file based upon your selection.
   • This file includes both environment and content variables.
     

The Bot Variable file contains the following information, the same needs to be present in your Import file. CSV files need a header row. You are advised to refer to the Export (or backup) file and use the same format for the Import file.

• key (mandatory) – name of the variable
• scope  – the scope of the variable corresponds to the Setup Option at the time of variable declaration (if not provided will be set to prePopulated) and can be
  • prePopulated,
  • askOnInstall, or
  • hidden
• value – the value of the variables
• variableType (if not set will default to env)-
  • env for Environment and
  • locale for Content Variable
• audioTag -for the player details in case IVR enabled
• group – group name
• hint – description of the variable

Sample CSV file:

Sample JSON file:

[
  {"key":"hosturl",
   "value":"https://bots.kore.ai",
   "hint":"This is the URL of environment which can be used across the endpoints configured in the bot",
   "audioTag":"",
   "variableType":"env",
   "scope":"prePopulated",
   "group":"URLS"}
]