Working with External Data

Outbound REST integrations call external APIs FROM ServiceNow. They use REST Message records to define the endpoint, authentication, and request format.

REST Message Configuration

• REST Message — Defines the base endpoint URL and authentication method.
• HTTP Method — GET, POST, PUT, PATCH, DELETE (configured per method).
• Authentication — Basic Auth, OAuth 2.0, Mutual Authentication, or No Auth.
• Request Headers — Content-Type, Accept, custom headers.
• Request Body — JSON/XML payload (for POST/PUT). Supports variable substitution.
• Variable Substitution — Use ${variable_name} in URL and body. Replaced at runtime.

Calling REST Messages from Script

• var sm = new sn_ws.RESTMessageV2('REST_Message_Name', 'HTTP_Method_Name');
• sm.setStringParameterNoEscape('variable', value); — Set URL/body variables.
• sm.setRequestBody(JSON.stringify(payload)); — Set custom body.
• var response = sm.execute(); — Execute the call.
• response.getStatusCode(); — HTTP status (200, 404, etc.).
• response.getBody(); — Response body as string.
• JSON.parse(response.getBody()); — Parse JSON response.

Inbound REST allows external systems to call ServiceNow. This includes the standard Table API and custom Scripted REST APIs.

Table API

• URL: /api/now/table/{table_name}
• GET — Read records (supports query parameters for filtering).
• POST — Create a new record (JSON body with field values).
• PUT — Replace a record entirely.
• PATCH — Partial update (only specified fields).
• DELETE — Delete a record by sys_id.
• Controlled by ACLs — the authenticated user must have appropriate roles.

Scripted REST APIs

• Custom endpoints with your own URL structure.
• Define resources (URL paths) and HTTP methods.
• Full control over request parsing and response formatting.
• Access request data: request.body.data, request.queryParams, request.pathParams.
• Set response: response.setStatus(200), response.setBody({...}).
• Use for complex integrations where Table API is insufficient.

Developers use Import Sets for data migration and integration. Beyond the basic import/transform process, developers write Transform Scripts to handle complex data transformations.

Transform Scripts for Developers

• onBefore(source, target, map, log) — Modify target values before insert/update. 'source' is the staging record, 'target' is the destination record.
• onAfter(source, target, map, log) — Post-processing after each row. Create related records, send notifications.
• Use ignore = true in onBefore to skip a row entirely.
• Use error = true in onBefore to mark a row as failed.
• source.u_field — Access staging table fields.
• target.field — Access/set destination table fields.

Integration Hub extends Flow Designer with pre-built connectors (Spokes) for external services like Slack, Jira, Azure, AWS, and more.

Key Concepts

• Spokes — Pre-built integration packages (e.g., Slack Spoke, Jira Spoke, Microsoft Teams Spoke).
• Actions — Individual operations within a spoke (e.g., 'Send Slack Message', 'Create Jira Issue').
• Used within Flow Designer flows — drag and drop spoke actions into flows.
• Custom Spokes — Developers can build custom spokes for internal or marketplace distribution.
• Credential Aliases — Secure storage for API keys and credentials used by spokes.