--- sourceDocument: Xanadu API Reference sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference Release : - xanadu ft:locale : - en-US ft:publication_title : - Xanadu API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # CTIOperationRequest - Scoped, Global # CTIOperationRequest - Scoped, Global {#ariaid-title1} * Release version: Xanadu * * Updated August 1, 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 35 minutes to read The CTIOperationRequest script include provides methods to set and get data on the current CTIOperationRequest object. You use CTIOperationRequest objects to pass information between a message transformer and an operation handler within the ServiceNow Voice framework. Typically, a message transformer is responsible for parsing an incoming CTI-specific payload and setting the payload data on an associated CTIOperationRequest object. An operation handler is then responsible for getting the information from the CTIOperationRequest object and using the data to process the requested operation. The ServiceNow base system provides working operation handlers and message transformers that enable connection to Amazon Connect. When building contact flows within Amazon Connect, there are two integration points between Amazon services and a ServiceNow instance: * Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function) * AWS Lex Bot (Get Customer Input) {#CTIOperationRequestAPI__ul_pqp_3hl_hlb}You can find the available operation handlers and message transformers for these integration points in the Operation Handlers \[sn_cti_operation_handler\] and Provider Message Transformer \[sn_cti_provider_msg_transormer\] tables. A payload is passed into a ServiceNow instance from an external source, such as from a computer telephony integration (CTI) provider that is making an operation request. When a request is received, a message transformer parses the payload and uses the CTIOperationRequest set methods to set payload values, such as the operation handler name, onto an operation and contact-specific CTIOperationRequest object. For example, the following message transformer script parses the passed in JSON payload and sets the values required by the associated operation handler on the CTIOperationRequest object. { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); After the message transformer finishes parsing the passed in payload, the ServiceNow Voice framework instantiates the specified operation handler. The operating handler uses the CTIOperationResponse script include get methods to obtain the information that it needs from the associated CTIOperationRequest object to process the requested operation. For example, the following operation handler script stores values that were set on the CTIOperationRequest object in the interaction record associated with the call. (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) { // Returns the sys_id of the interaction record. var interactionSysId = request.getInteractionSysId(); var number = request.getParameter('number'); var addComment = request.getParameter('add_comment'); addComment = addComment ? addComment.toLowerCase() : addComment; addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment; var workNotes = request.getParameter('work_notes'); var message = gs.getMessage('Thankyou'); var interactionGr = request.getInteractionRecord(); var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null; if (openedFor && number && addComment && workNotes) { var now_GR = new GlideRecordSecure('incident'); now_GR.addQuery('caller_id', openedFor); now_GR.addQuery('number', number); now_GR.query(); if (now_GR.next()) { now_GR.work_notes += workNotes; now_GR.update(); message = now_GR.getMessage('Your comment was added'); } } response.setStatusCode(200); response.setMessage(message); })(request, response, ctx); For additional information on creating operation handlers, see [Configure a contact flow for an automated caller interaction](https://www.servicenow.com/docs/access?context=establish-automated-bot-interactions&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). This script include runs in the `sn_cti_core` namespace. Before you are able to access the CTIOperationRequest script include, the ServiceNow Voice (sn_cti_core) plugin must be activated. For information on activating ServiceNow Voice, see [Install ServiceNow Voice applications](https://www.servicenow.com/docs/access?context=install-ccc-apps&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). For additional information on the ServiceNow Voice, see [ServiceNow Voice](https://www.servicenow.com/docs/access?context=cloud-call-center-overview&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). ## CTIOperationRequest - CTIOperationRequest(String origin) {#ariaid-title2} Instantiates a CTIOperationRequest object. {#CTIOpReq-CTIOperationRequest_S__table_mvz_lgy_glb__entry__3} | Name | Type | Description | |-|-|-| | origin | String | Optional. Origin of the request. Usually the name of the computer telephony integrator provider. Default: null | [Table 1. Parameters] {#CTIOpReq-CTIOperationRequest_S__table_mvz_lgy_glb} var request = new sn_cti_core.CTIOperationRequest('AWS Connect'); request.setSessionAttribute('contact.phone', '+15552222345'); request.setSessionAttribute('contact.okToCall', true); request.setSessionAttribute('contact.address', { street: '1234 Main St' city: 'API City', zip: 91335 }); ## CTIOperationRequest - getAuthToken() {#ariaid-title3} Returns the authentication token set on the associated CTIOperationRequest object. This token is used by the ServiceNow Voice framework to authenticate the current ServiceNow Voice user before executing the requested operation handler if the handler's auth_required flag is set to true. The auth_required flag is a field in the Operation Handler \[sn_cti_operation_handler\] table. The life of an authentication token should be for the life of the call session, but is determined by the CTI provider. You can define whatever authentication/authorization handling required by your implementation by creating your own authentication operation handler. Regardless of how the authentication token is generated, the message translator must pass the token back in the CTI payload. Additionally, the CTI provider must store this authentication token locally and pass it in each operation request that requires authentication. If using the instance provided authenticate operation handler, the handler initiates the creation of the authentication token based on a four-digit user-entered pin. It then sets the authentication token in the sessionAttributes object of the CTIOperationResponse object. The associated message transformer translates the sessionAttributes object into the CTI-specific payload and then sends it to the CTI provider. Note: If the authentication token is not passed, all requests to execute operation handlers with the auth_required flag set will fail. If you do not use authentication, you do not need to maintain authentication tokens. The ServiceNow base system provides working operation handlers and message transformers that enable connection to Amazon Connect. When building contact flows within Amazon Connect, there are two integration points between Amazon services and a ServiceNow instance: * Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function) * AWS Lex Bot (Get Customer Input) {#CTIOpReq-getAuthToken__ul_pqp_3hl_hlb}You can find the available operation handlers and message transformers for these integration points in the Operation Handlers \[sn_cti_operation_handler\] and Provider Message Transformer \[sn_cti_provider_msg_transormer\] tables. {#CTIOpReq-getAuthToken__table_bfd_c4x_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 2. Parameters] {#CTIOpReq-getAuthToken__table_bfd_c4x_zkb} {#CTIOpReq-getAuthToken__table_cfd_c4x_zkb__entry__2} | Type | Description | |-|-| | String | The authentication token associated with the current ServiceNow Voice user. | [Table 3. Returns] {#CTIOpReq-getAuthToken__table_cfd_c4x_zkb} (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); ## CTIOperationRequest - getInteractionRecord() {#ariaid-title4} Returns the interaction GlideRecord associated with the operation request. An interaction represents a customer request for assistance made through a chat, phone call, or in-person. Interactions can be routed to queues for assignment or assigned to agents directly. Interaction records are stored in the Interaction \[interaction\] table and can contain any type of data that describes service account interactions with a customer for a specific session. Interaction records are associated with a CTIOperationRequest object through the [CTIOperationRequest - setInteractionSysId(String Id)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setInteractionSysId_S "Sets the sys_id of the interaction record associated with the operation request on the current CTIOperationRequest object.") method. This method is typically called by the message transformer and must be called prior to calling the getInteractionRecord() method. {#CTIOpReq-getInteractionRecord__table_tt5_55g_ykb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 4. Parameters] {#CTIOpReq-getInteractionRecord__table_tt5_55g_ykb} {#CTIOpReq-getInteractionRecord__table_ut5_55g_ykb__entry__2} | Type | Description | |-|-| | GlideRecord | Interaction GlideRecord object associated with the current CTIOperationRequest object. If the interaction record sys_id has not been set on the CTIOperationRequest object, returns null. | [Table 5. Returns] {#CTIOpReq-getInteractionRecord__table_ut5_55g_ykb} (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) { var notes = '', lang = request.getLanguage(); try { // Returns the interaction record (GlideRecord) set on the passed in CTIOperationRequest object 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); ## CTIOperationRequest - getInteractionSysId() {#ariaid-title5} Returns the sys_id of the interaction record associated with the current CTIOperationRequest object. The [CTIOperationRequest - setInteractionSysId(String Id)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setInteractionSysId_S "Sets the sys_id of the interaction record associated with the operation request on the current CTIOperationRequest object.") method must have been called prior to calling this method. {#CTIOpReq-getInteractionSysId__table_cjp_gpg_ykb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 6. Parameters] {#CTIOpReq-getInteractionSysId__table_cjp_gpg_ykb} {#CTIOpReq-getInteractionSysId__table_djp_gpg_ykb__entry__2} | Type | Description | |-|-| | String | The sys_id of the interaction record set on the current CTIOperationRequest object. If the sys_id was not set on the associated CTIOperationRequest object, the method returns null. | [Table 7. Returns] {#CTIOpReq-getInteractionSysId__table_djp_gpg_ykb} (function( /*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) { // Returns the sys_id of the interaction record associated with the CTIOperationRequest object. var interactionSysId = request.getInteractionSysId(); var number = request.getParameter('number'); var addComment = request.getParameter('add_comment'); addComment = addComment ? addComment.toLowerCase() : addComment; addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment; var workNotes = request.getParameter('work_notes'); var message = gs.getMessage('Thankyou'); var interactionGr = request.getInteractionRecord(); var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null; if (openedFor && number && addComment && workNotes) { var now_GR = new GlideRecordSecure('incident'); now_GR.addQuery('caller_id', openedFor); now_GR.addQuery('number', number); now_GR.query(); if (now_GR.next()) { now_GR.work_notes += workNotes; now_GR.update(); message = gs.getMessage('Your comment was added'); } } response.setStatusCode(200); response.setMessage(message); })(request, response, ctx); ## CTIOperationRequest - getLanguage() {#ariaid-title6} Returns the ISO 639.1 language code that was set on the current CTIOperationRequest object. Using the customer preferred language enables you to use platform-provided internationalization and localization capabilities to customize messages and other communications with the associated caller. Typically an operation handler calls the getLanguage() method and the message transformer sets the language on the CTIOperationRequest object by calling the [CTIOperationRequest - setLanguage(String languageCode)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setLanguage_S "Sets the ISO 639.1 language code to use when processing the associated operation on a CTIOperationRequest object.") method. {#CTIOpReq-getLanguage__table_slx_ngx_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 8. Parameters] {#CTIOpReq-getLanguage__table_slx_ngx_zkb} {#CTIOpReq-getLanguage__table_tlx_ngx_zkb__entry__2} | Type | Description | |-|-| | String | The ISO 639.1 language code set on the current CTIOperationRequest object. If the language code is not set, returns en. | [Table 9. Returns] {#CTIOpReq-getLanguage__table_tlx_ngx_zkb} The following example shows an operation handler calling getLanguage() to obtain the caller's preferred language. (function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response) { // Obtain the contact's preferred language var notes = "", announcement, lang = request.getLanguage(); try { var interactionGr = request.getInteractionRecord(); announcement = gs.getMessageLang("We are currently experiencing issues with VPN. If you are calling about VPN issues, you may hang up the call.", lang); // Use the contact's language to customize the response messages and notes if(announcement) { notes = gs.getMessageLang("Listened to announcement: {0}", lang, [announcement]); response.setStatusCode(200); } else { announcement = gs.getMessageLang("There are currently no known outage announcements", lang); //use the status case as the flag to check for announcements in contact flow response.setStatusCode(404); } response.setMessage(announcement); if(interactionGr && notes) { interactionGr.work_notes = notes; interactionGr.update(); } } catch(e) { ctx.setError(e); } })(request, response); ## CTIOperationRequest - getMajorVersion() {#ariaid-title7} Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationRequest object. Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers. Typically the message transformer sets the software version on the CTIOperationRequest object by calling the [CTIOperationRequest - setMajorVersion(Number majorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMajorVersion_N "Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") method and an operation handler then consumes the set value using this method. You can also get/set the minor version value of a provider's software using the [CTIOperationRequest - getMinorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMinorVersion "Returns the minor version of the computer telephony integrator (CTI) software associated with a CTIOperationRequest object.") and [CTIOperationRequest - setMinorVersion(Number minorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMinorVersion_N "Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") methods. {#CTIOpReq-getMajorVersion__table_olp_qvg_ykb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 10. Parameters] {#CTIOpReq-getMajorVersion__table_olp_qvg_ykb} {#CTIOpReq-getMajorVersion__table_plp_qvg_ykb__entry__2} | Type | Description | |-|-| | Number | Major version number of the CTI software. If the major version was never set, returns 1. | [Table 11. Returns] {#CTIOpReq-getMajorVersion__table_plp_qvg_ykb} var request = new sn_cti_core.CTIOperationRequest('origin'); var majorVersion = request.getMajorVersion(); ## CTIOperationRequest - getMinorVersion() {#ariaid-title8} Returns the minor version of the computer telephony integrator (CTI) software associated with a CTIOperationRequest object. Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers. Typically the message transformer sets the software version on the CTIOperationRequest object by calling the [CTIOperationRequest - setMinorVersion(Number minorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMinorVersion_N "Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") [CTIOperationRequest - setMinorVersion(Number minorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMinorVersion_N "Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") method and an operation handler then consumes the set value using this method. You can also get/set the major version value of a provider's software using the [CTIOperationRequest - getMajorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMajorVersion "Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationRequest object.") [CTIOperationRequest - getMajorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMajorVersion "Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationRequest object.") and [CTIOperationRequest - setMajorVersion(Number majorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMajorVersion_N "Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") [CTIOperationRequest - setMajorVersion(Number majorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMajorVersion_N "Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") methods. {#CTIOpReq-getMinorVersion__table_chp_z41_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 12. Parameters] {#CTIOpReq-getMinorVersion__table_chp_z41_zkb} {#CTIOpReq-getMinorVersion__table_dhp_z41_zkb__entry__2} | Type | Description | |-|-| | Number | Minor version number of the CTI software. If the minor version was never set, returns 0. | [Table 13. Returns] {#CTIOpReq-getMinorVersion__table_dhp_z41_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var minorVersion = request.getMinorVersion(); ## CTIOperationRequest - getOperationName() {#ariaid-title9} Returns the name of the operation that the computer telephony integration (CTI) provider is requesting to execute. The operation name determines the operation handler that is used to process a request. Typically the message transformer sets the operation name on the CTIOperationRequest object using the [CTIOperationRequest - setOperationName(String name)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setOperationName_S "Sets the name of the operation that the computer telephony integration (CTI) provider is attempting to execute on the current CTIOperationRequest object.") method. Note: The getOperationName() method does not instantiate the associated operation handler. This is done by the ServiceNow Voiceframework. This method simply returns the associated operation handler name. Note: For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix (myOperation_SUFFX), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request (myOperation). {#CTIOpReq-getOperationName__table_kgj_tmw_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 14. Parameters] {#CTIOpReq-getOperationName__table_kgj_tmw_zkb} {#CTIOpReq-getOperationName__table_lgj_tmw_zkb__entry__2} | Type | Description | |-|-| | String | The name of the operation that the CTI provider is requesting to execute. If the operation name is not set, returns null. | [Table 15. Returns] {#CTIOpReq-getOperationName__table_lgj_tmw_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var name = request.getOperationName(); ## CTIOperationRequest - getOperationSubStepName() {#ariaid-title10} Returns the substep operation handler name set on the current CTIOperationRequest object. Use substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider.{#CTIOpReq-getOperationSubStepName__p_substeps_CTIOpReq} The ServiceNow Voice framework performs the following steps to locate the required operation handler and any associated substep operation handlers. Note: For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix (myOperation_SUFFX), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request (myOperation). 1. Tries to locate the operation handler associated with the request. * First checks for an operation handler called `myOperation_SUFFX`. * If not found, checks for the operation handler `myOperation`. If not found, errors out. {#CTIOpReq-getOperationSubStepName__ul_jwd_34c_glb} 2. If the handler is found, checks the auth_required flag on the operation handler. If set, it checks that a valid authentication token (obtained through the getAuthToken() method) is present on the request. If present and valid, continue processing, else throw an error. 3. Looks up the operation handler for the passed in substep. For this example let's assume `subStepName=SubStep`. * First checks for an operation handler named `myOperation_SUFFX.SubStep`. If found, executes the handler. * If not found, checks for the handler `myOperation.SubStep`. If found executes the handler. * If not found, checks if a `subStepNotFoundBehavior` was set on the request object. * If set, executes the behavior, otherwise, errors out. {#CTIOpReq-getOperationSubStepName__ul_i4n_dpc_glb} 4. Executes the primary operation handler (`myOpersation_SUFFX` or `myOperation`.) {#CTIOpReq-getOperationSubStepName__ol_yqk_h4c_glb} Typically the message transformer sets the substep name on the CTIOperationRequest object using the [CTIOperationRequest - setOperationSubStepName(String name)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setOperationSubStepName_S "Sets the operation substep name on the current CTIOperationRequest object.") method. You can override this behavior if you are creating your own transformer by calling the [CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setSubStepNotFoundBehav_O "Sets the behavior to perform if the current substep's operation handler is not found.") method. {#CTIOpReq-getOperationSubStepName__table_cbj_syw_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 16. Parameters] {#CTIOpReq-getOperationSubStepName__table_cbj_syw_zkb} {#CTIOpReq-getOperationSubStepName__table_dbj_syw_zkb__entry__2} | Type | Description | |-|-| | String | The name of the substep operation handler set on the CTIOperationRequest object. If it does not exist, returns null. | [Table 17. Returns] {#CTIOpReq-getOperationSubStepName__table_dbj_syw_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var name = request.getOperationSubStepName(); ## CTIOperationRequest - getParameter(String key) {#ariaid-title11} Returns the value of a specified key previously set on the current CTIOperationRequest object. Using the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation request. The operation handler determines what key/value pairs are required as it consumes these values. Typically the message transformer sets these parameters on the CTIOperationRequest object by calling the [CTIOperationRequest - setParameter(String key, Object value)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setParameter_S_O "Sets the specified key-value pair on the parameter object of the current CTIOperationRequest object.") method and the operation handler consumes them using this method. {#CTIOpReq-getParameter_S__table_n1d_rgr_zkb__entry__3} | Name | Type | Description | |-|-|-| | key | String | The name of the key value to return. | [Table 18. Parameters] {#CTIOpReq-getParameter_S__table_n1d_rgr_zkb} {#CTIOpReq-getParameter_S__table_o1d_rgr_zkb__entry__2} | Type | Description | |-|-| | String or Number | Value of the specified key. If no such key exists, returns null. | [Table 19. Returns] {#CTIOpReq-getParameter_S__table_o1d_rgr_zkb} (function( /*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) { var interactionSysId = request.getInteractionSysId(); // Returns the number and add_comment parameters from the CTIOperationRequest object var number = request.getParameter('number'); var addComment = request.getParameter('add_comment'); addComment = addComment ? addComment.toLowerCase() : addComment; addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment; var workNotes = request.getParameter('work_notes'); var message = gs.getMessage('Thankyou'); var interactionGr = request.getInteractionRecord(); var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null; if (openedFor && number && addComment && workNotes) { var now_GR = new GlideRecordSecure('incident'); now_GR.addQuery('caller_id', openedFor); now_GR.addQuery('number', number); now_GR.query(); if (now_GR.next()) { now_GR.work_notes += workNotes; now_GR.update(); message = gs.getMessage('Your comment was added'); } } response.setStatusCode(200); response.setMessage(message); })(request, response, ctx); ## CTIOperationRequest - getParameters() {#ariaid-title12} Returns the key-value pairs for all parameters that were previously set on the current CTIOperationRequest object. Using the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation request. The operation handler determines what key/value pairs are required as it consumes these values. Typically the message transformer sets these parameters on the CTIOperationRequest object by calling the [CTIOperationRequest - setParameter(String key, Object value)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setParameter_S_O "Sets the specified key-value pair on the parameter object of the current CTIOperationRequest object.") method and the operation handler consumes them using this method. {#CTIOpReq-getParameters__table_hcc_y3b_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 20. Parameters] {#CTIOpReq-getParameters__table_hcc_y3b_zkb} {#CTIOpReq-getParameters__table_icc_y3b_zkb__entry__2} | Type | Description | |-|-| | Object | A map of key-value pairs that were previously set on the CTIOperationRequest object. This key-value pairs are free-form and defined by the needs of the operation handler. The returned values are either Strings or Numbers. | [Table 21. Returns] {#CTIOpReq-getParameters__table_icc_y3b_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var parms = request.getParameters(); for(var key in parms) { gs.info(key + '=' + parms[key]); } ## CTIOperationRequest - getSessionAttribute(String key) {#ariaid-title13} Returns the value of a specified session attribute key set on the current CTIOperationRequest object. Using the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The sessionAttribute object can contain zero or more key/value pairs of data that are valid for the duration of a computer telephony integration provider defined session, such as the contact's phone number. Session attributes can also be accessed within a contact flow. The operation handler determines what session attribute key/value pairs are needed as it consumes these values. Typically the message transformer sets these attributes on the CTIOperationRequest object by calling the [CTIOperationRequest - setSessionAttribute(String key, Object value)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setSessionAttribute_S_O "Sets the specified session attribute key-value pair on the current CTIOperationRequest object.") method. Session attributes are different than parameters in that they persist for the life of the session (such as the entire call) and should be passed back by the CTI provider with each operation request within that call session. {#CTIOpReq-getSessionAttribute_S__table_v1k_cwr_zkb__entry__3} | Name | Type | Description | |-|-|-| | key | String | The name of the key value to return. | [Table 22. Parameters] {#CTIOpReq-getSessionAttribute_S__table_v1k_cwr_zkb} {#CTIOpReq-getSessionAttribute_S__table_w1k_cwr_zkb__entry__2} | Type | Description | |-|-| | String or Number | Value of the specified key. If no such key exists, returns null. | [Table 23. Returns] {#CTIOpReq-getSessionAttribute_S__table_w1k_cwr_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var phoneAttribute = request.getSessionAttribute('contact.phone'); ## CTIOperationRequest - getSessionAttributes() {#ariaid-title14} Returns a key-value pair map of all session attributes set on the current CTIOperationRequest object. Using the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The sessionAttribute object can contain zero or more key/value pairs of data that are valid for the duration of a computer telephony integration provider defined session, such as the contact's phone number. Session attributes can also be accessed within a contact flow. The operation handler determines what session attribute key/value pairs are needed as it consumes these values. Typically the message transformer sets these attributes on the CTIOperationRequest object by calling the [CTIOperationRequest - setSessionAttribute(String key, Object value)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setSessionAttribute_S_O "Sets the specified session attribute key-value pair on the current CTIOperationRequest object.") method. Session attributes are different than parameters in that they persist for the life of the session (such as the entire call) and should be passed back by the CTI provider with each operation request within that call session. {#CTIOpReq-getSessionAttributes__table_ujd_ltr_zkb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 24. Parameters] {#CTIOpReq-getSessionAttributes__table_ujd_ltr_zkb} {#CTIOpReq-getSessionAttributes__table_vjd_ltr_zkb__entry__2} | Type | Description | |-|-| | Object | A map of session attribute key-value pairs that were set on the associated CTIOperationResponse object. This map is free-form and defined by the needs of the operation handler. | [Table 25. Returns] {#CTIOpReq-getSessionAttributes__table_vjd_ltr_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); var parms = request.getSessionAttributes(); for(var key in parms) { gs.info(key + '=' + parms[key]); } ## CTIOperationRequest - getSubStepNotFoundBehaviour {#ariaid-title15} Returns the handling behavior for a subsep when a substep's operation handler is not found. Use substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider. If the requested substep operation handler cannot be found by the ServiceNow Voice framework, it attempts to use the "step not found behavior". This behavior is typically set by the message transformer when an operation is initially requested. {#CTIOpReq-getSubStepNotFoundBehaviour__table_gxb_rg2_1lb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 26. Parameters] {#CTIOpReq-getSubStepNotFoundBehaviour__table_gxb_rg2_1lb} {#CTIOpReq-getSubStepNotFoundBehaviour__table_hxb_rg2_1lb__entry__2} | Type | Description | |-|-| | OperationNotFoundBehaviours | The behavior/handling to perform when an operation handler cannot be found for the operation/substep combination (\.SubStep\>). If not defined, returns null. Possible values: * OperationNotFoundBehaviours.ThrowError: Throw an error. * OperationNotFoundBehaviours.PassThrough: Do not perform any further processing on the request, just return. * OperationNotFoundBehaviours.RouteToOperation: Use the parent operation handler \. {#CTIOpReq-getSubStepNotFoundBehaviour__ul_kbc_53f_1lb} | [Table 27. Returns] {#CTIOpReq-getSubStepNotFoundBehaviour__table_hxb_rg2_1lb} var request = new sn_cti_core.CTIOperationRequest('origin'); var behavior = request.getSubStepNotFoundBehaviour(); ## CTIOperationRequest - setAuthToken(String id) {#ariaid-title16} Sets an authentication token on the current CTIOperationRequest object. This token is used by the ServiceNow Voice framework to authenticate the current ServiceNow Voice user before executing the requested operation handler if the handler's auth_required flag is set to true. The auth_required flag is a field in the Operation Handler \[sn_cti_operation_handler\] table. The life of an authentication token should be for the life of the call session, but is determined by the CTI provider. You can define whatever authentication/authorization handling required by your implementation by creating your own authentication operation handler. Regardless of how the authentication token is generated, the message translator must pass the token back in the CTI payload. Additionally, the CTI provider must store this authentication token locally and pass it in each operation request that requires authentication. If using the instance provided authenticate operation handler, the handler initiates the creation of the authentication token based on a four-digit user-entered pin. It then sets the authentication token in the sessionAttributes object of the CTIOperationResponse object. The associated message transformer translates the sessionAttributes object into the CTI-specific payload and then sends it to the CTI provider. Note: If the authentication token is not passed, all requests to execute operation handlers with the auth_required flag set will fail. If you do not use authentication, you do not need to maintain authentication tokens. The ServiceNow base system provides working operation handlers and message transformers that enable connection to Amazon Connect. When building contact flows within Amazon Connect, there are two integration points between Amazon services and a ServiceNow instance: * Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function) * AWS Lex Bot (Get Customer Input) {#CTIOpReq-setAuthToken_S__ul_pqp_3hl_hlb}You can find the available operation handlers and message transformers for these integration points in the Operation Handlers \[sn_cti_operation_handler\] and Provider Message Transformer \[sn_cti_provider_msg_transormer\] tables. {#CTIOpReq-setAuthToken_S__table_xvb_3wx_zkb__entry__3} | Name | Type | Description | |-|-|-| | id | String | The authentication token for the associated ServiceNow Voice user. | [Table 28. Parameters] {#CTIOpReq-setAuthToken_S__table_xvb_3wx_zkb} {#CTIOpReq-setAuthToken_S__table_yvb_3wx_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 29. Returns] {#CTIOpReq-setAuthToken_S__table_yvb_3wx_zkb} Example of message transformer script that saves the passed in authentication token. { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; case 'statusCode': case 'message': break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setInteractionSysId(String Id) {#ariaid-title17} Sets the sys_id of the interaction record associated with the operation request on the current CTIOperationRequest object. If you want to maintain contact interaction information within a contact-specific interaction record, the interaction record sys_id must be maintained for the entire ServiceNow Voice call session. Typically, an operation handler creates an interaction record when a new contact call is initiated. It then sets the interaction record sys_id and table name on the associated CTIOperationResponse object as session attributes using the [CTIOperationRequest - setSessionAttribute(String key, Object value)](https://servicenow-prod.fluidtopics.net/5ijvP7RkHP~~EiAqN4XyIA#CTIOpResp-setSessionAttribute_S_O "Sets the specified session attribute key-value pair on the associated CTIOperationResponse object.") method. The associated method transformer then translates this information into the computer telephony integration (CTI) provider payload and sends it back to the CTI provider. The CTI provider must store the interaction record sys_id for the contact session locally. Each time the CTI provider interacts with the ServiceNow Voice for this contact session, it must pass back the corresponding interaction record sys_id in its payload. The receiving message transformer then parses the payload and uses the CTIOperationRequest - setInteractionSysId() method to set the interaction record sys_id on the associated CTIOperationtRequest object. The [CTIOperationRequest - getInteractionRecord()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getInteractionRecord "Returns the interaction GlideRecord associated with the operation request.") method uses this sys_id to obtain the correct interaction record for the contact session. Interaction records are located in the Interaction \[interaction\] table. For additional information on interaction records, see {#CTIOpReq-setInteractionSysId_S__table_usk_lrg_ykb__entry__3} | Name | Type | Description | |-|-|-| | sys_id | String | The sys_id of the interaction record to associate with the request. | [Table 30. Parameters] {#CTIOpReq-setInteractionSysId_S__table_usk_lrg_ykb} {#CTIOpReq-setInteractionSysId_S__table_vsk_lrg_ykb__entry__2} | Type | Description | |-|-| | void | | [Table 31. Returns] {#CTIOpReq-setInteractionSysId_S__table_vsk_lrg_ykb} Example of a message transformer script that extracts the interaction record sys_id from the incoming payload (passed as a parameter) and sets it on the associated CTIOperationRequest object. { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { // Associate the existing customer interaction record with the request case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; case 'statusCode': case 'message': break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setLanguage(String languageCode) {#ariaid-title18} Sets the ISO 639.1 language code to use when processing the associated operation on a CTIOperationRequest object. Using the customer preferred language enables you to use platform-provided internationalization and localization capabilities to customize messages and other communications with the associated caller. Typically the message transformer sets the language on the CTIOperationRequest object. {#CTIOpReq-setLanguage_S__table_fkv_blx_zkb__entry__3} | Name | Type | Description | |-|-|-| | languageCode | String | The ISO 639.1 language code to use when processing the associated operation. | [Table 32. Parameters] {#CTIOpReq-setLanguage_S__table_fkv_blx_zkb} {#CTIOpReq-setLanguage_S__table_gkv_blx_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 33. Returns] {#CTIOpReq-setLanguage_S__table_gkv_blx_zkb} { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; case 'statusCode': case 'message': break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setMajorVersion(Number majorVersion) {#ariaid-title19} Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object. Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers. Typically the message transformer sets the software version on the CTIOperationRequest object by calling this method and an operation handler then consumes the set value using the [CTIOperationRequest - getMajorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMajorVersion "Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationRequest object.") method. You can also get/set the minor version value of a provider's software using the [CTIOperationRequest - getMinorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMinorVersion "Returns the minor version of the computer telephony integrator (CTI) software associated with a CTIOperationRequest object.") and [CTIOperationRequest - setMinorVersion(Number minorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMinorVersion_N "Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") methods. {#CTIOpReq-setMajorVersion_N__table_jlt_pz1_zkb__entry__3} | Name | Type | Description | |-|-|-| | majorVersion | Number | Major version of the CTI provider software making the operation request. If this value was not previously set, returns 1. | [Table 34. Parameters] {#CTIOpReq-setMajorVersion_N__table_jlt_pz1_zkb} {#CTIOpReq-setMajorVersion_N__table_klt_pz1_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 35. Returns] {#CTIOpReq-setMajorVersion_N__table_klt_pz1_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); request.setMajorVersion(2); ## CTIOperationRequest - setMinorVersion(Number minorVersion) {#ariaid-title20} Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object. Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers. Typically the message transformer sets the software version on the CTIOperationRequest object by calling this method and an operation handler then consumes the set value using the [CTIOperationRequest - getMinorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMinorVersion "Returns the minor version of the computer telephony integrator (CTI) software associated with a CTIOperationRequest object.") method. You can also get/set the major version value of a provider's software using the [CTIOperationRequest - getMajorVersion()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getMajorVersion "Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationRequest object.") and [CTIOperationRequest - setMajorVersion(Number majorVersion)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setMajorVersion_N "Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationRequest object.") methods. {#CTIOpReq-setMinorVersion_N__table_zqj_52b_zkb__entry__3} | Name | Type | Description | |-|-|-| | minorVersion | Number | Minor version of the CTI provider software making the operation request. If this value was not previously set, returns 0. | [Table 36. Parameters] {#CTIOpReq-setMinorVersion_N__table_zqj_52b_zkb} {#CTIOpReq-setMinorVersion_N__table_arj_52b_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 37. Returns] {#CTIOpReq-setMinorVersion_N__table_arj_52b_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); ... request.setMinorVersion(3); ## CTIOperationRequest - setOperationName(String name) {#ariaid-title21} Sets the name of the operation that the computer telephony integration (CTI) provider is attempting to execute on the current CTIOperationRequest object. The operation name determines the operation handler that is used to process the request. Call this method from the associated message transformer. Note: For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix (myOperation_SUFFX), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request (myOperation). {#CTIOpReq-setOperationName_S__table_msx_jpw_zkb__entry__3} | Name | Type | Description | |-|-|-| | name | String | The name of the operation that the CTI provider is currently attempting to execute. This name must be the same as the name of the operation handler to use to process the request. If it is not, an error is thrown. You can locate the available operation handlers in the Operation Handler \[sn_cti_operation_handler\] table. | [Table 38. Parameters] {#CTIOpReq-setOperationName_S__table_msx_jpw_zkb} {#CTIOpReq-setOperationName_S__table_nsx_jpw_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 39. Returns] {#CTIOpReq-setOperationName_S__table_nsx_jpw_zkb} { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { // Set the operation handler to use to process the request operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; case 'statusCode': case 'message': break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setOperationSubStepName(String name) {#ariaid-title22} Sets the operation substep name on the current CTIOperationRequest object. Use substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider.{#CTIOpReq-setOperationSubStepName_S__p_substeps_CTIOpReq} The ServiceNow Voice framework performs the following steps to locate the required operation handler and any associated substep operation handlers. Note: For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix (myOperation_SUFFX), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request (myOperation). 1. Tries to locate the operation handler associated with the request. * First checks for an operation handler called `myOperation_SUFFX`. * If not found, checks for the operation handler `myOperation`. If not found, errors out. {#CTIOpReq-setOperationSubStepName_S__ul_jwd_34c_glb} 2. If the handler is found, checks the auth_required flag on the operation handler. If set, it checks that a valid authentication token (obtained through the getAuthToken() method) is present on the request. If present and valid, continue processing, else throw an error. 3. Looks up the operation handler for the passed in substep. For this example let's assume `subStepName=SubStep`. * First checks for an operation handler named `myOperation_SUFFX.SubStep`. If found, executes the handler. * If not found, checks for the handler `myOperation.SubStep`. If found executes the handler. * If not found, checks if a `subStepNotFoundBehavior` was set on the request object. * If set, executes the behavior, otherwise, errors out. {#CTIOpReq-setOperationSubStepName_S__ul_i4n_dpc_glb} 4. Executes the primary operation handler (`myOpersation_SUFFX` or `myOperation`.) {#CTIOpReq-setOperationSubStepName_S__ol_yqk_h4c_glb} You can set the default behavior of a substep by calling the [CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-setSubStepNotFoundBehav_O "Sets the behavior to perform if the current substep's operation handler is not found.") method. {#CTIOpReq-setOperationSubStepName_S__table_sf4_t2x_zkb__entry__3} | Name | Type | Description | |-|-|-| | name | String | The name of the substep that the CTI provider is trying to execute. | [Table 40. Parameters] {#CTIOpReq-setOperationSubStepName_S__table_sf4_t2x_zkb} {#CTIOpReq-setOperationSubStepName_S__table_tf4_t2x_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 41. Returns] {#CTIOpReq-setOperationSubStepName_S__table_tf4_t2x_zkb} (function( /*HTTPRequest*/ httpRequest, /*CTIOperationRequest*/ operationRequest, /*Context*/ ctx) { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var intent = event.currentIntent; var inputTranscript = event.inputTranscript; if(inputTranscript) { operationRequest.setParameter('$utterance', inputTranscript); } if (intent) { operationRequest.setOperationName(intent.name); // Add this because intent name gets changed through the pipeline operationRequest.setParameter('$original_intent', intent.name); var sessionAttributes = event.sessionAttributes; if (sessionAttributes) { for (var sk in sessionAttributes) { switch (sk) { case 'interactionId': operationRequest.setInteractionSysId(sessionAttributes[sk]); break; case 'authToken': operationRequest.setAuthToken(sessionAttributes[sk]); break; case 'language': operationRequest.setLanguage(sessionAttributes[sk]); break; case 'statusCode': case 'message': break; default: operationRequest.setSessionAttribute(sk, sessionAttributes[sk]); } } } var slots = intent.slots; // Always copy in slots they are the parameters for the operation if (slots) { for (var pk in slots) { operationRequest.setParameter(pk, slots[pk]); } } var invocationSource = event.invocationSource; operationRequest.setParameter('$$invocationSource', invocationSource); // Specific handling for dialog hooks with a way to override for Amazon specific provider if (invocationSource === 'DialogCodeHook') { // Set substep to trigger forwarding to another handler IF it s present operationRequest.setOperationSubStepName(invocationSource); // Allow pass through behavior var behaviourToUse = sn_cti_core.CTIOperationRequest.OperationNotFoundBehaviours.PassThrough; operationRequest.setSubStepNotFoundBehaviour(behaviourToUse); // Reserved - copy slots in so we can just use delegate as default if the call isn't handled operationRequest.setParameter('$$slots', slots); } } } } } catch (e) { ctx.setError(e); } return operationRequest; })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setParameter(String key, Object value) {#ariaid-title23} Sets the specified key-value pair on the parameter object of the current CTIOperationRequest object. Using the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation request. The operation handler determines what key/value pairs are required as it consumes these values. Typically the message transformer sets these parameters on the CTIOperationRequest object by calling this method and the operation handler consumes them using the [CTIOperationRequest - getParameter(String key)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getParameter_S "Returns the value of a specified key previously set on the current CTIOperationRequest object.") or [CTIOperationRequest - getParameters()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getParameters "Returns the key-value pairs for all parameters that were previously set on the current CTIOperationRequest object.") method. Note: You should only store objects that can survive a `JSON.parse(JSON.stringify(object))` operation. Objects not meeting this criteria may not propagate correctly through the entire operation processing chain. For example: 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); Produces: {"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"}} {#CTIOpReq-setParameter_S_O__table_ab4_k3r_zkb__entry__3} | Name | Type | Description | |-|-|-| | key | String | Name of the key under which to store the associated value. | | value | Object | Value to store. Valid data types: * string * int * float * number * boolean * date * object {#CTIOpReq-setParameter_S_O__ul_mcs_2sr_zkb} | [Table 42. Parameters] {#CTIOpReq-setParameter_S_O__table_ab4_k3r_zkb} {#CTIOpReq-setParameter_S_O__table_bb4_k3r_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 43. Returns] {#CTIOpReq-setParameter_S_O__table_bb4_k3r_zkb} { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var details = event.Details; if (details) { operationRequest.setOperationName(details.Parameters['sn_operation']); var contactData = details.ContactData; if(contactData) { // Call id should be surfaced in openframe call log so it can be tied to transcription later operationRequest.setParameter('contact.call_id', contactData.ContactId); for(var ck in contactData.CustomerEndpoint) { operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]); } operationRequest.setParameter('contact.id', contactData.ContactId); operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address); } var parameters = details.Parameters; if (parameters) { for (var pk in parameters) { switch(pk) { case 'interactionId': operationRequest.setInteractionSysId(parameters[pk]); break; case 'authToken': operationRequest.setAuthToken(parameters[pk]); break; case 'language': operationRequest.setLanguage(parameters[pk]); break; case 'statusCode': case 'message': break; default: operationRequest.setParameter(pk, parameters[pk]); } } } } } } } catch(e) { ctx.setError(e); } })(httpRequest, operationRequest, ctx); ## CTIOperationRequest - setSessionAttribute(String key, Object value) {#ariaid-title24} Sets the specified session attribute key-value pair on the current CTIOperationRequest object. Using the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. The sessionAttribute object can contain zero or more key/value pairs of data that are valid for the duration of a computer telephony integration provider defined session. Session attributes can also be accessed within a contact flow. The operation handler determines what session attribute key/value pairs are needed as it consumes these values. Typically the message transformer sets these attributes on the CTIOperationRequest object by calling this method and the operation handler gets the attributes using the [CTIOperationRequest - getSessionAttribute(String key)](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getSessionAttribute_S "Returns the value of a specified session attribute key set on the current CTIOperationRequest object.") or [CTIOperationRequest - getSessionAttribute()](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOpReq-getSessionAttributes "Returns a key-value pair map of all session attributes set on the current CTIOperationRequest object.") method. Note: You should only store objects that can survive a `JSON.parse(JSON.stringify(object))` operation. Objects not meeting this criteria may not propagate correctly through the entire operation processing chain. For example: 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); Produces: {"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"}} {#CTIOpReq-setSessionAttribute_S_O__table_ihm_rxr_zkb__entry__3} | Name | Type | Description | |-|-|-| | key | String | Name of the key under which to store the associated value. | | value | Object | Value to store. Valid data types: * string * int * float * number * boolean * date * object {#CTIOpReq-setSessionAttribute_S_O__ul_mcs_2sr_zkb} | [Table 44. Parameters] {#CTIOpReq-setSessionAttribute_S_O__table_ihm_rxr_zkb} {#CTIOpReq-setSessionAttribute_S_O__table_jhm_rxr_zkb__entry__2} | Type | Description | |-|-| | void | | [Table 45. Returns] {#CTIOpReq-setSessionAttribute_S_O__table_jhm_rxr_zkb} var request = new sn_cti_core.CTIOperationRequest('origin'); request.setSessionAttribute('contact.phone', '+15552222345'); request.setSessionAttribute('contact.okToCall', true); request.setSessionAttribute('contact.address', { street: '1234 Main St' city: 'API City', zip: 91335 }); ## CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour) {#ariaid-title25} Sets the behavior to perform if the current substep's operation handler is not found. This method should be called by the input message transformer. {#CTIOpReq-setSubStepNotFoundBehav_O__table_k4q_dmf_1lb__entry__3} | Name | Type | Description | |-|-|-| | behaviour | OperationNotFoundBehaviours | Behavior to use if a handling behavior is not specified for the substep. This must be a behavior defined on the CTIOperationRequest.OperationNotFoundBehaviours object. Possible values: * ThrowError: Throw an error. * PassThrough: Do not perform any further processing on the request, just return. * RouteToOperation: Use the parent operation handler \. {#CTIOpReq-setSubStepNotFoundBehav_O__ul_kbc_53f_1lb} | [Table 46. Parameters] {#CTIOpReq-setSubStepNotFoundBehav_O__table_k4q_dmf_1lb} {#CTIOpReq-setSubStepNotFoundBehav_O__table_l4q_dmf_1lb__entry__2} | Type | Description | |-|-| | void | | [Table 47. Returns] {#CTIOpReq-setSubStepNotFoundBehav_O__table_l4q_dmf_1lb} (function( /*HTTPRequest*/ httpRequest, /*CTIOperationRequest*/ operationRequest, /*Context*/ ctx) { try { var jsonPayload = httpRequest.body.data; if (jsonPayload) { var event = jsonPayload.event; if (event) { var intent = event.currentIntent; var inputTranscript = event.inputTranscript; if(inputTranscript) { operationRequest.setParameter('$utterance', inputTranscript); } if (intent) { operationRequest.setOperationName(intent.name); // Add this because intent name gets changed through the pipeline operationRequest.setParameter('$original_intent', intent.name); var sessionAttributes = event.sessionAttributes; if (sessionAttributes) { for (var sk in sessionAttributes) { switch (sk) { case 'interactionId': operationRequest.setInteractionSysId(sessionAttributes[sk]); break; case 'authToken': operationRequest.setAuthToken(sessionAttributes[sk]); break; case 'language': operationRequest.setLanguage(sessionAttributes[sk]); break; case 'statusCode': case 'message': break; default: operationRequest.setSessionAttribute(sk, sessionAttributes[sk]); } } } var slots = intent.slots; // Always copy in slots they are the parameters for the operation if (slots) { for (var pk in slots) { operationRequest.setParameter(pk, slots[pk]); } } var invocationSource = event.invocationSource; operationRequest.setParameter('$$invocationSource', invocationSource); // Specific handling for dialog hooks with a way to overide for Amazon specific provider if (invocationSource === 'DialogCodeHook') { // Set substep to trigger forwarding to another handler IF it s present operationRequest.setOperationSubStepName(invocationSource); // Allow pass through behavior var behaviourToUse = sn_cti_core.CTIOperationRequest.OperationNotFoundBehaviours.PassThrough; operationRequest.setSubStepNotFoundBehaviour(behaviourToUse); // Reserved - copy slots in so we can just use delegate as default if the call isn't handled operationRequest.setParameter('$$slots', slots); } } } } } catch (e) { ctx.setError(e); } return operationRequest; })(httpRequest, operationRequest, ctx);