RESTMessageV2 - Scoped, Global
-
- UpdatedFeb 1, 2024
- 11 minutes to read
- Washington DC
- API reference
The RESTMessageV2 API allows you to send outbound REST messages using JavaScript.
Use the RESTResponseV2 API to manage the response returned by the REST provider.
The User-Agent value is "ServiceNow/1.0". To change this, add the glide.http.user.agent system property in the System Properties [sys_properties] table.
This API runs in the sn_ws
namespace.
RESTMessageV2 - disableForcedVariableSubstitution()
Disables forced variable substitution in outbound REST messages.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - execute()
Sends the REST message to the endpoint.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
RESTResponse | The response returned by the REST provider. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - executeAsync()
Sends the REST message to the endpoint asynchronously. The instance does not wait for a response from the web service provider when making asynchronous calls.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
RESTResponse | The response returned by the REST provider. |
In the following example, replace REST_message_record with the name of
the REST message record from your instance. When using executeAsync
,
consider processing the response body in a separate business rule to take advantage of the
asynchronous call.
Example
RESTMessageV2 - getEndpoint()
Gets the URL of the endpoint for the REST message.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The URL of the REST web service provider. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - getRequestBody()
Gets the content of the REST message body.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | the REST message body. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - getRequestHeader(String headerName)
Gets the value for an HTTP header specified in the REST message.
By default, this method cannot return the value for a header set automatically by the system. To grant this method access to all headers, set the property glide.http.log_debug to true.
Name | Type | Description |
---|---|---|
headerName | String | Request header you want to get the value for. |
Type | Description |
---|---|
String | The value of the specified header. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - getRequestHeaders()
Gets HTTP headers that were set by the REST client and the associated values.
This method does not return headers set automatically by the system. To configure this method to return all headers, set the property glide.http.log_debug to true.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Object | An Object that maps the name of each header to the associated value. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - RESTMessageV2()
Instantiates an empty RESTMessageV2 object.
When using an object instantiated this way, you must manually specify an HTTP method and endpoint.
Name | Type | Description |
---|---|---|
None |
Example
RESTMessageV2 - RESTMessageV2(String name, String methodName)
Instantiates a RESTMessageV2 object using information from a REST message record.
You must have a REST message record defined before you can use this constructor.
Name | Type | Description |
---|---|---|
name | String | The name of the REST message record. |
methodName | String | The name of the HTTP method to use, such as GET/get or PUT/put - case insensitive. |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - saveResponseBodyAsAttachment(String tableName, String recordSysId, String fileName)
Configures the REST message to save the returned response body as an attachment record.
When you use this function with a REST message that is sent through a MID server, the MID server user must have any roles required to read and write attachment records, as well as any roles required to read and write records on the table specified in the tableName parameter.
The response body does not need to be a binary file to be saved as an attachment. Response bodies using text formats, such as JSON or XML can also be saved. If the instance fails to save the attachment, call getErrorMessage() on the related RESTResponseV2 object for error details.
Name | Type | Description |
---|---|---|
tableName | String | Specify the table that contains the record you want to attach the saved file to. |
recordSysId | String | Specify the sys_id of the record you want to attach the saved file to. |
fileName | String | Specify the file name to give to the saved file. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - saveResponseBodyAsAttachment(String tableName, String recordSysId, String fileName, String encryptContext)
Configures the REST message to save the returned response body as an encrypted attachment record.
When you use this function with a REST message that is sent through a MID server, the MID server user must have any roles required to read and write attachment records, as well as any roles required to read and write records on the table specified in the tableName parameter.
The response body does not need to be a binary file to be saved as an attachment. Response bodies using text formats, such as JSON or XML can also be saved. If the instance fails to save the attachment, call getErrorMessage() on the related RESTResponseV2 object for error details.
Type | Description |
---|---|
void |
RESTMessageV2 - setAuthenticationProfile(String type, String profileId)
Sets the credentials for the REST message using an existing basic auth or OAuth 2.0 profile.
Name | Type | Description |
---|---|---|
type | String | The type of authentication profile to use. Valid values are 'basic' to use basic authentication, or 'oauth2' to use OAuth 2.0. |
profileId | String | The sys_id of an authentication profile record. When using basic auth, specify the sys_id of a Basic Auth Configuration [sys_auth_profile_basic] record. When using OAuth 2.0, specify the sys_id of a OAuth Entity Profile [oauth_entity_profile] record. |
Type | Description |
---|---|
void |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - setBasicAuth(String userName, String userPass)
Sets basic authentication headers for the REST message.
Setting security values using this method overrides basic authentication values defined for the REST message record.
Name | Type | Description |
---|---|---|
userName | String | Username you want to use to authenticate the REST message. |
userPass | String | Password for the specified user. |
Type | Description |
---|---|
void |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - setEccCorrelator(String correlator)
Associates outbound requests and the resulting response record in the ECC queue. This method only applies to REST messages sent through a MID Server.
The correlator provided populates the Agent correlator field on the ECC queue record for the response. Provide a unique correlator for each outbound request to associate the correct results in the ECC queue with the request when designing asynchronous automation through a MID Server.
Name | Type | Description |
---|---|---|
correlator | String | Unique identifier |
Type | Description |
---|---|
void |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - setEccParameter(String name, String value)
Overrides a value from the database by writing to the REST message payload. This method only applies to REST messages sent through a MID Server.
Use this method when a value from the REST message in the database is invalid, such as when the endpoint URL is longer than the maximum REST endpoint field length. You can set only the endpoint URL using this method by passing source as the name parameter.
Name | Type | Description |
---|---|---|
name | String | The name of the parameter, such as source. |
value | String | The value to assign to the specified parameter. |
Type | Description |
---|---|
void |
In the following example, replace REST_message_record with the name of the REST message record from your instance.
Example
RESTMessageV2 - setEndpoint(String endpoint)
Sets the endpoint for the REST message.
By default, the REST message uses the endpoint specified in the REST message record. Use this method to override this default. You must call this method when using the RESTMessageV2 - RESTMessageV2() constructor with no parameters.
Name | Type | Description |
---|---|---|
endpoint | String | The URL of the REST provider you want to interface with. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setHttpMethod(String method)
Sets the HTTP method this REST message performs, such as GET or PUT.
You must set an HTTP method when using the RESTMessageV2 - RESTMessageV2() constructor with no parameters.
Name | Type | Description |
---|---|---|
method | String | HTTP method to perform. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setHttpTimeout(Number timeoutMs)
Sets the amount of time the REST message waits for a response from the web service provider before the request times out.
Name | Type | Description |
---|---|---|
timeoutMs | Number | Amount of time in milliseconds before the call to the REST provider times out. Note: This value sets a timeout on the socket and only times out if the socket
does not receive data within the specified time. For environments in which
responses are streamed, it's possible that connections last much longer than the
timeout value. |
Type | Description |
---|---|
None |
Example
To use the following example, replace <REST_message_record> with the name of the REST message record from your instance.
RESTMessageV2 - setLogLevel(String level)
Sets the log level for this message and the corresponding response.
Setting a log level using the RESTMessageV2 API overrides the log level configured on the REST message record. This log level may not apply if the endpoint domain is excluded, or if the property glide.outbound_http_log.override is true. To view outbound web service logs, navigate to .
Name | Type | Description |
---|---|---|
level | String | The log level. Valid values are basic, elevated, and all. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setMIDServer(String midServer)
Configures the REST message to communicate through a MID Server.
Name | Type | Description |
---|---|---|
midServer | String | Name of the MID Server to use. Your instance must have an active MID Server with the specified name. |
Type | Description |
---|---|
void |
Example
In the following example, replace REST_message_record with the name of the REST message record from your instance.
RESTMessageV2 - setMutualAuth(String profileName)
Sets the mutual authentication protocol profile for the REST message.
Setting a protocol profile using this method overrides the protocol profile selected for the REST message record.
Name | Type | Description |
---|---|---|
profileName | String | The Name of the protocol profile to use for mutual authentication. |
Type | Description |
---|---|
void |
Example
In the following example, replace REST_message_record with the name of the REST message record from your instance.
RESTMessageV2 - setQueryParameter(String name, String value)
Appends a parameter to the end of the request URL with the form name=value.
For example, the code setQueryParameter("sysparm_query","active=true^ORDERBYnumber^ORDERBYDESCcategory"); appends the text sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory to the request URL.
Name | Type | Description |
---|---|---|
name | String | Name of the URL parameter to pass. |
value | String | Value to assign the URL parameter. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setRequestBody(String body)
Sets the body content to send to the web service provider when using PUT or POST HTTP methods.
When you set the body content using this method, variables in the body are not substituted for parameters from the REST message function record. You must explicitly define all values within the REST message body.
Name | Type | Description |
---|---|---|
body | String | Request body to send. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setRequestBodyFromAttachment(String attachmentSysId)
Sets the request body using an existing attachment record.
When you use this function with a REST message that is sent through a MID Server, the MID Server user must have any roles required to read attachment records.
Name | Type | Description |
---|---|---|
attachmentSysId | String | Sys_id of the Attachment [sys_attachment] record you want to send in this REST message. |
Type | Description |
---|---|
void |
Example
RESTMessageV2 - setRequestHeader(String name, String value)
Sets an HTTP header in the REST message to the specified value.
Name | Type | Description |
---|---|---|
name | String | Name of the header. |
value | String | Value to assign to the specified header. |
Type | Description |
---|---|
void |
Example
In the following example, replace REST_message_record with the name of the REST message record from your instance.
RESTMessageV2 - setRequestorProfile(String requestorContext, String requestorId)
Overrides the default requestor profile for the REST message in order to retrieve an OAuth access token associated with a different requestor.
This method applies only to REST messages configured to use OAuth 2.0 authentication. This method is optional and is unnecessary in most configurations.
Name | Type | Description |
---|---|---|
requestorContext | String | |
requestorId | String |
Type | Description |
---|---|
void |
RESTMessageV2 - setStringParameter(String name, String value)
Sets a REST message function variable with the specified name from the REST message record to the specified value.
XML reserved characters in the value are converted to the equivalent escaped characters. Use setStringParameterNoEscape to set a variable without escaping XML reserved characters.
Name | Type | Description |
---|---|---|
name | String | Name of the REST message variable. This parameter must be defined in the REST message record before you can assign a value to it. |
value | String | Value to assign the variable. |
Type | Description |
---|---|
void |
Example
In the following example, replace REST_message_record with the name of the REST message record from your instance.
RESTMessageV2 - setStringParameterNoEscape(String name, String value)
Sets a REST message function variable with the specified name from the REST message record to the specified value.
This method is equivalent to setStringParameter but does not escape XML reserved characters.
Name | Type | Description |
---|---|---|
name | String | Name of the REST message variable. This parameter must be defined in the REST message record before you can assign a value to it. |
value | String | Value to assign the variable. |
Type | Description |
---|---|
void |
Example
In the following example, replace REST_message_record with the name of the REST message record from your instance.
On this page
- RESTMessageV2 - disableForcedVariableSubstitution()
- RESTMessageV2 - execute()
- RESTMessageV2 - executeAsync()
- RESTMessageV2 - getEndpoint()
- RESTMessageV2 - getRequestBody()
- RESTMessageV2 - getRequestHeader(String headerName)
- RESTMessageV2 - getRequestHeaders()
- RESTMessageV2 - RESTMessageV2()
- RESTMessageV2 - RESTMessageV2(String name, String methodName)
- RESTMessageV2 - saveResponseBodyAsAttachment(String tableName, String recordSysId, String
fileName)
- RESTMessageV2 - saveResponseBodyAsAttachment(String tableName, String recordSysId, String
fileName, String encryptContext)
- RESTMessageV2 - setAuthenticationProfile(String type, String profileId)
- RESTMessageV2 - setBasicAuth(String userName, String userPass)
- RESTMessageV2 - setEccCorrelator(String correlator)
- RESTMessageV2 - setEccParameter(String name, String value)
- RESTMessageV2 - setEndpoint(String endpoint)
- RESTMessageV2 - setHttpMethod(String method)
- RESTMessageV2 - setHttpTimeout(Number timeoutMs)
- RESTMessageV2 - setLogLevel(String level)
- RESTMessageV2 - setMIDServer(String midServer)
- RESTMessageV2 - setMutualAuth(String profileName)
- RESTMessageV2 - setQueryParameter(String name, String value)
- RESTMessageV2 - setRequestBody(String body)
- RESTMessageV2 - setRequestBodyFromAttachment(String attachmentSysId)
- RESTMessageV2 - setRequestHeader(String name, String value)
- RESTMessageV2 - setRequestorProfile(String requestorContext, String requestorId)
- RESTMessageV2 - setStringParameter(String name, String value)
- RESTMessageV2 - setStringParameterNoEscape(String name, String value)