Direct web services
Summarize
Summary of Direct web services
Direct web services in ServiceNow allow you to interact with any table in the system through SOAP-based document/literal XML messages, provided the correct access control lists are configured.
Each table exposes a WSDL description accessible via a URL pattern ending with
Show less
Extended Query Parameters
When using SOAP functions like get, getKeys, and getRecords, you can refine your queries with extended query parameters. These parameters, prefixed with double underscores, allow you to:
- Filter results using encoded queries (
encodedquery). - Sort results ascending or descending (
orderby,orderbydesc). - Exclude specific columns from the result set (
excludecolumns). - Limit the number of returned records (
limit). - Paginate results by specifying offset and range (
firstrow,lastrow). - Use a specific form view to expand or limit the fields returned, including referenced fields (
useview).
Namespace and Schema Configuration
ServiceNow uses a unique namespace per table by default (glide.wsdl.definition.useuniquenamespace property set to true). This ensures the WSDL targetNamespace is distinct for each table, preventing conflicts when consuming multiple tables' web services simultaneously.
The WSDL schema defaults to elementFormDefault="unqualified", which can cause compatibility issues with some client generators (e.g., .NET, Axis2). To address this, the property glide.wsdl.schema.UnqualifiedElementFormDefault can be set to false to improve parsing compatibility.
Administrators can also configure whether service names are unique by setting glide.wsdl.uniqueservicename to false, allowing duplicate service names if needed.
Practical Usage Notes
- You can limit or extend SOAP query responses by using form views to control which fields are returned.
- Reference fields return sysid values; to get display values, additional handling may be required.
- To clear a field value on the target instance, pass an empty value in the SOAP parameter.
- Journal entries require a secondary SOAP request against the
sysjournalfieldtable to retrieve their contents. - Choice fields must be handled by their stored value, not the label, when retrieving or setting via SOAP.
- HTTP sessions can be persisted across multiple SOAP calls to improve performance when many calls occur in a short timeframe.
SOAP API Functions
The direct web service SOAP API provides a set of globally defined functions to perform operations on targeted resources (tables). These functions facilitate standard data retrieval and manipulation using SOAP messaging.
A direct web service is available for any table in the system if the correct access control list is configured.
The supported format of the incoming message is document style literal XML SOAP documents (Document/Literal). To retrieve a direct web service WSDL description and XML schema, point to the relative URL <tablename>.do?WSDL. For example, to retrieve the WSDL for the Incident table on the online demo system, use the following URL: https://<instance name>.service-now.com/incident.do?WSDL.
Extended query parameters
| Parameter | Description | Example |
|---|---|---|
| __encoded_query | Specify an encoded query string to be used in filtering the returned results. The
encoded query string format is similar to the value that may be specified in a
sysparm_query URL parameter. See the encoded query building example in the
RSS feed generator examples. |
<__encoded_query>active=true^category='hardware'</__encoded_query> |
| __order_by | Instruct the returned results to be ordered by the specified field. | <__order_by>priority</__order_by> |
| __order_by_desc | Instruct the returned results to be ordered by the specified field, in descending order. | <__order_by_desc>opened_date</__order_by_desc> |
| __exclude_columns | Specify a list of comma delimited field names to exclude from the result set. | <__exclude_columns>sys_created_on,sys_created_by,caller_id,priority</__exclude_columns> |
| __limit | Limit the number of records that are returned. | <__limit>100</__limit> |
| __first_row | Instruct the results to be offset by this number of records from the beginning of the
set. When used with __last_row has the effect of querying for a window of
results. The results are inclusive of the first row number. |
<__first_row>250</__first_row> |
| __last_row | Instruct the results to be limited by this number of records from the beginning of the
set, or the __start_row value when specified. When used with
__first_row has the effect of querying for a window of results. The
results are less than the last row number, and does not include the last row. |
<__last_row>500</__last_row> |
| __use_view | Specify a Form view by name, to be used for limiting and expanding the results returned. When the form view contains deep referenced fields such as caller_id.email, this field will be returned in the result as well. | <__use_view>soap_view</__use_view> |
Direct web services namespace
Specifying a unique namespace for each table
The glide.wsdl.definition.use_unique_namespace property ensures that each table's direct web service WSDL has a unique targetNamespace attribute. This property is true by default, which requires a table's direct web service WSDL to use a targetNamespace value of http://www.service-now.com/<table name>. When false (or when the property is not present), all tables use the same targetNamespace value of http://www.service-now.com. Since all tables also share the same operation names, a web service client attempting to consume more than one ServiceNow web service would be unable to differentiate between requests between multiple tables. Using a unique targetNamespace value allows web service clients to distinguish requests between multiple tables.
For example, the direct web service WSDL for the incident table uses this targetNamepsace value:
<wsdl:definitions xmlns:soapenc= "http://schemas.xmlsoap.org/soap/encoding/"xmlns:wsdl = "http://schemas.xmlsoap.org/wsdl/"xmlns:http = "http://schemas.xmlsoap.org/wsdl/http/"xmlns:tns = "http://www.service-now.com/incident"xmlns:xsd = "http://www.w3.org/2001/XMLSchema"xmlns:mime = "http://schemas.xmlsoap.org/wsdl/mime/"xmlns:soap = "http://schemas.xmlsoap.org/wsdl/soap/"targetNamespace = "http://www.service-now.com/incident" ><wsdl:types><xsd:schema elementFormDefault = "unqualified"targetNamespace = "http://www.service-now.com/incident" >Setting namespace requirements
ServiceNow's WSDL schema by default declares an attribute of elementFormDefault="unqualified". This attribute indicates whether or not locally declared elements must be qualified by the targetNamepsace in an instance document. If the value of this attribute is unqualified, then locally declared elements should not be qualified by the targetNamepsace. If the value of this attribute is qualified, then locally declared elements must be qualified by the targetNamepsace.
However, this is incompatible with the way clients generated from WSDL (for example, .NET, Axis2, webMethods) process the embedded schema. It removes the schema namespace as a result, making the web service response unparseable.
To overcome this compatibility issue, a boolean property called glide.wsdl.schema.UnqualifiedElementFormDefault is introduced. This property has the value of true by default. Setting it to false enables clients generated from WSDL to parse the return value of the web service invocation. You can modify this property using the Web Services properties page at .
Allowing duplicate service names
By default, service names from dynamically generated WSDL are unique and have the following format:
ServiceNow_<table name>To allow duplicate service names, administrators can set the glide.wsdl.unique_service_name property to false. Create the property if it does not exist.