XML APIs

  • Release version: Yokohama
  • Updated June 16, 2026
  • 4 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 XML APIs

    XML APIs in ServiceNow enable customers to handle XML content securely by iterating through XML elements and applying encryption rules dynamically. These APIs are accessed via thegetAsXmlContent()method on request objects or ParameterValue properties, returning an iterable XMLContent object. This functionality is essential when processing XML payloads to map data fields to ServiceNow tables and apply encryption based on configured policies.

    Show full answer Show less

    Key Features

    • XMLContent Object: Provides methods to obtain iterators (getIterator() or getIterator(String xPath)) for navigating XML elements efficiently.
    • XMLElementIterator: Enables iteration over XML elements using hasNext() and next() methods to traverse elements safely.
    • XMLElement: Offers the valueFor(String tableName, String fieldName) method to map XML element values to specific table fields and trigger encryption checks by the proxy server.
    • Dynamic Field Mapping: Supports encryption rules that adapt to unknown or dynamic table fields by iterating over child elements and determining encryption requirements at runtime.
    • Encoded Query Handling: Allows encryption of encoded queries within XML elements by checking a filter attribute and calling encodedQueryFor(tableName) when appropriate.

    Practical Application for ServiceNow Customers

    Using XML APIs, customers can:

    • Process incoming XML payloads to insert or update records in ServiceNow tables, such as incidents, with encrypted sensitive fields like shortdescription.
    • Create flexible encryption rules that work with known or unknown XML structures by dynamically mapping element names to table fields and invoking encryption only when configured.
    • Handle complex XML payloads containing encoded queries, ensuring these are encrypted properly to maintain data security.
    • Leverage built-in iterator methods to safely traverse XML content without errors, ensuring robust and maintainable encryption logic.

    Expected Outcomes

    • Enhanced data security through automatic detection and encryption of sensitive fields in XML payloads before storing them in the ServiceNow instance.
    • Greater flexibility in handling diverse XML data formats, reducing manual configuration and enabling dynamic encryption policies.
    • Improved integration security when ingesting data via XML, ensuring compliance with encryption requirements transparently.

    XML APIs can be used after calling getAsXmlContent() on either the request object or a ParameterValue property.

    When using XML APIs to write your encryption rule, you can follow a general format:
    1. Call getAsXmlContent() on the request object or ParameterValue property. This returns an iterable object of the XMLContent underlying class.
    2. Call getIterator() or getIterator(String xPath) on the XMLContent object. This returns an XMLElementIterator object that can be used to iterate over XML elements.
    3. Call the hasNext() method on the XMLElementIterator object to determine whether another element is available.
    4. Call next() on the XMLElementIterator object to return the next XML element. You cannot call next() without first calling hasNext().
    5. Call valueFor(String tableName, String fieldName) on the XML element. This method tells the proxy that the value for this element maps to the specified field in the specified table. The proxy then checks if the field must be encrypted.
      Note:
      To determine if you want to call valueFor(String tableName, String fieldName) on an XML element, you can use the getName() method to return the name of the element.

    Mapping to a known table-field on the instance

    In this example, the XML payload will be processed on the instance to insert records in the incident table. The description field will populate short_description on the incident.

    <data>
    <record>
        <name>'Test Record 1'</name>
        <description>'Test Record 1 Description'</description>
        <tag>critical</tag>
    </record>
    <record>
        <name>'Test Record 2'</name>
        <description>'Test Record 2 Description'</description>
        <tag>security</tag>
    </record>
</data>

    The following encryption rule action can apply:

    function sampleXmlAction1() {
    var xmlContent = request.getAsXmlContent();
    // This loop iterates over all description tags that match the given path
    var xmlElementIterator = xmlContent.getIterator('data/record/description');    
    while (xmlElementIterator.hasNext()) {
        var xmlElement = xmlElementIterator.next();
        xmlElement.valueFor('incident', 'short_decription');
    }
}

    This action iterates through the description tags and asks the proxy server to encrypt the values and insert them into incident.short_description on the instance.

    Note:
    This rule finds all description tags within all record tags in the XML payload. If there is only one occurrence of a tag to encrypt, the rule still uses the xPath and iterator structure. However, it iterates only once in the loop.

    Mapping to an unknown table-field on the instance

    In this example, the rule iterates over the record tags, but does not know what tags to expect within the record tag. The only known is that the tags within the record tags match the names of the columns specified in the table URL parameter.

    The rule also specifies that, if the table is incident, then the data in the description tag should be encrypted and stored in the short_description field on the instance.

    function sampleXmlAction2() {
    var xmlContent = request.getAsXmlContent();
    var tableName = request.urlParam.table;
    // This first iterator will iterate over all record elements
    var xmlElementIterator = xmlContent.getIterator('data/record');
    while (xmlElementIterator.hasNext()) {
        encryptFieldsInRecord(xmlElementIterator.next());
    }
}
function encryptFieldsInRecord(xmlElement) {
    //Then, iterate over all tags representing fields in the table
    var fieldIterator = xmlElement.getIteratorOverAllChildren();
    while (fieldIterator.hasNext()) {
        var field = fieldIterator.next();
        var fieldName = childElement.getName();
        //if table is incident, then description is encrypted for the short_description field
        if (tableName == 'incident' && fieldName == 'description') {
            field.valueFor(tableName, 'short_description');
        } else {
            //if table is not incident, ask the proxy to check if the given field is encrypted for the given table
            field.valueFor(tableName, fieldName);
        }
    }
}

    In the encryptFieldsInRecord() function, the valueFor() method is called on a table and a field that are dynamically assigned based on the request. Even though the table and field names can change, the rule asks the proxy to check whether the field in the table must be encrypted based on the encryption configurations defined.

    If the field is not configured for encryption, or if the tag does not match a field in the table, the proxy skips that tag. If the tag matches a field marked for encryption, then the Edge Encryption proxy server encrypts the value.

    Using an encoded query

    In this example, all tags have the filter attribute, which indicates whether the tag contains an encoded query.

    <data>
    <record>
        <name filter="false">'Test Record 1'</name>
        <description filter="false">'Test Record 1 Description'</description>
        <query filter="true">category=1^name=edge</query>
    </record>
    <record>
        <name filter="false">'Test Record 2'</name>
        <description filter="false">'Test Record 2 Description'</description>
        <query filter="true">category=2^severity=3</query>
   </record>
</data>

    The following encryption rule action can apply:

    function sampleXmlAction3() {
   var xmlContent = request.getAsXmlContent();
   var tableName = request.urlParam.table;
   // This first iterator will iterate over all record elements
   var xmlElementIterator = xmlContent.getIterator('data/record');
   while (xmlElementIterator.hasNext()) {
       encryptFieldsInRecord(xmlElementIterator.next());
   }
}
function encryptFieldsInRecord(xmlElement) {
   //this time we want to iterate over all tags representing fields in the table
   var fieldIterator = xmlElement.getIteratorOverAllChildren();
   while (fieldIterator.hasNext()) {
       var field = fieldIterator.next();
       var fieldname = childElement.getName();
       //let's look at the filter attribute, if true, then encrypt as encoded query
       if (field.getAttributeValue('filter') == 'true') {
           field.encodedQueryFor(tableName);
       } else {
           //if it is false then check if the field should be encrypted
           field.valueFor(tableName, fieldName);
       }
   }
}

    If the filter attribute value is true, the rule asks the proxy server to encrypt the values in the encoded query. If false, the rule asks the proxy to check whether the field should be encrypted.