---
sourceDocument: Australia Platform security
sourceDocumentLink: https://www.servicenow.com/docs/r/australia/platform-security
Release :
- australia
ft:locale :
- en-US
ft:publication_title :
- Australia Platform security
ft:clusterId :
- psec
bundleId :
- psec
workflow :
- Platform
---
# XML APIs
# XML APIs {#ariaid-title1}
Release version: Australia
Updated November 5, 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 process and encrypt XML payloads by interacting with XML elements through a structured iteration approach.
These APIs are utilized by callinggetAsXmlContent()on the request object or a ParameterValue property, which returns an iterable XMLContent object.
This facilitates encryption rules that map XML data to specific fields in ServiceNow tables, ensuring sensitive data is encrypted before insertion or processing on the instance.
Show full answer Show less
## Key Features
* **XMLContent Object:** Provides methods such as `getIterator()` or `getIterator(String xPath)` to iterate over XML elements efficiently.
* **XMLElementIterator:** Allows traversal of XML elements with `hasNext()` and `next()` methods, ensuring controlled iteration.
* **XMLElement:** Offers the `valueFor(String tableName, String fieldName)` method to map XML element values to corresponding table fields, enabling the proxy to determine if encryption is required based on configured encryption rules.
* **Dynamic Field and Table Mapping:** Supports scenarios where XML structure varies or is unknown, dynamically mapping fields based on table names derived from request parameters.
* **Encoded Query Encryption:** Handles encryption of encoded queries within XML elements when a `filter="true"` attribute is present, using the `encodedQueryFor(tableName)` method.
## Practical Application
ServiceNow customers can define encryption rules in JavaScript that iterate over XML payloads, selectively encrypting data before it is processed on the instance. Common use cases include:
* **Mapping known XML tags to specific table fields:** For example, encrypting the `description` tag values and inserting them into the `incident.shortdescription` field.
* **Handling unknown or dynamic XML structures:** Iterating over all child elements within a record and encrypting fields based on runtime table and field names.
* **Encrypting encoded queries:** Detecting XML elements with a filter attribute and encrypting their contents accordingly.
## Key Outcomes
* Ensures sensitive XML data is encrypted consistently according to ServiceNow encryption configurations.
* Provides a flexible and programmable approach to handle diverse XML payloads securely.
* Integrates encryption seamlessly into data ingestion workflows, protecting data at the proxy level before it reaches the instance.
* Allows customers to customize encryption logic based on XML structure and business requirements.
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.
{#xml-overview__ol_jwb_1nw_2z}
## Mapping to a known table-field on the instance {#xml-overview__section_kmb_jrd_yz}
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.
'Test Record 1'
'Test Record 1 Description'
critical
'Test Record 2'
'Test Record 2 Description'
security
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 {#xml-overview__xml-dynamic}
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 {#xml-overview__section_glc_rrd_yz}
In this example, all tags have the filter attribute, which
indicates whether the tag contains an encoded query.
'Test Record 1'
'Test Record 1 Description'
category=1^name=edge
'Test Record 2'
'Test Record 2 Description'
category=2^severity=3
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.
* **[XMLContent](https://www.servicenow.com/docs/s8tOp7mwbCuYmUJhiCU_7A#c_XMLContentAPI)**
A global object that provides methods to iterate over the XML content.
* **[XMLElementIterator](https://www.servicenow.com/docs/0f2gT0TLusqA9IiqWtTbNA#c_XMLElementIteratorAPI)**
Provides methods for iterating over XML elements.
* **[XMLElement](https://www.servicenow.com/docs/fdfRjDhXjD644Q3X4~Bzfw#c_XMLElementAPI)**
Provides methods for iterating through XML elements and mapping values to fields in a table.