TrainingSupportCommunity

Includes

Suggest Edits

Includes are small chunks of a property configuration that you can create, version, and activate independently from the rest of a property's rule tree.

Each include contains its own rule trees based on the property configuration's rule format and is one of two types.

  • Microservices. Used when different teams work independently on different parts of a single site.
  • Common settings. Used when a central team manages property configurations for your site. This type of include functions as a single source of information for common settings used across different configurations.

You can use the PowerShell module to get your includes, create a new include, update an existing include, and activate or deactivate your includes.

Get base IDs

You need your contract and group IDs to work with these commands. If you don't have them, use the commands below to find them.

IDCommand
ContractIDGet-Contracts
GroupIDGet-Groups

Get includes

List all

Use your contract or group ID to a list of all your includes.

List-PropertyIncludes -ContractId C-0N7RAC7

accountId         : act_A-CCT1234
contractId        : ctr_C-0N7RAC7
groupId           : grp_12345
latestVersion     : 2
stagingVersion    : 1
productionVersion : 
assetId           : aid_12345
includeId         : inc_12345
includeName       : MyInclude1
includeType       : COMMON_SETTINGS

accountId         : act_A-CCT1234
contractId        : ctr_C-0N7RAC7
groupId           : grp_12345
latestVersion     : 1
stagingVersion    : 
productionVersion : 1
assetId           : aid_98765
includeId         : inc_98765
includeName       : MyInclude2
includeType       : MICROSERVICES

Get all versions

To get all versions of an include, pass its name in the -IncludeName parameter. 

Get-PropertyIncludeVersions -IncludeName MyInclude1

updatedByUser    : jsmith
updatedDate      : 9/21/2022 8:11:47 AM
productionStatus : INACTIVE
stagingStatus    : INACTIVE
etag             : exetag7888b96a6b6aeb49bec6ddcc823079b2e7
productId        : prd_Site_Defender
ruleFormat       : v2022-10-18
includeVersion   : 2

updatedByUser    : jsmith
updatedDate      : 7/21/2021 7:10:23 AM
productionStatus : INACTIVE
stagingStatus    : ACTIVE
etag             : exetag881d6908155b7a15ab53f1ec0278df7392f3
productId        : prd_Site_Defender
ruleFormat       : v2020-11-02
includeVersion   : 1

Create include

Create a new include, setting its name, product, rule format, and type.

📘

The rule format has to match the parent property configuration's rule format. You can get your property rules if you're not sure which rule format it's using.

New-PropertyInclude -IncludeName MyNewInclude -ProductID prd_Site_Defender -RuleFormat v2022-10-18 -IncludeType COMMON_SETTINGS -GroupID 12345 
-ContractId C-0N7RAC7

# The return is a partial HATEOAS link to the new property
includeLink
------------
/papi/v1/properties/inc_34567?contractId=ctr_C-0N7RAC7&groupId=grp_12345

You can use the URL with the host in your API client as a fully qualified HATEOAS link to get information about your new property.

Add new rule tree from JSON

For a new rule tree created from scratch in a JSON file, push the file to your include.

Set-PropertyIncludeRuleTree -IncludeName MyNewInclude -PropertyName MyProperty -PropertyVersion latest -InputFile MyNewInclude.json

To apply your changes to your property, activate your include.

Add rule tree from existing

To use an existing set of rules from another include, pull the rules down and push them to your new include.

  1. Use the name and version of an include to pull down its rule tree. There is more than one way to pull down a rule tree. See Get rules for more methods. 

    Get-PropertyIncludeRuleTree -IncludeVersion 2 -IncludeName MyInclude1

    accountId      : act_A-CCT1234
contractId     : ctr_C-0N7RAC7
groupId        : grp_12345
etag           : exetag7888b96a6b6aeb49bec6ddcc823079b2e7
rules          : @{name=default; children=System.Object[]; behaviors=System.Object[]; options=}
ruleFormat     : v2022-10-18
includeId      : inc_12345
includeName    : MyInclude1
includeVersion : 2
includeType    : COMMON_SETTINGS

  2. To use the rule tree as is, push it to your new include.

    Set-PropertyIncludeRuleTree -IncludeName MyNewInclude -PropertyName MyProperty -PropertyVersion latest -RuleTree

You can also update the rule set and then push your changes.

Update includes

To update an existing includes, base a new version off of one of its previous versions.

  1. Create a new version. 

    New-PropertyIncludeVersion -CreateFromVersion 2 -IncludeName MyInclude1

    # The return is a partial HATEOAS link to the new property
versionLink
-----------
/papi/v1/includes/inc_87654/versions/3

    You can use the URL with the host in your API client as a fully qualified HATEOAS link to get information about your new property.

  2. Pull down the include's rule tree.

    Get-PropertyIncludeRuleTree -IncludeVersion 2 -IncludeName MyNewIncludeVersion

    accountId      : act_A-CCT1234
contractId     : ctr_C-0N7RAC7
groupId        : grp_12345
etag           : exetag7888b96a6b6aeb49bec6ddcc823079b2e7
rules          : @{name=default; children=System.Object[]; behaviors=System.Object[]; options=}
ruleFormat     : v2022-10-18
includeId      : inc_12345
includeName    : MyInclude1
includeVersion : 2
includeType    : COMMON_SETTINGS

  3. Make your changes using an object or in your JSON file. 

    # Here, the rules were pulled down into a variable named $Rules.
$Rules.rules.behaviors[0].options.hostname = "neworigin.example.com"
$Rules.comments = "Updating origin hostname"

    There is no response, but you can verify your change by sending the mapped variable through your console.

    $Rules.comments

    Updating origin hostname

  4. Push your changes to your new include version.

    # Update from an object
Set-PropertyIncludeRuleTree -IncludeName MyNewIncludeVersion -PropertyName MyProperty -PropertyVersion latest

#Update from a JSON file
Set-PropertyIncludeRuleTree -IncludeName MyNewIncludeVersion -PropertyName MyProperty -PropertyVersion latest -InputFile MyNewInclude_1.json

To apply your changes to your property, activate your include.

Activate includes

Because includes can be deployed independently and directly affect your larger property configurations, the importance of checking their behavior on staging before deployment to your production instances cannot be overstated. For this reason, each of your includes should have one activation in staging and one in production.

For new includes:

  • Activation does not immediately apply rules because the includes are not directly assigned to hosts. Activation only makes it available for use.
  • Application of the includes comes when you associate an includes to a property.
    1. Version the property configuration.
    2. Add it to the property configuration's rule tree.
    3. Activate the property.

For existing includes that are versioning up, activation immediately deploys the changes to the parent property.

To activate an include, send the include's version, name or ID, activation network, and a list of who to notify about the activation.

Activate-PropertyInclude -IncludeVersion 3 -IncludeName MyNewIncludeVersion -Network Staging -NotifyEmails jsmith@example.com

# The return is a partial HATEOAS link to the new property
activationLink
--------------
/papi/v1/includes/76543/activations/ACTIDbb3-2207-4651-b644-9b9f00a3794d

You can use the URL with the host in your API client as a fully qualified HATEOAS link to get information about your new property.

Updated 10 months ago