Outbound REST Messages

Outbound REST Messages in ServiceNow – Complete Guide for CAD Exam

Why Outbound REST Messages Matter

Modern enterprises rarely operate in isolation. ServiceNow frequently needs to communicate with external systems — whether it is sending data to a third-party cloud application, triggering an action in an external tool, or retrieving information from an outside API. Outbound REST Messages are the primary mechanism ServiceNow provides for making HTTP calls to external REST APIs. Understanding them is critical for the Certified Application Developer (CAD) exam because integration is a core competency tested across multiple question domains.

---

What Is an Outbound REST Message?

An Outbound REST Message is a ServiceNow record that defines how ServiceNow will call an external REST API. It encapsulates:

• Endpoint URL – The external API URL that ServiceNow will call.
• HTTP Method(s) – GET, POST, PUT, PATCH, DELETE, etc.
• Authentication – Basic, OAuth 2.0, Mutual Auth, or no authentication.
• HTTP Headers – Custom headers required by the external API (e.g., Content-Type, Accept).
• HTTP Query Parameters – Key-value pairs appended to the URL.
• Request Body (Content) – The payload sent with POST/PUT/PATCH requests.
• Variable Substitutions – Placeholders like ${variable_name} that are dynamically replaced at runtime.

Each Outbound REST Message record can have one or more HTTP Methods (child records). Think of the parent record as the service definition and the HTTP Methods as the individual operations you can perform against that service.

---

How Outbound REST Messages Work – Step by Step

1. Define the REST Message
Navigate to System Web Services → Outbound → REST Message. Create a new record and provide:
- A descriptive Name
- The base Endpoint URL (e.g., https://api.example.com/v1)
- An Authentication profile (if needed)

2. Create HTTP Methods
Under the REST Message, create one or more HTTP Method records. Each method specifies:
- The HTTP method (GET, POST, PUT, DELETE, PATCH)
- A relative path appended to the base endpoint (e.g., /users/${user_id})
- HTTP Headers specific to this method
- HTTP Query Parameters
- A Content (request body) field where you can include variable substitutions

3. Use Variable Substitutions
Variables are defined using the syntax ${variable_name} in the endpoint, content body, or query parameters. At runtime, you replace them with actual values using:

request.setStringParameterNoEscape('variable_name', 'actual_value');

4. Invoke from a Script
You can call an Outbound REST Message from any server-side script (Business Rule, Script Include, Scheduled Job, Flow Designer, etc.) using the RESTMessageV2 API:

var sm = new sn_ws.RESTMessageV2('REST Message Name', 'HTTP Method Name');
sm.setStringParameterNoEscape('user_id', '12345');
var response = sm.execute();
var responseBody = response.getBody();
var httpStatus = response.getStatusCode();

5. Process the Response
The RESTResponseV2 object gives you access to:
- getBody() – The response body as a string
- getStatusCode() – The HTTP status code (200, 404, 500, etc.)
- getHeaders() – Response headers
- getErrorMessage() – Any error message
- haveError() – Boolean indicating if an error occurred

6. Test Within the Platform
ServiceNow provides a Test link on the HTTP Method form. You can supply variable values and execute a test call directly from the platform, viewing the request and response details. This is extremely useful during development.

---

Key Concepts to Understand

Authentication Profiles
- Basic Auth: Username and password sent with each request (Base64 encoded).
- OAuth 2.0: Uses an OAuth profile to obtain and manage tokens. ServiceNow handles token refresh automatically.
- Mutual Authentication: Both client (ServiceNow) and server present certificates.
- Authentication can be set at the REST Message level or overridden at the HTTP Method level.

Mid Server
If the external API is behind a firewall or on an internal network, you can route the outbound call through a MID Server by setting:
sm.setMIDServer('mid_server_name');

ECC Queue
When using a MID Server, requests go through the ECC Queue. Calls can be executed asynchronously using:
sm.executeAsync();
This returns a RESTResponseV2 object that you can check later using waitForResponse(timeout).

Connection and Read Timeout
You can configure timeouts to prevent long-running calls:
sm.setHttpTimeout(10000); // timeout in milliseconds

Protocol Profiles and Certificates
For HTTPS connections requiring specific certificates, ServiceNow supports importing certificates and associating them with protocol profiles.

---

Outbound REST Message vs. RESTMessageV2 Scripted Approach

You have two approaches for making outbound REST calls:

1. Defined REST Message + RESTMessageV2 – You define the message/methods in the platform UI and reference them by name in script. This is the recommended approach because it separates configuration from code, is easier to maintain, and is reusable.

2. Purely Scripted (no predefined message) – You can use RESTMessageV2 without referencing a predefined message and set the endpoint, headers, and body entirely in script:

var sm = new sn_ws.RESTMessageV2();
sm.setHttpMethod('GET');
sm.setEndpoint('https://api.example.com/v1/users');
sm.setRequestHeader('Accept', 'application/json');
var response = sm.execute();

The exam may test whether you understand when to use each approach.

---

Common Exam Scenarios

• A question may describe a requirement to send incident data to an external ticketing system. The correct answer involves creating an Outbound REST Message with a POST method and invoking it via a Business Rule or Flow Designer action.

• Questions about variable substitution: Know that ${variable} syntax is used and that setStringParameterNoEscape() replaces them at runtime.

• Questions about error handling: You should check getStatusCode() and handle non-2xx responses appropriately.

• Questions about asynchronous execution: Know that executeAsync() is used with MID Servers or when you do not want to block script execution.

---

Exam Tips: Answering Questions on Outbound REST Messages

1. Know the navigation path: System Web Services → Outbound → REST Message. This is frequently tested.

2. Understand the parent-child relationship: A REST Message is the parent; HTTP Methods are children. Each HTTP Method defines a specific operation (GET, POST, etc.).

3. Remember the API class: The scripting API is sn_ws.RESTMessageV2 (not RESTMessage, which is deprecated). If you see RESTMessageV2 vs. RESTMessage in answer choices, always pick RESTMessageV2.

4. Variable substitution syntax: Always ${variable_name}. Replaced at runtime using setStringParameterNoEscape() or setStringParameter(). The NoEscape version does not XML-escape the value — use it for JSON payloads.

5. Authentication: If a question mentions OAuth, know that you need to create an OAuth Entity Profile (via Application Registry or OAuth provider) and associate it with the REST Message. For basic auth, credentials are stored in the REST Message record or a credential alias.

6. Testing: ServiceNow allows you to test HTTP Methods directly from the form. If a question asks about the best way to test an outbound integration during development, the built-in Test feature is the answer.

7. MID Server: If the question mentions calling an API inside a corporate network (not internet-accessible), the answer involves routing through a MID Server.

8. Response handling: Know the key methods — getBody(), getStatusCode(), getHeaders(), haveError(). If a question asks how to retrieve the response payload, the answer is getBody().

9. Content-Type header: For POST/PUT requests sending JSON, set the Content-Type header to application/json. This is a common detail in exam questions.

10. Differentiate Outbound from Inbound: Outbound REST Messages are for ServiceNow calling out to external systems. Scripted REST APIs and standard REST API are for external systems calling into ServiceNow. Do not confuse the two.

11. Flow Designer Integration: In newer exam versions, know that you can use the REST step in Flow Designer to invoke outbound REST calls without writing script. However, under the hood, it still uses the same REST Message framework.

12. Elimination strategy: If you see answer choices mentioning Import Sets, Transform Maps, or Web Service Import Sets, those relate to inbound data loading, not outbound calls. Eliminate them quickly for outbound integration questions.

13. Error handling best practice: Always wrap outbound calls in try-catch blocks and check the HTTP status code. If an exam question asks about best practices for outbound integrations, error handling and logging are key components of the correct answer.

14. Credential management: ServiceNow recommends using Connection and Credential Aliases (part of Integration Hub) for managing credentials rather than hardcoding them. This may appear in questions about security best practices.

---

Summary

Outbound REST Messages are a foundational integration feature in ServiceNow. For the CAD exam, focus on understanding the configuration structure (REST Message → HTTP Methods), the RESTMessageV2 scripting API, variable substitution, authentication options, and the difference between outbound and inbound integrations. Practice creating and testing REST Messages in a Personal Developer Instance (PDI) to build hands-on familiarity that will help you confidently answer exam questions.