Direct web services

  • Release version: Yokohama
  • Updated January 30, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Direct web services

    Direct web services in ServiceNow provide SOAP-based access to any table in the system, granted the appropriate access controls are configured. These services use document style literal XML SOAP messages and expose WSDL descriptions at a predictable URL pattern for each table, allowing easy discovery and consumption of the web service.

    Show full answer Show less

    Key Features

    • WSDL Access: Retrieve WSDL and XML schema by appending ?WSDL to the table URL (e.g., /incident.do?WSDL).
    • Extended Query Parameters: Modify SOAP query results with parameters such as encodedquery (filtered queries), orderby (sorting), excludecolumns (omit fields), limit (record limits), and paging controls (firstrow, lastrow). These enable precise control over data retrieved.
    • Namespace Management: Each table’s web service WSDL uses a unique targetNamespace by default, ensuring clients can distinguish requests across multiple tables. This is controlled by the glide.wsdl.definition.useuniquenamespace property.
    • Schema Compatibility: The glide.wsdl.schema.UnqualifiedElementFormDefault property addresses compatibility with SOAP clients by toggling element qualification in the WSDL schema, improving parsing in clients like .NET or Axis2.
    • Service Name Uniqueness: By default, service names are unique per table, but administrators can allow duplicate service names by setting the glide.wsdl.uniqueservicename property to false.
    • Form Views for Response Control: Use form views to limit or extend the fields returned in SOAP queries, including deep referenced fields, providing flexible control of the response data.
    • Reference Field Handling: SOAP queries return reference fields as sysids by default; you can configure responses to return display values for easier interpretation.
    • Clearing Field Values: Pass empty SOAP parameters to clear specific field values in target records.
    • Journal and Choice Fields: Retrieve journal entries by querying the sysjournalfield table separately. For choice fields, use the choice’s value (not label) when retrieving or setting data.
    • Session Persistence: Reuse a single HTTP session across multiple SOAP calls to improve performance in bulk operations.

    Practical Application for ServiceNow Customers

    Direct web services enable ServiceNow customers to integrate and interact programmatically with any table data using SOAP APIs with fine-grained filtering, sorting, and field selection. The use of unique namespaces and configurable schema settings ensures compatibility and clarity when consuming multiple table services simultaneously. Extended query parameters offer advanced querying capabilities, making it easier to retrieve relevant data efficiently. Additionally, handling of reference, journal, and choice fields is streamlined for straightforward data manipulation. Session persistence support enhances performance for integrations involving multiple SOAP calls. Overall, this functionality empowers customers to build robust, scalable integrations and automate data exchange with ServiceNow tables securely and flexibly.

    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

    Extended query parameters enable you to filter and modify the return results of a SOAP query when using the get, getKeys, and getRecords functions.
    Note:
    Extended query element names are preceded by two underscore characters.
    Table 1. Available 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 System Properties > Web Services.

    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.