XML APIs

  • Release version: Xanadu
  • 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 you to process and encrypt XML payloads by iterating through XML elements and mapping them to database fields. These APIs are accessed by callinggetAsXmlContent()on a request object or a ParameterValue property, returning an iterableXMLContentobject. This facilitates encryption rule creation that dynamically handles XML data during ingestion.

    Show full answer Show less

    Key Features

    • Iteration over XML elements: Use getIterator() with optional XPath expressions to traverse specific XML nodes.
    • Element inspection and mapping: Each XMLElement exposes methods like getName() and valueFor(tableName, fieldName) to determine element identity and map values to ServiceNow table fields.
    • Dynamic encryption decision: The proxy checks if mapped fields require encryption based on existing encryption configurations and applies encryption only when needed.
    • Support for encoded queries: Elements with a filter="true" attribute are treated as encoded queries and encrypted accordingly via encodedQueryFor(tableName).

    Practical Usage Examples

    • Known table-field mapping: Iterate over specific XML tags (e.g., description) and encrypt their values into known table fields (e.g., incident.shortdescription).
    • Unknown table-field mapping: Iterate over child elements of XML records when field names are dynamic and map values accordingly, with conditional encryption based on table and field names.
    • Handling encoded queries: Detect elements flagged as encoded queries and encrypt the query strings, while encrypting other fields as configured.

    Key Outcomes

    By leveraging XML APIs, ServiceNow customers can create flexible encryption rules that securely process incoming XML data payloads, ensuring sensitive information is encrypted before insertion into the platform's tables. The APIs support both static and dynamic XML structures and handle complex cases like encoded queries, enhancing data security in integrations and import scenarios.

    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.