Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform capabilities
Table of Contents
Choose your release version
    Home Orlando Now Platform Capabilities Now Platform capabilities Edge Encryption Edge Encryption configuration Define a custom encryption rule Encryption rule objects and APIs XML APIs

    XML APIs

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

    XML APIs

    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.

    • XMLContent

      A global object that provides methods to iterate over the XML content.

    • XMLElementIterator

      Provides methods for iterating over XML elements.

    • XMLElement

      Provides methods for iterating through XML elements and mapping values to fields in a table.

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      XML APIs

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

      XML APIs

      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.

      • XMLContent

        A global object that provides methods to iterate over the XML content.

      • XMLElementIterator

        Provides methods for iterating over XML elements.

      • XMLElement

        Provides methods for iterating through XML elements and mapping values to fields in a table.

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login