CTIOperationRequest - Scoped, Global
-
- UpdatedJan 30, 2025
- 27 minutes to read
- Yokohama
- API reference
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.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
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.
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.
For additional information on creating operation handlers, see Configure a contact flow for an automated caller interaction.
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.
For additional information on the ServiceNow Voice, see ServiceNow Voice.
CTIOperationRequest - CTIOperationRequest(String origin)
Instantiates a CTIOperationRequest object.
Name | Type | Description |
---|---|---|
origin | String | Optional. Origin of the request. Usually the name of the computer telephony
integrator provider. Default: null |
Example
CTIOperationRequest - getAuthToken()
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.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The authentication token associated with the current ServiceNow Voice user. |
Example
CTIOperationRequest - getInteractionRecord()
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) method. This method is typically called by the message transformer and must be called prior to calling the getInteractionRecord() method.
Name | Type | Description |
---|---|---|
None |
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. |
Example
CTIOperationRequest - getInteractionSysId()
Returns the sys_id of the interaction record associated with the current CTIOperationRequest object.
The CTIOperationRequest - setInteractionSysId(String Id) method must have been called prior to calling this method.
Name | Type | Description |
---|---|---|
None |
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. |
Example
CTIOperationRequest - getLanguage()
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) method.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The ISO 639.1 language code set on the current CTIOperationRequest object. If the language code is not set, returns en. |
Example
The following example shows an operation handler calling getLanguage() to obtain the caller's preferred language.
CTIOperationRequest - getMajorVersion()
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) 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() and CTIOperationRequest - setMinorVersion(Number minorVersion) methods.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Number | Major version number of the CTI software. If the major version was never set, returns 1. |
Example
CTIOperationRequest - getMinorVersion()
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) CTIOperationRequest - setMinorVersion(Number minorVersion) 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() CTIOperationRequest - getMajorVersion() and CTIOperationRequest - setMajorVersion(Number majorVersion) CTIOperationRequest - setMajorVersion(Number majorVersion) methods.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Number | Minor version number of the CTI software. If the minor version was never set, returns 0. |
Example
CTIOperationRequest - getOperationName()
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) method.
Name | Type | Description |
---|---|---|
None |
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. |
Example
CTIOperationRequest - getOperationSubStepName()
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.
- 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.
- First checks for an operation handler called
- 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.
- 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.
- First checks for an operation handler named
- Executes the primary operation handler (
myOpersation_SUFFX
ormyOperation
.)
Typically the message transformer sets the substep name on the CTIOperationRequest object using the CTIOperationRequest - setOperationSubStepName(String name) method. You can override this behavior if you are creating your own transformer by calling the CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour) method.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The name of the substep operation handler set on the CTIOperationRequest object. If it does not exist, returns null. |
Example
CTIOperationRequest - getParameter(String key)
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) method and the operation handler consumes them using this method.
Name | Type | Description |
---|---|---|
key | String | The name of the key value to return. |
Type | Description |
---|---|
String or Number | Value of the specified key. If no such key exists, returns null. |
Example
CTIOperationRequest - getParameters()
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) method and the operation handler consumes them using this method.
Name | Type | Description |
---|---|---|
None |
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. |
Example
CTIOperationRequest - getSessionAttribute(String key)
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) 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.
Name | Type | Description |
---|---|---|
key | String | The name of the key value to return. |
Type | Description |
---|---|
String or Number | Value of the specified key. If no such key exists, returns null. |
Example
CTIOperationRequest - getSessionAttributes()
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) 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.
Name | Type | Description |
---|---|---|
None |
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. |
Example
CTIOperationRequest - getSubStepNotFoundBehaviour
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.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
OperationNotFoundBehaviours | The behavior/handling to perform when an operation handler cannot be found for
the operation/substep combination
(<operation_name>.SubStep>). If not defined, returns
null. Possible values:
|
Example
CTIOperationRequest - setAuthToken(String id)
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.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
Name | Type | Description |
---|---|---|
id | String | The authentication token for the associated ServiceNow Voice user. |
Type | Description |
---|---|
void |
Example
Example of message transformer script that saves the passed in authentication token.
CTIOperationRequest - setInteractionSysId(String Id)
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) 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() method uses this sys_id to obtain the correct interaction record for the contact session.
Name | Type | Description |
---|---|---|
sys_id | String | Sys_id of the interaction record to associate with the request. Table: Interaction [interaction] |
Type | Description |
---|---|
void |
Example
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.
CTIOperationRequest - setLanguage(String languageCode)
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.
Name | Type | Description |
---|---|---|
languageCode | String | The ISO 639.1 language code to use when processing the associated operation. |
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setMajorVersion(Number majorVersion)
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() method. You can also get/set the minor version value of a provider's software using the CTIOperationRequest - getMinorVersion() and CTIOperationRequest - setMinorVersion(Number minorVersion) methods.
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. |
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setMinorVersion(Number minorVersion)
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() method. You can also get/set the major version value of a provider's software using the CTIOperationRequest - getMajorVersion() and CTIOperationRequest - setMajorVersion(Number majorVersion) methods.
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. |
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setOperationName(String name)
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.
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. |
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setOperationSubStepName(String name)
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.
- 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.
- First checks for an operation handler called
- 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.
- 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.
- First checks for an operation handler named
- Executes the primary operation handler (
myOpersation_SUFFX
ormyOperation
.)
You can set the default behavior of a substep by calling the CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour) method.
Name | Type | Description |
---|---|---|
name | String | The name of the substep that the CTI provider is trying to execute. |
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setParameter(String key, Object value)
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) or CTIOperationRequest - getParameters() method.
JSON.parse(JSON.stringify(object))
operation. Objects not meeting this
criteria may not propagate correctly through the entire operation processing chain.Name | Type | Description |
---|---|---|
key | String | Name of the key under which to store the associated value. |
value | Object | Value to store. Valid data types:
|
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setSessionAttribute(String key, Object value)
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) or CTIOperationRequest - getSessionAttribute() method.
JSON.parse(JSON.stringify(object))
operation. Objects not meeting this
criteria may not propagate correctly through the entire operation processing chain.Name | Type | Description |
---|---|---|
key | String | Name of the key under which to store the associated value. |
value | Object | Value to store. Valid data types:
|
Type | Description |
---|---|
void |
Example
CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour)
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.
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:
|
Type | Description |
---|---|
void |
Example
On this page
- CTIOperationRequest - CTIOperationRequest(String origin)
- CTIOperationRequest - getAuthToken()
- CTIOperationRequest - getInteractionRecord()
- CTIOperationRequest - getInteractionSysId()
- CTIOperationRequest - getLanguage()
- CTIOperationRequest - getMajorVersion()
- CTIOperationRequest - getMinorVersion()
- CTIOperationRequest - getOperationName()
- CTIOperationRequest - getOperationSubStepName()
- CTIOperationRequest - getParameter(String key)
- CTIOperationRequest - getParameters()
- CTIOperationRequest - getSessionAttribute(String key)
- CTIOperationRequest - getSessionAttributes()
- CTIOperationRequest - getSubStepNotFoundBehaviour
- CTIOperationRequest - setAuthToken(String id)
- CTIOperationRequest - setInteractionSysId(String Id)
- CTIOperationRequest - setLanguage(String languageCode)
- CTIOperationRequest - setMajorVersion(Number majorVersion)
- CTIOperationRequest - setMinorVersion(Number minorVersion)
- CTIOperationRequest - setOperationName(String name)
- CTIOperationRequest - setOperationSubStepName(String name)
- CTIOperationRequest - setParameter(String key, Object value)
- CTIOperationRequest - setSessionAttribute(String key, Object value)
- CTIOperationRequest - setSubStepNotFoundBehaviour(Object behaviour)