CTIOperationResponse :スコープ付き、グローバル

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む50読むのに数分

    • CTIOperationResponse API は、現在の CTIOperationResponse オブジェクトに関するデータを設定および取得するためのメソッドを提供します。

    CTIOperationResponse オブジェクトを使用して、ServiceNow 音声アシスト機能 フレームワーク内において操作ハンドラーとメッセージトランスフォーマーの間で情報を渡します。

    通常、操作ハンドラーは、関連付けられた要求を処理するときに CTIOperationResponse オブジェクトに値を設定する役割を担います。メッセージトランスフォーマーは、CTIOperationRequest オブジェクトから値を取得し、コンピューター電話統合 (CTI) プロバイダーに送り返される CTI 固有のペイロードを構築する役割を担います。

    ServiceNow ベースシステムは、Amazon Connect への接続を有効にする機能している操作ハンドラーとメッセージトランスフォーマーを提供します。Amazon Connect 内で連絡先フローを構築する場合、Amazon サービスと ServiceNow インスタンスの間に次の 2 つの統合ポイントがあります。
    • Amazon Web Services (AWS) Lambda プロキシ (AWS Lambda 関数の呼び出し)
    • AWS Lex ボット (顧客入力を取得)
    これらの統合ポイントに利用可能な操作ハンドラーとメッセージトランスフォーマーは、操作ハンドラー [sn_cti_operation_handler] テーブルおよびプロバイダーメッセージトランスフォーマー [sn_cti_provider_msg_transormer] テーブルにあります。

    次の操作ハンドラースクリプトは、さまざまな CTIOperationResponse メソッドを使用して CTIOperationResponse オブジェクトに値を設定する方法を示しています。

    (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response) {

  try {
    var state = request.getParameter('$state');
    if(!state) {
      state = 'new';
    }
    var phone = request.getParameter('contact.phone');
    var username = request.getParameter('contact.username');
    var someDataPresent = phone || username;
    if(!someDataPresent) {
      throw 'phone or username must be supplied';
    }
    if('new' === state) {
      var userGr = null;
      if(phone || username) {
        userGr = new GlideRecordSecure('sys_user');
        var qc = null;
        if(phone) {
          qc = userGr.addQuery('phone', phone);
          qc.addOrCondition('mobile_phone', phone);
          qc.addOrCondition("home_phone", phone);
        }
        if(username) {
          if(qc) {
            qc.addOrCondition('user_name', username);
          } else {
            qc = userGr.addQuery('user_name', username);
          }
        }
        // If there was criteria then run the query
        if(qc) {
          userGr.query();
        } else {
          userGr = null;
        }
      }
			
      var foundUser = userGr && userGr.next();

      var phonelogGr = new GlideRecord('sn_openframe_phone_log');
      phonelogGr.initialize();
      phonelogGr.setValue('call_id', request.getParameter('contact.id'));
      phonelogGr.setValue('phone_number', phone);
      if(foundUser) {
        phonelogGr.setValue('contact', userGr.getUniqueValue());
      }
      phonelogGr.insert();
			
      var interactionGr = new GlideRecordSecure('interaction');
      interactionGr.initialize();
      interactionGr.setValue('type', 'phone');
      interactionGr.setValue('short_description', 'User Contact via Phone: ' + phone);
      interactionGr.setValue('channel_metadata_table', 'sn_openframe_phone_log');
      interactionGr.setValue('channel_metadata_document',phonelogGr.getUniqueValue());
			
      if(foundUser) {
        interactionGr.setValue('opened_for', userGr.getUniqueValue());
        response.setSessionAttribute('snc_user_first_name', userGr.getValue('first_name'));
        response.setSessionAttribute('snc_user_last_name', userGr.getValue('last_name'));
        response.setSessionAttribute('snc_user_sys_id', userGr.getUniqueValue());
      } else {
        response.setSessionAttribute('snc_user_sys_id', "USER_NOT_FOUND");
      }
      interactionGr.setValue('state', 'new');

      var interactionId = interactionGr.insert();

      response.setStatusCode(200);
      response.setMessage('success');
      response.setSessionAttribute('interactionTable', 'interaction');
      response.setSessionAttribute('interactionId', interactionId);

    }
  } catch(e) {
    ctx.setError(e);
  }

})(request, response);

    操作ハンドラーの作成の詳細については、「 発信者との自動インタラクション用の問い合わせフローの構成」を参照してください。

    次のメッセージトランスフォーマースクリプトは、CTIOperationResponse オブジェクトに設定された値を取得して、CTI 固有のペイロードに格納し、CTI プロバイダーに送り返します。

    (function (/*CTIOperationResponse*/operationResponse, /*HTTPResponse*/ httpResponse) {
	// AWS Connect Lambda expects name value pairs only
	var out = {};
	for(var k in operationResponse.getSessionAttributes()) {
		out[k] = operationResponse.getSessionAttributes()[k];
	}
	out.statusCode = operationResponse.getStatusCode();
	out.message = operationResponse.getMessage();
	httpResponse.setBody(out);
})(operationResponse, httpResponse);

    この API は sn_cti_core 名前空間で実行されます。CTIOperationRequest API にアクセスするためには、ServiceNow 音声アシスト機能 Core (sn_cti_core) プラグインがインストールされている必要があります。このインストールの詳細については、「 ServiceNow 音声アシスト機能アプリケーションのインストール」を参照してください。

    ServiceNow 音声アシスト機能の詳細については、ServiceNow 音声アシスト機能を参照してください。

    CTIOperationResponse - CTIOperationResponse(文字列 origin)

    CTIOperationResponse オブジェクトをインスタンス化します。

    表 : 1. パラメーター
    名前 タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setMinorVersion(3);

    CTIOperationResponse - getAuthToken()

    CTIOperationResponse オブジェクトに設定された認証トークンを返します。

    ハンドラーの auth_required フラグが true に設定されている場合、このトークンは、要求された操作ハンドラーを実行する前に ServiceNow 音声アシスト機能 フレームワークによって、現在の ServiceNow 音声アシスト機能 ユーザーを認証するために使用されます。auth_required フラグは、操作ハンドラー [sn_cti_operation_handler] テーブルのフィールドです。認証トークンの有効期間は、コールセッションの有効期間である必要がありますが、CTI プロバイダーによって決定されます。

    独自の認証操作ハンドラーを作成することで、実装に必要なあらゆる認証/認可処理を定義できます。認証トークンの生成方法に関係なく、メッセージ翻訳者は CTI ペイロードでトークンを返す必要があります。さらに、CTI プロバイダーはこの認証トークンをローカルに保存し、認証が必要な各操作要求で渡す必要があります。

    インスタンスが提供する認証操作ハンドラーを使用する場合、ハンドラーはユーザーが入力した 4 桁の PIN に基づいて認証トークンの作成を開始します。次に、CTIOperationResponse オブジェクトの sessionAttributes オブジェクトに認証トークンを設定します。関連するメッセージトランスフォーマーは、sessionAttributes オブジェクトを CTI 固有のペイロードに変換し、CTI プロバイダーに送信します。

    注:
    認証トークンが渡されない場合、 auth_required フラグが設定された操作ハンドラーの実行要求はすべて失敗します。認証を使用しない場合は、認証トークンを維持する必要はありません。
    ServiceNow ベースシステムは、Amazon Connect への接続を有効にする機能している操作ハンドラーとメッセージトランスフォーマーを提供します。Amazon Connect 内で連絡先フローを構築する場合、Amazon サービスと ServiceNow インスタンスの間に次の 2 つの統合ポイントがあります。
    • Amazon Web Services (AWS) Lambda プロキシ (AWS Lambda 関数の呼び出し)
    • AWS Lex ボット (顧客入力を取得)
    これらの統合ポイントに利用可能な操作ハンドラーとメッセージトランスフォーマーは、操作ハンドラー [sn_cti_operation_handler] テーブルおよびプロバイダーメッセージトランスフォーマー [sn_cti_provider_msg_transormer] テーブルにあります。
    表 : 2. パラメーター
    名前 タイプ 説明
    なし
    表 : 3. 返される内容
    タイプ 説明
    文字列 CTIOperationRequest オブジェクトに既に設定された認証トークンです。設定されていない場合は null を返します。 
    var response = new sn_cti_core.CTIOperationResponse();
var token = response.getAuthToken();

    CTIOperationResponse - getError()

    現在の CTIOperationResponse オブジェクトに関連付けられたエラーオブジェクトを返します。

    この情報を使用して、コンピューター電話統合 (CTI) プロバイダーに返されるペイロードを作成できます。

    表 : 4. パラメーター
    名前 タイプ 説明
    なし
    表 : 5. 返される内容
    タイプ 説明
    オブジェクト 操作エラー情報です。このオブジェクトの形式は、CTI プロバイダーによって決定されます。エラーが存在しない場合は null を返します。 
    (function( /*CTIProviderResponseExecutionContext*/ ctx, /*CTIOperationRequest*/ operationRequest, /*CTIOperationResponse*/ operationResponse, /*HTTPResponse*/ httpResponse) {
    var sessionAttributes = {},
        intentResponse;
    var statusCode = -1;
    var message = 'Unprocessed';
    if (operationResponse) {
        statusCode = operationResponse.getStatusCode();
        sessionAttributes = operationResponse.getSessionAttributes();
        message = operationResponse.getMessage();
        var error = operationResponse.getError();
        if (error) {
            sessionAttributes.error = error;
        }
    }
    if (sn_cti_core.CTIRequestDispatcher.Constants.HTTP.Status.AUTH_REQUIRED.code === statusCode) {
        //first call for a secure action without authentication token
        sessionAttributes.statusCode = 401;
        sessionAttributes.message = message;
        intentResponse = {
            sessionAttributes: sessionAttributes,
            dialogAction: {
                type: 'Close',
                fulfillmentState: 'Fulfilled',
                message: {
                    contentType: 'PlainText',
                    content: 'This operation requires authentication. Say authenticate for authentication.'
                }
            }
        };
    } else if ('DialogCodeHook' === operationRequest.getParameter('$$invocationSource')) {
        //pass back authToken and interactionId
        sessionAttributes.authToken = operationRequest.getAuthToken();
        sessionAttributes.interactionId = operationRequest.getInteractionSysId();
		var originalSlots = operationRequest.getParameter('$$slots');
        var responseParameters = operationResponse ? operationResponse.getParameters() : {};
        responseParameters = responseParameters ? responseParameters : {};
        // See if we processing happened and we got a dialogAction
		var responseDialogAction = responseParameters['dialogAction'];
		// Default dialog action
        var dialogAction = {
            type: 'Delegate',
            slots: originalSlots
        };
		// If the response doesn't contain an override replay the inputs
        if (responseDialogAction) {
            // We bypassed dialoghook so delegate and pass through inputs
            dialogAction = responseDialogAction;
        }
        intentResponse = {
            sessionAttributes: sessionAttributes,
            dialogAction: dialogAction
        };
    } else {
        // Override required session attributes
        sessionAttributes.statusCode = statusCode;
        sessionAttributes.message = message;
        // Build response template
        intentResponse = {
            sessionAttributes: sessionAttributes,
            dialogAction: {
                type: 'Close',
                fulfillmentState: 'Fulfilled',
                message: {
                    contentType: 'PlainText',
                    content: message
                }
            }
        };
    }
    httpResponse.setBody(intentResponse);
})(ctx, operationRequest, operationResponse, httpResponse);

    CTIOperationResponse - getInteractionSysId()

    CTIOperationResponse オブジェクトに設定されたコールセッションに関連付けられたインタラクションレコードの sys_id を返します。

    CTIOperationResponse - setInteractionSysId(文字列 Id) メソッドは、このメソッドを呼び出す前に呼び出す必要があります。

    表 : 6. パラメーター
    名前 タイプ 説明
    なし
    表 : 7. 返される内容
    タイプ 説明
    文字列 CTIOperationResponse オブジェクトに設定されたインタラクションレコードの sys_id です。インタラクションレコードはインタラクション [interaction] テーブルにあります。

    インタラクションレコード sys_id が設定されていない場合、このメソッドは null を返します。

    		 
    var request = new sn_cti_core.CTIOperationResponse();
var interactionId = request.getInteractionSysId();

    CTIOperationResponse - getMajorVersion()

    現在の CTIOperationResponse オブジェクトに設定されているコンピューター電話統合 (CTI) ソフトウェアのメジャーバージョンを返します。

    ServiceNow インスタンスに接続されている CTI プロバイダーが複数のバージョンのソフトウェアを実行している場合は、ソフトウェアのバージョンごとに異なるペイロードが必要になる可能性があるため、このメソッドを使用します。ソフトウェアのバージョン間でペイロードがわずかに異なるだけの場合は、メッセージトランスフォーマーを 1 つだけにすることができます。メッセージトランスフォーマー内で要求を行っているソフトウェアのバージョンを確認するだけで、ペイロードの違いに対応できます。必要なペイロードがバージョン間で大幅に異なる場合は、複数のメッセージトランスフォーマーを使用する方が効率的です。

    表 : 8. パラメーター
    名前 タイプ 説明
    なし
    表 : 9. 返される内容
    タイプ 説明
    番号 CTI ソフトウェアのメジャーバージョン番号です。

    メジャーバージョンが設定されていない場合は、1 を返します。

    		 
    var request = new sn_cti_core.CTIOperationResponse();
var majorVersion = response.getMajorVersion();

    CTIOperationResponse - getMessage()

    現在の CTIOperationResponse オブジェクトに設定されているメッセージ文字列を返します。

    通常、これは操作が完了したときにユーザーに返されるメッセージです。この値を設定するには、CTIOperationResponse - setMessage(文字列 message) メソッドを使用します。

    表 : 10. パラメーター
    名前 タイプ 説明
    なし
    表 : 11. 返される内容
    タイプ 説明
    文字列 メッセージのテキストです。メッセージが存在しない場合は、null を返します。 
    (function (/*CTIOperationResponse*/operationResponse, /*HTTPResponse*/ httpResponse) {
  // AWS Connect Lambda expects name value pairs only
  var out = {};
  for(var k in operationResponse.getSessionAttributes()) {
    out[k] = operationResponse.getSessionAttributes()[k];
  }
  out.statusCode = operationResponse.getStatusCode();
  out.message = operationResponse.getMessage();
  httpResponse.setBody(out);
})(operationResponse, httpResponse);

    CTIOperationResponse - getMinorVersion()

    現在の CTIOperationResponse オブジェクトに設定されているコンピューター電話統合 (CTI) ソフトウェアのマイナーバージョンを返します。

    ServiceNow インスタンスに接続されている CTI プロバイダーが複数のバージョンのソフトウェアを実行している場合は、ソフトウェアのバージョンごとに異なるペイロードが必要になる可能性があるため、このメソッドを使用します。ソフトウェアのバージョン間でペイロードがわずかに異なるだけの場合は、メッセージトランスフォーマーを 1 つだけにすることができます。メッセージトランスフォーマー内で要求を行っているソフトウェアのバージョンを確認するだけで、ペイロードの違いに対応できます。必要なペイロードがバージョン間で大幅に異なる場合は、複数のメッセージトランスフォーマーを使用する方が効率的です。

    表 : 12. パラメーター
    名前 タイプ 説明
    なし
    表 : 13. 返される内容
    タイプ 説明
    番号 このインタラクションに関連付けられたペイロードのマイナーバージョン番号です。

    マイナーバージョンが設定されていない場合は、0 を返します。

    		 
    var request = new sn_cti_core.CTIOperationResponse();
var minorVersion = request.getMinorVersion();

    CTIOperationResponse - getParameter(文字列 key)

    現在の CTIOperationResponse オブジェクトに既に設定されている、指定されたキーの値を返します。

    get/setParameter メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。パラメーターオブジェクトには、現在の操作応答に直接関連するデータのキー/値ペアを 0 個以上含めることができます。操作ハンドラーは、これらの値を生成するときに必要なキー/値ペアを判断します。CTIOperationResponse - setParameter(文字列キー, オブジェクト値) メソッドを使用して、現在の CTIOperationResponse オブジェクトのパラメーターを設定します。

    表 : 14. パラメーター
    名前 タイプ 説明
    key 文字列 返されるキーの値の名前です。
    表 : 15. 返される内容
    タイプ 説明
    文字列 渡されたキーの値です。該当するキーが存在しない場合は、null を返します。 
    var request = new sn_cti_core.CTIOperationResponse();
var parm = request.getParameter('contact.phone');

    CTIOperationResponse - getParameters()

    現在の CTIOperationResponse オブジェクトに既に設定されているすべてのパラメーターのキー/値ペアを返します。

    get/setParameter メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。パラメーターオブジェクトには、現在の操作応答に直接関連するデータのキー/値ペアを 0 個以上含めることができます。操作ハンドラーは、これらの値を生成するときに必要なキー/値ペアを判断します。CTIOperationResponse - setParameter(文字列キー, オブジェクト値) メソッドを使用して、現在の CTIOperationResponse オブジェクトのパラメーターを設定します。

    表 : 16. パラメーター
    名前 タイプ 説明
    なし
    表 : 17. 返される内容
    タイプ 説明
    オブジェクト CTIOperationResponse オブジェクトに既に設定されているキー/値ペアのマップです。このキー/値ペアは自由形式であり、操作ハンドラーのニーズにより定義されます。戻り値は文字列または数値です。 
    (function( /*CTIProviderResponseExecutionContext*/ ctx, /*CTIOperationRequest*/ operationRequest, /*CTIOperationResponse*/ operationResponse, /*HTTPResponse*/ httpResponse) {
  var sessionAttributes = {},
      intentResponse;
  var statusCode = -1;
  var message = 'Unprocessed';
  if (operationResponse) {
    statusCode = operationResponse.getStatusCode();
    sessionAttributes = operationResponse.getSessionAttributes();
    message = operationResponse.getMessage();
    var error = operationResponse.getError();
    if (error) {
      sessionAttributes.error = error;
    }
  }
  if (sn_cti_core.CTIRequestDispatcher.Constants.HTTP.Status.AUTH_REQUIRED.code === statusCode) {
    //first call for a secure action without authentication token
    sessionAttributes.statusCode = 401;
    sessionAttributes.message = message;
    intentResponse = {
      sessionAttributes: sessionAttributes,
      dialogAction: {
        type: 'Close',
        fulfillmentState: 'Fulfilled',
        message: {
          contentType: 'PlainText',
          content: 'This operation requires authentication. Say authenticate for authentication.'
        }
      }
    };
  } else if ('DialogCodeHook' === operationRequest.getParameter('$$invocationSource')) {
      //pass back authToken and interactionId
      sessionAttributes.authToken = operationRequest.getAuthToken();
      sessionAttributes.interactionId = operationRequest.getInteractionSysId();
      var originalSlots = operationRequest.getParameter('$$slots');
      var responseParameters = operationResponse ? operationResponse.getParameters() : {};
      responseParameters = responseParameters ? responseParameters : {};
      // See if processing happened and we got a dialogAction
      var responseDialogAction = responseParameters['dialogAction'];
      // Default dialog action
      var dialogAction = {
        type: 'Delegate',
        slots: originalSlots
      };
      // If the response doesn't contain an override replay the inputs
      if (responseDialogAction) {
        // We bypassed dialoghook so delegate and pass through inputs
        dialogAction = responseDialogAction;
      }
        intentResponse = {
            sessionAttributes: sessionAttributes,
            dialogAction: dialogAction
        };
    } else {
      // Override required session attributes
      sessionAttributes.statusCode = statusCode;
      sessionAttributes.message = message;
      // Build response template
      intentResponse = {
        sessionAttributes: sessionAttributes,
        dialogAction: {
          type: 'Close',
          fulfillmentState: 'Fulfilled',
          message: {
            contentType: 'PlainText',
            content: message
          }
        }
      };
  }
  httpResponse.setBody(intentResponse);
})(ctx, operationRequest, operationResponse, httpResponse);

    CTIOperationResponse - getSessionAttribute(文字列 key)

    現在の CTIOperationResponse オブジェクトに設定されている、指定されたセッション属性キーの値を返します。

    get/setSessionAttribute メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。セッション属性は、問い合わせフロー内でもアクセスできます。sessionAttribute オブジェクトには、コンピューター電話統合プロバイダーが定義したセッションの期間中に有効なデータのキー/値ペア (連絡先電話番号など) を 0 個以上含めることができます。操作ハンドラーは、処理中にこれらの値を使用するときに必要なセッション属性のキー/値ペアを判断します。通常、操作ハンドラーは、CTIOperationResponse - setSessionAttribute(文字列キー、オブジェクト値) メソッドを呼び出して CTIOperationResponse オブジェクトにこれらの属性を設定し、メッセージトランスフォーマーは、このメソッドを使用して属性を使用します。

    表 : 18. パラメーター
    名前 タイプ 説明
    key 文字列 返されるキーの値の名前です。
    表 : 19. 返される内容
    タイプ 説明
    文字列 渡されたキーの値です。該当するキーが存在しない場合は、null を返します。 
    var response = new sn_cti_core.CTIOperationResponse();
var phoneAttribute = response.getSessionAttribute('contact.phone');

    CTIOperationResponse - getSessionAttributes()

    現在の CTIOperationResponse オブジェクトに既に設定されているすべてのセッション属性のキー/値ペアを返します。

    get/setSessionAttribute メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。セッション属性は、問い合わせフロー内でもアクセスできます。sessionAttribute オブジェクトには、コンピューター電話統合プロバイダーが定義したセッションの期間中に有効なデータのキー/値ペア (連絡先電話番号など) を 0 個以上含めることができます。操作ハンドラーは、処理中にこれらの値を使用するときに必要なセッション属性のキー/値ペアを判断します。通常、操作ハンドラーは、CTIOperationResponse - setSessionAttribute(文字列キー、オブジェクト値) メソッドを呼び出して CTIOperationResponse オブジェクトにこれらの属性を設定し、メッセージトランスフォーマーは、このメソッドを使用して属性を使用します。

    表 : 20. パラメーター
    名前 タイプ 説明
    なし
    表 : 21. 返される内容
    タイプ 説明
    オブジェクト CTIOperationResponse オブジェクトに既に設定されているキー/値ペアのマップです。このキー/値ペアは自由形式であり、操作ハンドラーのニーズにより定義されます。戻り値は文字列または数値です。 
    (function (/*CTIOperationResponse*/operationResponse, /*HTTPResponse*/ httpResponse) {
  // AWS Connect Lambda expects name value pairs only
  var out = {};
  for(var k in operationResponse.getSessionAttributes()) {
    out[k] = operationResponse.getSessionAttributes()[k];
  }
  out.statusCode = operationResponse.getStatusCode();
  out.message = operationResponse.getMessage();
  httpResponse.setBody(out);
})(operationResponse, httpResponse);

    CTIOperationResponse - getStatusCode()

    現在の CTIOperationResponse オブジェクトに設定されているステータスコードを返します。

    これらのステータスコードは、標準の HTTP ステータスコード (成功の場合は 200、認証が必要な場合は 401 など) に対応している必要があります。通常、生成されるステータスコードは、操作ハンドラーによって決定され、CTIOperationResponse - setStatusCode(文字列 statusCode) メソッドを使用して CTIOperationResponse オブジェクトに設定されます。メッセージトランスフォーマーは、このメソッドを使用して、コンピューター電話統合プロバイダーに返されるペイロードにステータスコードを含めます。

    表 : 22. パラメーター
    名前 タイプ 説明
    なし
    表 : 23. 返される内容
    タイプ 説明
    番号 現在の操作のステータスコードです。ステータスコードが設定されていない場合は -1 を返します。 
    (function (/*CTIOperationResponse*/operationResponse, /*HTTPResponse*/ httpResponse) {
  // AWS Connect Lambda expects name value pairs only
  var out = {};
  for(var k in operationResponse.getSessionAttributes()) {
    out[k] = operationResponse.getSessionAttributes()[k];
  }
  out.statusCode = operationResponse.getStatusCode();
  out.message = operationResponse.getMessage();
  httpResponse.setBody(out);
})(operationResponse, httpResponse);

    CTIOperationResponse - setAuthToken(文字列 token)

    現在の CTIOperationResponse オブジェクトに認証トークンを設定します。

    ハンドラーの auth_required フラグが true に設定されている場合、このトークンは、要求された操作ハンドラーを実行する前に ServiceNow 音声アシスト機能 フレームワークによって、現在の ServiceNow 音声アシスト機能 ユーザーを認証するために使用されます。auth_required フラグは、操作ハンドラー [sn_cti_operation_handler] テーブルのフィールドです。認証トークンの有効期間は、コールセッションの有効期間である必要がありますが、CTI プロバイダーによって決定されます。

    独自の認証操作ハンドラーを作成することで、実装に必要なあらゆる認証/認可処理を定義できます。認証トークンの生成方法に関係なく、メッセージ翻訳者は CTI ペイロードでトークンを返す必要があります。さらに、CTI プロバイダーはこの認証トークンをローカルに保存し、認証が必要な各操作要求で渡す必要があります。

    インスタンスが提供する認証操作ハンドラーを使用する場合、ハンドラーはユーザーが入力した 4 桁の PIN に基づいて認証トークンの作成を開始します。次に、CTIOperationResponse オブジェクトの sessionAttributes オブジェクトに認証トークンを設定します。関連するメッセージトランスフォーマーは、sessionAttributes オブジェクトを CTI 固有のペイロードに変換し、CTI プロバイダーに送信します。

    注:
    認証トークンが渡されない場合、 auth_required フラグが設定された操作ハンドラーの実行要求はすべて失敗します。認証を使用しない場合は、認証トークンを維持する必要はありません。
    ServiceNow ベースシステムは、Amazon Connect への接続を有効にする機能している操作ハンドラーとメッセージトランスフォーマーを提供します。Amazon Connect 内で連絡先フローを構築する場合、Amazon サービスと ServiceNow インスタンスの間に次の 2 つの統合ポイントがあります。
    • Amazon Web Services (AWS) Lambda プロキシ (AWS Lambda 関数の呼び出し)
    • AWS Lex ボット (顧客入力を取得)
    これらの統合ポイントに利用可能な操作ハンドラーとメッセージトランスフォーマーは、操作ハンドラー [sn_cti_operation_handler] テーブルおよびプロバイダーメッセージトランスフォーマー [sn_cti_provider_msg_transormer] テーブルにあります。
    表 : 24. パラメーター
    名前 タイプ 説明
    なし
    表 : 25. 返される内容
    タイプ 説明
    文字列 auth_required フラグが設定された操作を認証するために使用する認証トークンです。 
    var response = new sn_cti_core.CTIOperationResponse();
var authenticate = <Your authentication code here>; // Authenticate the user
if (authenticated) {
	var claims = {
		"interactionId":interactionGr.sys_id.toString()
	};
	var jwt = new sn_cti_core.AuthHelpers().generateJWT(claims);
	response.setAuthToken(jwt);
}

    CTIOperationResponse - setError(オブジェクト error)

    現在の CTIOperationResponse オブジェクトにエラーオブジェクトを設定します。

    コンポーネントでエラーオブジェクトを使用して、コンピューター電話統合 (CTI) プロバイダーに送信するペイロードを作成できます。

    表 : 26. パラメーター
    名前 タイプ 説明
    error オブジェクト 要求された操作の処理中に検出されたエラーに関する情報です。このオブジェクトの形式は、CTI プロバイダーによって決定されます。
    表 : 27. 返される内容
    タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setError(new Error("You did not supply a field"));

    CTIOperationResponse - setInteractionSysId(文字列 Id)

    現在の CTIOperationResponse オブジェクトに、操作要求に関連付けられたインタラクションレコードの sys_id を設定します。

    表 : 28. パラメーター
    名前 タイプ 説明
    sys_id 文字列 現在のインタラクションに設定する sys_id です。
    表 : 29. 返される内容
    タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setInteractionSysId('98529cc55380001048e5ddeeff7b120b');

    CTIOperationResponse - setMajorVersion(数値 majorVersion)

    関連する CTIOperationResponse オブジェクトに、要求を行うコンピューター電話統合 (CTI) ソフトウェアのメジャーバージョンを設定します。

    ServiceNow インスタンスに接続されている CTI プロバイダーが複数のバージョンのソフトウェアを実行している場合は、ソフトウェアのバージョンごとに異なるペイロードが必要になる可能性があるため、このメソッドを使用します。ソフトウェアのバージョン間でペイロードがわずかに異なるだけの場合は、メッセージトランスフォーマーを 1 つだけにすることができます。メッセージトランスフォーマー内で要求を行っているソフトウェアのバージョンを確認するだけで、ペイロードの違いに対応できます。必要なペイロードがバージョン間で大幅に異なる場合は、複数のメッセージトランスフォーマーを使用する方が効率的です。

    表 : 30. パラメーター
    名前 タイプ 説明
    majorVersion 番号 操作要求を行う CTI プロバイダーソフトウェアのメジャーバージョンです。

    この値がまだ設定されていない場合は、1 を返します。
    表 : 31. 返される内容
    タイプ 説明
    なし 
    var request = new sn_cti_core.CTIOperationResponse();
request.setMajorVersion(2);

    CTIOperationResponse - setMessage(文字列 message)

    現在の CTIOperationResponse オブジェクトにテキストメッセージを設定します。

    通常、これは操作が完了したときにユーザーに返されるメッセージであり、関連する操作ハンドラーによって設定されます。その後、メッセージトランスフォーマーは、CTIOperationResponse - getMessage() メソッドを使用してメッセージを取得し、コンピューター電話統合プロバイダーに返します。

    表 : 32. パラメーター
    名前 タイプ 説明
    message 文字列 メッセージテキスト
    表 : 33. 返される内容
    タイプ 説明
    なし 
    (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) {	
  var notes = '', lang = request.getLanguage();
  try { 
		
    var interactionGr = request.getInteractionRecord();

    var now_GR = new GlideRecord('sys_user');
    if(interactionGr && now_GR.get(interactionGr.opened_for.toString())) {	
    if(now_GR.locked_out == true) {
        notes += gs.getMessageLang("User record found locked. Unlocking the account.\n", lang);
        now_GR.locked_out=false;
        now_GR.update();
        response.setStatusCode(200);
        response.setMessage(gs.getMessageLang("Your account has been unlocked.", lang));
      } else {
        notes += gs.getMessageLang("User record not locked.\n", lang);
        response.setStatusCode(200);
        response.setMessage(gs.getMessageLang("Your account doesn't seem to be locked.", lang));
      }	
    } else {
      notes += gs.getMessageLang("User record not found. Transfer to agent\n", lang);
      response.setStatusCode(302);
      response.setMessage(gs.getMessageLang("I am unable to find your record. Let me transfer to someone who can help.", lang));
    }
    if(interactionGr) {
      interactionGr.work_notes = notes;
      interactionGr.update();
    }
  } catch(e) {
    ctx.setError(e);
  }
})(request, response, ctx);

    CTIOperationResponse - setMinorVersion(数値 minorVersion)

    関連する CTIOperationResponse オブジェクトに、要求を行うコンピューター電話統合 (CTI) ソフトウェアのマイナーバージョンを設定します。

    ServiceNow インスタンスに接続されている CTI プロバイダーが複数のバージョンのソフトウェアを実行している場合は、ソフトウェアのバージョンごとに異なるペイロードが必要になる可能性があるため、このメソッドを使用します。ソフトウェアのバージョン間でペイロードがわずかに異なるだけの場合は、メッセージトランスフォーマーを 1 つだけにすることができます。メッセージトランスフォーマー内で要求を行っているソフトウェアのバージョンを確認するだけで、ペイロードの違いに対応できます。必要なペイロードがバージョン間で大幅に異なる場合は、複数のメッセージトランスフォーマーを使用する方が効率的です。

    表 : 34. パラメーター
    名前 タイプ 説明
    minorVersion 番号 操作要求を行う CTI プロバイダーソフトウェアのマイナーバージョンです。

    この値がまだ設定されていない場合は、0を返します。
    表 : 35. 返される内容
    タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setMinorVersion(3);

    CTIOperationResponse - setParameter(文字列 key, オブジェクト value)

    指定されたキー/値ペアを、関連する CTIOperationResponse オブジェクトに設定します。

    get/setParameter メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。パラメーターオブジェクトには、現在の操作要求に直接関連するデータのキー/値ペアを 0 個以上含めることができます。操作ハンドラーは、これらの値を使用するときに必要なキー/値ペアを判断します。通常、操作ハンドラーは、このメソッドを呼び出して CTIOperationResponse オブジェクトにこれらのパラメーターを設定し、メッセージトランスフォーマーは、CTIOperationResponse - getParmeter(文字列 key) または CTIOperationResponse - getSParameters() メソッドを使用して設定値を使用します。

    注:
    JSON.parse(JSON.stringify(object)) 操作後も存続できるオブジェクトのみを格納する必要があります。この基準を満たさないオブジェクトは、操作処理チェーン全体を通じて正しく伝播されない可能性があります。
    例：
    var x = {
  "string": 'abc',
  "int": 123,
  "float": 1.234,
  "number": new Number(3),
  "boolean": true,
  "date": new Date(2006, 0, 2, 15, 4, 5),
  "object": {
    "string": 'abc',
    "int": 123,
    "float": 1.234,
    "number": new Number(3),
    "boolean": true,
    "date": new Date(2006, 0, 2, 15, 4, 5)
  },
  "function": function(abc) {

  }
}
var stringify = JSON.stringify(x);
gs.info(stringify);
var hydrate = JSON.parse(stringify);
var stringify2 = JSON.stringify(hydrate);
gs.info(stringify2);
    結果：
    {"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z","object":{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z"}}
{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z","object":{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z"}}
    表 : 36. パラメーター
    名前 タイプ 説明
    key 文字列 関連付けられた値を格納するキーの名前です。
    value オブジェクト 格納するキーの値です。
    有効なデータタイプ：
    • 文字列
    • int
    • 浮動小数点数
    • 番号
    • ブーリアン
    • 日付
    • オブジェクト
    表 : 37. 返される内容
    タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setParameter('contact.phone', '+15552222345');
response.setParameter('contact.okToCall', true);
response.setParameter('contact.address', {
    street: '1234 Main St'
    city: 'API City',
    zip: 91335
});

    CTIOperationResponse - setSessionAttribute(文字列 key, オブジェクト value)

    指定されたセッション属性のキー/値ペアを、関連する CTIOperationResponse オブジェクトに設定します。

    get/setSessionAttribute メソッドを使用すると、操作ハンドラーとメッセージトランスフォーマーの間で実質的に任意の文字列または数値を渡すことができます。sessionAttribute オブジェクトには、コンピューター電話統合プロバイダーが定義したセッションの期間中に有効なデータのキー/値ペアを 0 個以上含めることができます。セッション属性は、問い合わせフロー内でもアクセスできます。操作ハンドラーは、これらの値を使用するときに必要なセッション属性のキー/値ペアを判断します。通常、操作ハンドラーは、このメソッドを呼び出して CTIOperationResponse オブジェクトにこれらの属性を設定し、メッセージトランスフォーマーは、CTIOperationResponse - getSessionAttribute(文字列 key) または CTIOperationResponse - getSessionAttribute() メソッドを使用して属性を取得します。

    注:
    JSON.parse(JSON.stringify(object)) 操作後も存続できるオブジェクトのみを格納する必要があります。この基準を満たさないオブジェクトは、操作処理チェーン全体を通じて正しく伝播されない可能性があります。
    例：
    var x = {
  "string": 'abc',
  "int": 123,
  "float": 1.234,
  "number": new Number(3),
  "boolean": true,
  "date": new Date(2006, 0, 2, 15, 4, 5),
  "object": {
    "string": 'abc',
    "int": 123,
    "float": 1.234,
    "number": new Number(3),
    "boolean": true,
    "date": new Date(2006, 0, 2, 15, 4, 5)
  },
  "function": function(abc) {

  }
}
var stringify = JSON.stringify(x);
gs.info(stringify);
var hydrate = JSON.parse(stringify);
var stringify2 = JSON.stringify(hydrate);
gs.info(stringify2);
    結果：
    {"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z","object":{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z"}}
{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z","object":{"string":"abc","int":123,"float":1.234,"number":3,"boolean":true,"date":"2006-01-02T23:04:05.000Z"}}
    表 : 38. パラメーター
    名前 タイプ 説明
    key 文字列 関連する値を設定するセッション属性キーの名前です。
    value オブジェクト 設定する値です。
    有効なデータタイプ：
    • 文字列
    • int
    • 浮動小数点数
    • 番号
    • ブーリアン
    • 日付
    • オブジェクト
    表 : 39. 返される内容
    タイプ 説明
    なし 
    var response = new sn_cti_core.CTIOperationResponse();
response.setSessionAttribute('contact.phone', '+15552222345');
response.setSessionAttribute('contact.okToCall', true);
response.setSessionAttribute('contact.address', {
    street: '1234 Main St'
    city: 'API City',
    zip: 91335
});

    CTIOperationResponse - setStatusCode(数値 statusCode)

    CTIOperationResponse オブジェクトに、現在の操作要求のステータスコードを設定します。

    ステータスは任意の整数値を使用して定義できますが、HTTP ステータスコード (200 = Ok/Success、400 = Bad Request、401 = Unauthorized など) を基にすることをお勧めします。

    表 : 40. パラメーター
    名前 タイプ 説明
    statusCode 番号 要求された操作のステータスを一意に識別する整数です。
    表 : 41. 返される内容
    タイプ 説明
    なし 
    (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) {	
  var notes = '', lang = request.getLanguage();
  try { 
		
    var interactionGr = request.getInteractionRecord();

    var now_GR = new GlideRecord('sys_user');
    if(interactionGr && now_GR.get(interactionGr.opened_for.toString())) {	
    if(now_GR.locked_out == true) {
        notes += gs.getMessageLang("User record found locked. Unlocking the account.\n", lang);
        now_GR.locked_out=false;
        now_GR.update();
        response.setStatusCode(200);
        response.setMessage(gs.getMessageLang("Your account has been unlocked.", lang));
      } else {
        notes += gs.getMessageLang("User record not locked.\n", lang);
        response.setStatusCode(200);
        response.setMessage(gs.getMessageLang("Your account doesn't seem to be locked.", lang));
      }	
    } else {
      notes += gs.getMessageLang("User record not found. Transfer to agent\n", lang);
      response.setStatusCode(302);
      response.setMessage(gs.getMessageLang("I am unable to find your record. Let me transfer to someone who can help.", lang));
    }
    if(interactionGr) {
      interactionGr.work_notes = notes;
      interactionGr.update();
    }
  } catch(e) {
    ctx.setError(e);
  }
})(request, response, ctx);