Guide

Rules

Suggest Edits

Each property configuration contains a set of rules that determine response actions to your site's traffic when specific conditions are met.

What you'll do

  1. Learn how to configure rules.
  2. Add rules to a property.
  3. Activate the property.

Configure rules

You shape your rules' settings through behaviors and criteria. Behaviors contain options that define the response actions to your site's requests, and criteria settings detail exactly what puts those actions in motion.

Rule formats

Rule formats are versioned sets of behaviors and criteria. Version numbers reflect a set's release date, and each dated version is a major version update. New or updated functionality in newer releases isn't backward compatible, so check your property's rule format version against the feature you want and update it as needed.

Along with the dated versions is version named latest. This one contains all the behaviors and criteria from the latest dated version and any of the iterative, or beta, changes prior to the next official release.

The schema documentation for behaviors and criteria detail the available options, accepted values, and any dependencies for the latest and latest dated versions.

Note: For information on earlier dated versions, see Deprecated rule formats.

Rules

Your configuration's rule tree contains a default rule, any of its behaviors, and child rules and their behaviors.

Default rule

The default rule is a rule tree's base rule. Behaviors you build out at this level apply to all requests for the property's hostnames until you add another rule that overrides those settings.

For example, this default rule has two behaviors, origin and cpCode. There are no other rules, so these two behaviors define response actions for all of the property's hostnames.

"rules": {
  "name": "default",
  "children": [],
  "behaviors": [
    {
      "name": "origin",
      "options": {
        "originType": "CUSTOMER",
        "hostname": "example-origin-behavior.com",
        "forwardHostHeader": "REQUEST_HOST_HEADER",
        "cacheKeyHostname": "ORIGIN_HOSTNAME",
        "compress": true,
        "tcipEnabled": false,
        "httpPort": 80
      }
    },
    {
      "name": "cpCode",
      "options": {
        "value": {
          "id": 12345,
          "name": "main site"
        }
      }
    }
  ]
}

Child rules

Nested within the default rule are child rules. These serve to expand your default rule with settings for particular conditions.

Each child rule and any of its nested children narrow the focus of behaviors and the criteria that trigger them.

Evaluation of rules runs top to bottom with the last matching rule's behavior determining the actual action taken on a request.

Build out your child rules within the default rule's children array. Here, an added child rule of Compress Text Content has a behavior of gzipResponse with an option and criterion.

"rules": {
  "name": "default",
  "children": [
    {
      "name": "Compress Text Content",
      "behaviors": [
        {
          "name": "gzipResponse",
          "options": { "behavior": "ALWAYS" }
        }
      ],
      "criteria": [
        {
          "name": "contentType",
          "options": {
            "matchOperator": "IS_ONE_OF",
            "matchWildcard": true,
            "matchCaseSensitive": false,
            "values": [
              "text/html*",
              "text/css*",
              "application/x-javascript*"
            ]
          }
        }
      ]
    }
  ],
  ...
}

Complete tree

The sample code presented so far works together to deliver a solution that uses an origin as the source of truth, its hostname to build out the keys for cached content, and directs HTTP requests for information through port 80.

The solution also collects all forwarded request metadata and compresses specific content types to reduce the amount of data sent in responses and increase display speed. 

"rules": {
  "name": "default",
  "options": {
      "is_secure": false
  },
  "behaviors": [
    {
      "name": "origin",
      "options": {
        "originType": "CUSTOMER", 
        "hostname": "my-behavior-example.com", 
        "forwardHostHeader": "REQUEST_HOST_HEADER", 
        "cacheKeyHostname": "ORIGIN_HOSTNAME", 
        "compress": true, 
        "enable_true_client_ip": false,
        "httpPort": 80 
      }
    },
    {
      "name": "cpCode", 
      "options": {
        "value": {
            "id": 12345, 
            "name": "main site"
        }
      }
    }
  ],
  "children": [
    {
      "name": "Compress Text Content",
      "behaviors": [
        {
          "name": "gzipResponse",
          "options": { "behavior": "ALWAYS" }
        }
      ],
      "criteria": [
        {
          "name": "contentType",
          "options": {
            "matchOperator": "IS_ONE_OF",
            "matchWildcard": true,
            "matchCaseSensitive": false,
            "values": [
              "text/html*",
              "text/css*",
              "application/x-javascript*"
            ]
          }
        }
      ]
    }
  ]
}

Update and manage rules

Whether you're making changes to your existing rule tree or creating rules for a new property, rule configuration is an update process.

You can make updates to your rules using a PS Object, a single JSON file containing all your rules, or multiple snippet files that separate your default rule from your child rules.

  1. Get a rule tree.

    • Set your rules to a variable to work with them as a PS Object.
    • Pass the -OutputToFile switch with or without -OutputFileName to get its tree in a single JSON file. The default file name is your property's name.
    • Use the -OutputSnippets switch with or without -OutputDirectory to get its tree as a set of snippets. The default directory location is your active directory.
    # PS Object
$PropertyRules = Get-PropertyRules -PropertyName MyProperty -PropertyVersion 4  

# Single file
Get-PropertyRules -PropertyName MyProperty -PropertyVersion latest -OutputToFile

# Snippets
Get-PropertyRules -PropertyName MyProperty -PropertyVersion latest -OutputSnippets

    # PS Object
accountId       : A-CCT1234
contractId:       C-0N7RAC7
groupId         : 12345
propertyId      : 12345
propertyName    : MyProperty
propertyVersion : 3
etag            : 1a2345bcd6e789012fg34h56i78901234j5678k9
rules           : @{name=default; children=System.Object[]; 
                  behaviors=System.Object[]; options=; variables=System.Object[]; 
                  comments=The Default Rule template contains all the necessary and 
                  recommended behaviors. Rules are evaluated from top to bottom and 
                  the last matching rule wins.}
warnings        : {}
ruleFormat      : latest
comments        : Property use-case testing

# Single file
Wrote version 3 of property MyProperty to MyProperty.json

# Snippets
Creating new property directory MyProperty
Wrote version 3 of property MyProperty to MyProperty

  2. Make rule changes.

    • PS Object. Use dot notation to make changes to values.

      $PropertyRules.rules.behaviors[0].options.hostname = "origin.example-update.com"

    • Single JSON file. Add your new items directly into the rules, children, or behaviors arrays or add new options to the default rule in its options object.

    • Snippets. Organize your rules directory and subdirectory based on the child rule and behavior names and add references to them in the main.json file.

      ./MyProperty
  ├── Augment insights
  │   ├── Geolocation.json
  │   ├── Log delivery.json
  │   ├── Traffic reporting.json
  │   └── mPulse RUM.json
  ├── Augment insights.json
  ├── main.json
  └── pmVariables.json

      "children": [
  "#include:Augment insights.json"
]

  3. Create a new version of your property.

    New-PropertyVersion -PropertyName MyProperty -CreateFromVersion 3

    propertyLink                                                              propertyVersion
------------                                                              ---------------
/papi/v1/properties/12345/versions/11?contractId=C-0N7RAC7&groupId=12345               4

  4. Add your rules to the new property version.

    Important: Because the Set-PropertyRules function is a PUT, send your entire rule tree back when making updates.

    # PS Object
Set-PropertyRules -PropertyName MyProperty -PropertyVersion 4 -Body $PropertyRules 

# -OR-

$PropertyRules | -PropertyName MyProperty -PropertyVersion 4

# File
Set-PropertyRules -PropertyName MyProperty -PropertyVersion 4 -InputDirectory "./MyProperty"

    accountId       : A-CCT1234
contractId:       C-0N7RAC7
groupId         : 12345
propertyId      : 12345
propertyName    : MyProperty
propertyVersion : 4
etag            : 1a2345bcd6e789012fg34h56i78901234j5678k9
rules           : @{name=default; children=[]; 
                  behaviors=[]; options=; variables=[]; 
                  comments=The Default Rule template contains all the necessary and 
                  recommended behaviors. Rules are evaluated from top to bottom and 
                  the last matching rule wins.}
warnings        : {}
ruleFormat      : latest

    From here, you have a couple of options.

    • Push your rule changes out without a property activation. This lets you save your updates upstream and continue editing your property, including adding or updating hostnames.
    • Push your rule changes with a property activation. This applies your changes to a network. Any additional changes you need to make require a new configuration version.

  5. Activate your property on a network to apply your changes.

    New-PropertyActivation -PropertyName MyProperty -PropertyVersion 4 -Network Staging -NotifyEmails jsmith@email.com

    activationLink                                                                   activationId
--------------                                                                   ------------
/papi/v1/properties/786543/activations/12345?contractId=C-0N7RAC7&groupId=12345         12345

Updated about 1 month ago