Create an incident using display values

This example demonstrates how to create a new incident record by supplying human-readable labels (display values) for reference fields instead of their underlying sys_id values.

Normally, ServiceNow requires reference fields (such as caller_id or assignment_group) to be populated using the target record's sys_id. In this example, label-to-ID resolution is explicitly enabled using AllowDisplayValueAsInput='true', allowing display values to be passed instead.

This approach is useful for ad-hoc operations, demos, or interactive usage. For automated or high-volume integrations, using sys_id values is strongly recommended.

Standard SQL query example

This is the base query accepted by the connector. To execute it in SQL Server, you have to pass it to the Data Gateway via a Linked Server. See how to accomplish this using the examples below.

-- Create a new Incident using DISPLAY VALUES (labels) for reference fields
-- Instead of passing sys_id values, this example uses human-readable labels.
-- This works ONLY because AllowDisplayValueAsInput='true' is specified.

INSERT INTO incident
(
	short_description,
	incident_state,
	severity,
	category,
	caller_id,           -- reference to sys_user
	assignment_group     -- reference to sys_user_group
)
VALUES
(
	'Email service is intermittently failing',
	2,                   -- In Progress
	1,                   -- High severity
	'software',
	'John Doe',          -- LABEL (user display name), not sys_id
	'Network'            -- LABEL (group name), not sys_id
)
WITH(AllowDisplayValueAsInput='true')

Using OPENQUERY in SQL Server

SELECT * FROM OPENQUERY([LS_TO_SERVICENOW_IN_GATEWAY], '-- Create a new Incident using DISPLAY VALUES (labels) for reference fields
-- Instead of passing sys_id values, this example uses human-readable labels.
-- This works ONLY because AllowDisplayValueAsInput=''true'' is specified.

INSERT INTO incident
(
	short_description,
	incident_state,
	severity,
	category,
	caller_id,           -- reference to sys_user
	assignment_group     -- reference to sys_user_group
)
VALUES
(
	''Email service is intermittently failing'',
	2,                   -- In Progress
	1,                   -- High severity
	''software'',
	''John Doe'',          -- LABEL (user display name), not sys_id
	''Network''            -- LABEL (group name), not sys_id
)
WITH(AllowDisplayValueAsInput=''true'')')

Using EXEC in SQL Server (handling larger SQL text)

The major drawback of OPENQUERY is its inability to incorporate variables within SQL statements. This often leads to the use of cumbersome dynamic SQL (with numerous ticks and escape characters).

Fortunately, starting with SQL 2005 and onwards, you can utilize the EXEC (your_sql) AT [LS_TO_SERVICENOW_IN_GATEWAY] syntax.

DECLARE @MyQuery NVARCHAR(MAX) = '-- Create a new Incident using DISPLAY VALUES (labels) for reference fields
-- Instead of passing sys_id values, this example uses human-readable labels.
-- This works ONLY because AllowDisplayValueAsInput=''true'' is specified.

INSERT INTO incident
(
	short_description,
	incident_state,
	severity,
	category,
	caller_id,           -- reference to sys_user
	assignment_group     -- reference to sys_user_group
)
VALUES
(
	''Email service is intermittently failing'',
	2,                   -- In Progress
	1,                   -- High severity
	''software'',
	''John Doe'',          -- LABEL (user display name), not sys_id
	''Network''            -- LABEL (group name), not sys_id
)
WITH(AllowDisplayValueAsInput=''true'')'
EXEC (@MyQuery) AT [LS_TO_SERVICENOW_IN_GATEWAY]