接続のセットアップ

Integration Hub接続を使用すると、CXoneで使用するサードパーティのWebサービスへの統合を設定できます。

これらの各タスクを指定された順序で実行します。

接続テンプレートの作成

接続テンプレートは、統合に関する基本情報を定義します。 テンプレートは接続を作成するために使用され、特定のリクエストやその他の情報を設定できます。

接続テンプレートは作成後に変更することはできません。 ヘッダーなどの詳細を変更する必要がある場合は、新しいテンプレートを作成する必要があります。

Integration Hubの[テンプレートの追加]ページのスクリーンショット
  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.
  2. [テンプレートを追加]をクリックします。
  3. [詳細]タブで、テンプレートの名前を入力します。
  4. 接続するアプリケーションの名前を入力します。 これは、アプリケーション、プラットフォーム、またはWebサービスである可能性があります。
  5. 統合方法としてRESTを選択します。 現在、サポートされている方法はRESTのみです。

  6. 認証タイプのオプションを選択します。

    オプション 詳細
    OAuth 2.0 テンプレートにOAuth2.0認証を含める場合は、このオプションを選択します。 現在、これが唯一サポートされている認証タイプです。
    認証なし テンプレートに認証を含めない場合は、このオプションを選択します。
  7. テンプレートの説明を入力します。 他のユーザーは、接続ライブラリからこのテンプレートを選択するとそれを表示できます。
  8. アイコンを添付するには、画像をドラッグアンドドロップするか、ファイルを閲覧をクリックします。 このアイコンは、このテンプレートから作成されたすべての接続について接続ライブラリのこのテンプレートに表示されます。
  9. [設定]タブで、このテンプレートで使用できるようにするメソッド(動詞)を選択します。 すべてのWebサービスがすべてのREST動詞をサポートしているわけではありません。
  10. このテンプレートのカスタム認証ヘッダーを定義するには、カスタムヘッダーを追加をクリックします。 このオプションは、テンプレートで認証を有効にした場合にのみ使用できます。 ヘッダーを定義するには:
    1. 表示されるフィールドにヘッダー名を入力します。
    2. さらにカスタムヘッダーを追加するには、カスタムヘッダーを追加をクリックします。
    3. 必須?を選択します。 このテンプレートから作成された接続で使用する必要のあるヘッダーには。
    4. ヘッダーを削除するには、Xをクリックします。
  11. すべての設定を再確認してください。 テンプレートを保存した後は編集できません。
  12. 次のいずれかを実行します。
    • フロッピーディスクのアイコン保存をクリックして、テンプレートを接続ライブラリに追加します。
    • 接続 + マイ接続を保存をクリックして、テンプレートを接続ライブラリに追加し、そこから接続を作成します。 接続が作成されたら、認証の詳細、変数またはリクエストを追加して、接続を設定できます。 リクエストには、これらの設定の一部またはすべてを含めることができます。

接続を作成します

接続を使用すると、リクエストを作成し、認証の詳細を追加できます。 接続はIntegration Hubの[マイ接続]の下に表示されます。 接続テンプレートから新規接続を作成できます。 接続ライブラリには、CXone システムに存在するすべての接続テンプレートが表示されます。 必要な作業に一致するテンプレートがない場合は、テンプレートを作成します。

また、既存の接続をコピーして、既存の接続と類似した新規接続を作成する時間を節約することもできます。 既存の接続のコピーを作成すると、新しい接続には元の接続のURL、ヘッダー、パラメーター、本文、タイムアウト設定、変数名、シークレット名が含まれます。 新しい接続には、元の接続のリクエスト、クライアント証明書、キー、パスフレーズ、変数値、シークレット値は含まれません。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. 以下のいずれかの方法で新規接続を作成します：

    • ゼロから新規接続を作成するには、接続ライブラリーでテンプレートを探します。 ライブラリはページの右側にあります。 接続またはテンプレートを表示している場合は、ページの右上隅にあるXをクリックします。 これにより閉じられ、接続ライブラリが表示されます。 テンプレートのプロパティページで+自分の接続をクリックして、テンプレートに基づいて接続を作成します。

    • 既存の接続をコピーして新規接続を作成するには、左側の自分の接続ペインでコピーしたい接続を見つけて、それをクリックします。 [2枚の紙を重ねたアイコンコピー]をクリックします。

  3. ポップアップウィンドウの自分の接続名フィールドに、新規接続の一意の名前を入力します。

  4. [フロッピーディスクのアイコン保存]をクリックします。

認証の詳細の設定

接続の[認証]タブで認証の詳細を設定できます。 このタブは、この接続に使用されるテンプレートで認証が有効になっている場合にのみ表示されます。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. 認証タブをクリックします。

  4. 認証リクエストに使用されるURLを入力します。 URLはダイナミックにすることはできませんが、URL内のシークレットを参照することはできます。

  5. 認証リクエストで使用するRESTメソッド(動詞)を選択します。 使用可能な動詞は、この接続に使用するテンプレートによって定義されます。

  6. ヘッダーの下で、各フィールドに適切な値を入力します。 アスタリスク(*)の付いたフィールドは必須です。 これらのフィールドは、この接続に使用されるテンプレートで定義します。

  7. この接続にカスタムヘッダーを追加するには:

    1. カスタムヘッダーの追加をクリックします。

    2. ヘッダー名とヘッダー値を入力します。

  8. 認証リクエストにクエリパラメーターを追加するには:
    1. クエリパラメーターを追加をクリックします。
    2. 追加するクエリーパラメーターごとに、クエリーパラメーター名とクエリーパラメーター値を入力します。

  9. メディアタイプを選択し、本文の内容を入力します。 メディアタイプは本文コンテンツの形式に影響します。 これは、使用している認証サーバーが要求するタイプと一致することが推奨されます。

    オプション 詳細

    ApplicationJson

    本文コンテンツはJSONでなければなりません。
    ApplicationJsonPatch 本文コンテンツはJSONパッチ形式でなければなりません。
    FormURLEncoded

    本文コンテンツはキーと値のペアでなければなりません。 このメディアタイプにより、一般的なURL表記を使って申請を送ります。

    +フォームパラメーターから追加をクリックし、フォームパラメーター名とフォームパラメーター値を入力します。
    TextHtml 本文コンテンツはHTMLでなければなりません。
    TextPlain 本文コンテンツはプレーンテキストでなければなりません。
    TextXml 本文コンテンツはXMLでなければなりません。

  10. [フロッピーディスクのアイコン保存]をクリックします。

mTLS自己署名証明書を設定します

接続の設定タブを使用して、タイムアウト設定を設定し、mTLS自己署名証明書を設定することができます。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. 設定タブをクリックします。

  4. 必要に応じてタイムアウト(MS)設定を調整します。 タイムアウトは、認証を含む、接続で設定されたすべてのリクエストに適用されます。 mTLS自己署名証明書を使用している場合は、次のフィールドに入力します。

    • クライアント証明書
    • クライアントの秘密鍵
    • キーパスフレーズ

    これらのフィールドは、認証タイプとしてOAuth2.0を使用する場合にのみ表示されます。 クライアント証明書とクライアントの秘密鍵を一緒に入力する必要があります。 クライアントの秘密鍵が暗号化されている場合は、キーパスフレーズを入力する必要があります。 mTLS証明書は、認証URLがHTTPSである場合にのみ機能します。 これらのフィールドの検証は、接続が保存された後に行われます。 これらのフィールドはシークレットタブで参照できます。

  5. [フロッピーディスクのアイコン保存]をクリックします。

接続に変数を追加します

Integration Hub変数により接続の中で特定の情報を共有することができます。 この情報が暗号化されているかどうかを判断することができます。 暗号化された変数(シークレット)は、Studioスクリプト中のパスワードのような機密情報を使用する際にセキュリティの追加レイヤーを提供します。

変数を作成すると、いつでもそれをシークレットに変換することができます。 変数がシークレットになり、コネクタが保存されると、シークレットを変数に戻すことはできません。

シークレットは元に戻せません。 シークレット値フィールドから離れてクリックすると、コンテンツは暗号化され、マスキングアスタリスク(*)に置き換えられます。 マスクされた後はフィールドに入力した値を取得する方法はありません。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. 変数のタブでは、デバイスの+追加をクリックします。

  4. 変数名を入力し、変数に含まれる内容を特定します。 名前にはスペースや特殊文字を含めることができます。

  5. 変数値を入力します。 これは変数の値であり、変数をシークレットにした場合に暗号化される情報です。 シークレットとして有効にする前に、情報が正しいことを検証してください。

  6. 変数を暗号化するには、シークレットトグルを有効にします。

  7. 接続から変数を削除するには、その変数の右側にあるXをクリックします。

  8. [フロッピーディスクのアイコン保存]をクリックします。

接続で変数を使用します

手動リクエストまたはStudioスクリプトリクエストで変数を使用できます。 ヘッダー、クエリーパラメーター、本文コンテンツで使用できます。

認証の詳細または手動リクエストで変数を使用します

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. 変数を使いたいタブをクリックします。 変数は認証およびリクエストのタブで使用できます。

  4. ガイドラインに従って、変数値を入れたい場所に変数を入力します：

    • 名前を二重括弧で囲みます。 たとえば、[[ variableName ]]のように。
    • 変数のタブの変数名フィールドに入力した名前をそのまま使用します。
    • 変数は、それが作成された接続でのみ使用することができます。

Studioリクエストで変数を使用します

Studioスクリプトで変数を使用するには、スクリプトにCONNECTAuthまたはCONNECTREQUESTアクションが必要です。 アクションは、変数を含む接続にスクリプトをリンクしなければなりません。

  1. Studioで、変数を使用したいスクリプトを開きます。

  2. 変数を追加したいSnippetアクションをダブルクリックします。

  3. Snippetエディタのウィンドウで、以下のガイドラインに従って、変数値を使用したい場所に変数を追加します：

    • 名前を二重括弧で囲みます。 たとえば、[[ variableName ]]のように。
    • 変数のタブの変数名フィールドに入力した名前をそのまま使用します。
    • 括弧と変数名を二重引用符(")で囲みます。 たとえば、"[[ variableName ]]"のように。 変数がURLなどの文字列の一部である場合、変数だけでなく文字列全体を二重引用符で囲む必要があります。 たとえば、"[[ variableName ]]/location/anotherlocation/"のように。
    • 変数は、それが作成された接続でのみ使用することができます。 接続は、CONNECTAuthまたはCONNECTREQUESTアクションを使用してスクリプトで指定する必要があります。

    例：

    • ASSIGN requestPayload.body = "[[client_id]]"

    • ASSIGN requestPayload.URL = "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS"

手動リクエストを作成する

リクエストは、統合が接続するWebサービスから必要な情報を取得する方法です。 Studioスクリプト内で手動リクエストを使用したり、Integration Hubから実行したりできます。

リクエストにURL、ヘッダー、またはパラメーター内のパスパラメーターまたは変数置換が必要な場合は、Studioリクエストを作成する必要があります。 手動リクエストではこれらのオプションはサポートされません。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. [リクエスト]タブで、リクエストを追加をクリックします。

  4. リクエスト名を入力します。

  5. トリガーとして手動を選択します。

  6. このリクエストのURLを入力します。

  7. このリクエストのメソッド(動詞)をクリックします。

  8. [ヘッダー]で、リクエストに必要なヘッダーを追加します。

    1. ヘッダーを追加をクリックします。

    2. ヘッダー名とヘッダー値を入力します。

  9. [クエリパラメーター]で、リクエストに必要なクエリパラメーターを追加します:
    1. クエリパラメーターを追加をクリックします。
    2. クエリパラメーター名とクエリパラメーター値を入力します。

  10. メディアタイプを選択し、本文の内容を入力します。 メディアタイプは本文コンテンツの形式に影響します。 接続先のWebサービスが要求するタイプと一致することが推奨されます。

    オプション 詳細

    ApplicationJson

    本文コンテンツはコンテンツヘッダーとしてapplication/jsonを持つJSONでなければなりません。
    ApplicationJsonPatch 本文コンテンツはapplication/json-patch+jsonをコンテンツヘッダーとして持つJSONパッチ形式でなければなりません。
    FormURLEncoded

    本文コンテンツは、application/x-www-form-urlencodedをコンテンツヘッダーとして持つキーと値のペアでなければなりません。 このメディアタイプにより、一般的なURL表記を使って申請を送ります。

    +フォームパラメーターから追加をクリックし、フォームパラメーター名とフォームパラメーター値を入力します。
    TextHtml 本文コンテンツはtext/htmlをコンテンツヘッダーとして持つHTMLでなければなりません。
    TextPlain 本文コンテンツはtext/plainをコンテンツヘッダーとして持つプレーンテキストでなければなりません。
    TextXml 本文コンテンツはtext/xmlをコンテンツヘッダーとして持つXMLでなければなりません。
  11. このリクエストのアクティブステータスを変更する場合は、ページの上部にあるアクティブをクリックします。 テキストが非アクティブに変わります。
  12. クリック確認。
  13. [リクエスト]タブで、追加したリクエストのテストをクリックします。 Integration Hubがリクエストを試行します。 ウィンドウが表示され、テストの結果が表示されます。
  14. 編集をクリックしてリクエストを変更するか、フロッピーディスクのアイコン保存をクリックします。

Studioリクエストを作成する

Studioリクエストは、Integration Hubで作成できないが認証とシークレット用にIntegration Hubを使用できるようにしたAPIリクエストがあるときに有用です。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. [リクエスト]タブで、リクエストを追加をクリックします。

  4. リクエスト名を入力します。

  5. トリガーとしてStudioを選択します。

  6. サンプルを使用してスクリプトでJSONを構築する場合は、[リクエストを追加]ページからサンプルのリクエストペイロードを選択してコピーします。

  7. クリック確認。

    StudioリクエストはIntegration Hubからテストできません。 トレースを使用してスクリプトを実行してStudioでテストする必要があります。

  8. [フロッピーディスクのアイコン保存]をクリックします。

  9. Studioを起動してログインします。
  10. 既存のスクリプトを開くか、新しいスクリプトを作成します。
  11. スクリプトにSnippet アクションを追加し、それをダブルクリックしてSnippetエディターウィンドウを開きます。

  12. Snippetエディターウィンドウでダイナミックオブジェクトを構築し、JSONに変換します。 作成するオブジェクトには、リクエストに必要なヘッダー、クエリパラメーター、および本文コンテンツを保持するメンバーが含まれている必要があります。

    オブジェクトを作成するときは、前の手順でIntegration Hubからコピーしたサンプルのペイロードをガイドとして使用します。 ペイロードの例:

    {
 "URL": "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS",
 "HTTPMETHOD": "POST",
 "HEADERS": {
	"CONTENT-TYPE": "APPLICATION/JSON",
	"AUTHORIZATION": "BEARER[[BEARERTOKEN]]"
	},
 "QUERYPARAMETERS": {
	"ANI": "[[ANI]]",
	"ACCOUNTID": "123456"
	},
 "BODY": {
	"ANI": "[[ANI]]",
	"ACCOUNTID": "123456",
	"ACCOUNTNAME": "TESTACCOUNT"
	}
}

    サンプルのペイロードをガイドとして使用して作成されたダイナミックオブジェクトは次のとおりです:

    DYNAMIC requestPayload 
ASSIGN requestPayload.URL = "[[INSTANCEURI]]/INCONTACTAPI/SERBICES/V26.0/AGENTS"
ASSIGN requestPayload.HTTPMETHOD = "POST"
ASSIGN requestPayload.HEADERS.CONTENTHYPHENPLACEHOLDERTYPE = "APPLICATION/JSON"
ASSIGN requestPayload.HEADERS.AUTHORIZATION = "BEARER[[BEARERTOKEN]]"
ASSIGN requestPayload.QUERYPARAMETERS.ANI = "[[ANI]]"
ASSIGN requestPayload.QUERYPARAMETERS.ACCOUNTID = "123456"
ASSIGN requestPayload.BODY.ANI = "[[ANI]]"
ASSIGN requestPayload.BODY.ACCOUNTID = "123456"
ASSIGN requestPayload.BODY.ACCOUNTNAME = "TESTACCOUNT"
ASSIGN requestPayloadJSON = "{requestPayload.asjson()}"
ASSIGN requestPayloadJSON = "{requestPayloadJSON.replace("HYPHENPLACEHOLDER", "-")}"

    前の例の最後の行では、replace() 関数を使用してハイフン(-)文字をCONTENT-TYPEキー名に挿入しています。 Studioでは、変数名にハイフンなどの特殊文字を含めることはできないため、このアプローチは回避策として使用されます。

  13. リクエストを使用するようにスクリプトを設定します。

リクエストの状態を変更する

各Integration Hub接続には最大50件のリクエストを含めることができます。 一度にアクティブにできるリクエスト数に制限はありません。 リクエストはデフォルトでアクティブになっています。

  1. CXoneで、アプリセレクターをクリックし、選択します：オートメーションとAI > Integration Hub.

  2. ページの左側にある[マイ接続]から、操作する接続をクリックします。

  3. [リクエスト]タブで、操作するリクエストをクリックします。

  4. 状態を変更するには、ページの上部にある非アクティブまたはアクティブをクリックします。