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

    Define a custom encryption rule

    • 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

    Define a custom encryption rule

    It may be necessary to identify and encrypt sensitive information in HTTP requests on the way to your instance. You can write encryption rules to identify, interpret, and encrypt data in such requests, mapping fields in the request to table-field names on your instance.

    What is an encryption rule

    Encryption rules are scripts executed on the Edge Encryption proxy server to map fields in a request to fields in a table on your ServiceNow instance. An encryption rule tells the Edge Encryption proxy server how to encrypt data in custom payloads.
    Note: Encryption rules only support ECMAScript 3 and below.

    When to use custom rules

    A set of encryption rules is included as part of the Edge Encryption plugin. These rules handle core platform use cases such as editing a field from the list edit form, updating a record from the record form, managing direct web services, and processing data from the REST API. Applications created using standard forms and lists should work without custom encryption rules.

    If you develop scripted processors, scripted web services, scripted REST APIs, UIs, or Ajax scripts that contain data that should be encrypted, you must write encryption rules to find and map the data to Glide table-field names.

    Format of an encryption rule

    Rules include three parts:
    • Condition: Identifies the type of request.
    • Action: Maps fields in the request to fields in a table, encrypting values that map to fields with encryption configurations defined.
    • Order: Priority of the rule. The lowest priority rule with a satisfied condition is the only rule that runs. Like business rules, rules run from lowest to highest.

    Except for attachment requests, when an HTTP request hits the Edge Encryption proxy server, the Edge Encryption proxy server evaluates all encryption rule conditions in priority order until either all conditions return false, or one condition returns true. When a condition returns true, the action is executed on the request and the result is forwarded to the instance. No other conditions are evaluated. As a result, encryption rule conditions should be as specific as possible. A generic rule might evaluate as true for a request meant to be processed by another rule, causing the request to be processed by the wrong action. If a generic condition is unavoidable, the rule should be marked with a high-order value so that more specific rules are evaluated first.

    Guidelines for creating encryption rules

    Creating efficient, optimized encryption rules can reduce processing time for script validation.

    Overall guideline: When rules get very long, do your best to minimize the number of blocks and break the rules apart whenever possible. Ideally, custom rules should apply to specific use cases, rather than encompassing several cases, with ifs or switch statements in the action script.

    1. Split rules whenever possible. For example,
      • Create different rules for different tables and ensure that each rule runs only on its respective table.
      • Create different rules for each record producer you are targeting, or at least for each subset of record producers. Instead of one rule targeting dozens of sys_ids, you could create several different rules targeting smaller subsets of record producers, or even create one rule per sys_id.
        Note: Creating multiple rules requires more maintenance. The trade-off is that multiple, simpler rules can be validated more efficiently than longer, more complex rules.
    2. Minimize the number of blocks. Because the processing engine scans each block while evaluating scripts, a large number of blocks causes delays in validation. For example,
      • Replace all if blocks with an array lookup, and replace all blocks in the array lookup with just one if block.
      • Combine if blocks whenever it is possible to group them.

    Encryption rule APIs

    Encryption rules are written in JavaScript and utilize Edge Encryption APIs to locate and encrypt sensitive information in the body of a request. The API uses expressions similar to xPath to navigate through both JSON and XML content.

    Edge Encryption APIs process the request off the stream as it is being written to the output stream. Stream parsing allows encryption rules to be network performant. However, fetching and parsing content from the body multiple times could lead to unexpected results. To account for this, requests should be processed by the action in a single pass.

    When creating encryption rules, you cannot use Glide APIs, script includes, business rules, or any global parameters such as current. Because the rules are created for HTTP objects, a global request object is available.

    When creating encryption rules, you cannot use APIs from the white list manager or scoped applications.

    Error handling

    If an encryption rule condition or action throws an exception, check the proxy log for troubleshooting information.

    • Inspect the client request

      Before creating a custom encryption rule, you must determine the format of the client request entering the Edge Encryption proxy server.

    • Create an encryption rule

      Encryption rules are used by the proxy to find content in HTTP requests that should be encrypted.

    • Encryption rule conditions

      Encryption rule conditions determine if the rule should be executed.

    • Encryption rule actions

      An encryption rule maps fields in a client request to fields in a table on your instance and identifies fields marked for encryption.

    • Encryption rule objects and APIs

      Use encryption rule APIs to parse and encrypt values in requests moving through the Edge Encryption proxy server to the instance.

    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

      Define a custom encryption rule

      • 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

      Define a custom encryption rule

      It may be necessary to identify and encrypt sensitive information in HTTP requests on the way to your instance. You can write encryption rules to identify, interpret, and encrypt data in such requests, mapping fields in the request to table-field names on your instance.

      What is an encryption rule

      Encryption rules are scripts executed on the Edge Encryption proxy server to map fields in a request to fields in a table on your ServiceNow instance. An encryption rule tells the Edge Encryption proxy server how to encrypt data in custom payloads.
      Note: Encryption rules only support ECMAScript 3 and below.

      When to use custom rules

      A set of encryption rules is included as part of the Edge Encryption plugin. These rules handle core platform use cases such as editing a field from the list edit form, updating a record from the record form, managing direct web services, and processing data from the REST API. Applications created using standard forms and lists should work without custom encryption rules.

      If you develop scripted processors, scripted web services, scripted REST APIs, UIs, or Ajax scripts that contain data that should be encrypted, you must write encryption rules to find and map the data to Glide table-field names.

      Format of an encryption rule

      Rules include three parts:
      • Condition: Identifies the type of request.
      • Action: Maps fields in the request to fields in a table, encrypting values that map to fields with encryption configurations defined.
      • Order: Priority of the rule. The lowest priority rule with a satisfied condition is the only rule that runs. Like business rules, rules run from lowest to highest.

      Except for attachment requests, when an HTTP request hits the Edge Encryption proxy server, the Edge Encryption proxy server evaluates all encryption rule conditions in priority order until either all conditions return false, or one condition returns true. When a condition returns true, the action is executed on the request and the result is forwarded to the instance. No other conditions are evaluated. As a result, encryption rule conditions should be as specific as possible. A generic rule might evaluate as true for a request meant to be processed by another rule, causing the request to be processed by the wrong action. If a generic condition is unavoidable, the rule should be marked with a high-order value so that more specific rules are evaluated first.

      Guidelines for creating encryption rules

      Creating efficient, optimized encryption rules can reduce processing time for script validation.

      Overall guideline: When rules get very long, do your best to minimize the number of blocks and break the rules apart whenever possible. Ideally, custom rules should apply to specific use cases, rather than encompassing several cases, with ifs or switch statements in the action script.

      1. Split rules whenever possible. For example,
        • Create different rules for different tables and ensure that each rule runs only on its respective table.
        • Create different rules for each record producer you are targeting, or at least for each subset of record producers. Instead of one rule targeting dozens of sys_ids, you could create several different rules targeting smaller subsets of record producers, or even create one rule per sys_id.
          Note: Creating multiple rules requires more maintenance. The trade-off is that multiple, simpler rules can be validated more efficiently than longer, more complex rules.
      2. Minimize the number of blocks. Because the processing engine scans each block while evaluating scripts, a large number of blocks causes delays in validation. For example,
        • Replace all if blocks with an array lookup, and replace all blocks in the array lookup with just one if block.
        • Combine if blocks whenever it is possible to group them.

      Encryption rule APIs

      Encryption rules are written in JavaScript and utilize Edge Encryption APIs to locate and encrypt sensitive information in the body of a request. The API uses expressions similar to xPath to navigate through both JSON and XML content.

      Edge Encryption APIs process the request off the stream as it is being written to the output stream. Stream parsing allows encryption rules to be network performant. However, fetching and parsing content from the body multiple times could lead to unexpected results. To account for this, requests should be processed by the action in a single pass.

      When creating encryption rules, you cannot use Glide APIs, script includes, business rules, or any global parameters such as current. Because the rules are created for HTTP objects, a global request object is available.

      When creating encryption rules, you cannot use APIs from the white list manager or scoped applications.

      Error handling

      If an encryption rule condition or action throws an exception, check the proxy log for troubleshooting information.

      • Inspect the client request

        Before creating a custom encryption rule, you must determine the format of the client request entering the Edge Encryption proxy server.

      • Create an encryption rule

        Encryption rules are used by the proxy to find content in HTTP requests that should be encrypted.

      • Encryption rule conditions

        Encryption rule conditions determine if the rule should be executed.

      • Encryption rule actions

        An encryption rule maps fields in a client request to fields in a table on your instance and identifies fields marked for encryption.

      • Encryption rule objects and APIs

        Use encryption rule APIs to parse and encrypt values in requests moving through the Edge Encryption proxy server to the instance.

      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