Guide

Includes

Suggest Edits

Includes are rule configurations that are independent of a property's configuration.

What you'll do

  1. Learn about includes.
  2. Create an include.
  3. Get an include's rules and make changes.
  4. Update the include.
  5. Activate the include.

About includes

The decoupling of includes rules from a property's rule tree from gives you flexibility and agility with your site's traffic management.

An include is a single-source rule configuration you can use across multiple properties or an isolated set of rules for a particular area of your site. This functional difference works to reduce inter-team dependencies on task completion while protecting permission levels to different areas of your site at the same time.

  • Microservices includes. Let different teams work on different parts of a single site. For example, a marketing team can set actions to the information captured in a cookie and apply them without having to wait on IT to deploy changes.
  • Common settings includes. Give a central team that manages property configurations for single source of information for common settings used across different configurations.

Includes are associated with properties using an Includes behavior that's added to to a property configuration's rule tree. This association requires a one-time property reactivation.

Once that change is live, the includes activation and any future updates and reactivation immediately apply their settings to your traffic without having to update and activate a new property version.

Create include

Create a new include or a new include based on an existing one.

  • A new include doesn't have any rules defined but does have a rule schema.
  • A cloned include comes with a copy of the original includes rules. 
# New
New-PropertyInclude -Name MyInclude -ProductID prd_Download_Delivery -IncludeType COMMON_SETTINGS -GroupID 12345 -ContractID C-0N7RAC7

## New from existing
New-PropertyInclude -Name MyIncludeClone -CloneIncludeName MyOriginalInclude -ProductID prd_Download_Delivery -IncludeType COMMON_SETTINGS -GroupID 12345 -ContractID C-0N7RAC7

includeLink                                                 includeId
-----------                                                 ---------
/papi/v1/includes/98765?contractId=C-0N7RAC7&groupId=12345      98765

Get the include's rule schema to build out or update the include's rules.

Create new version

Use any version of an include to create a new inactive, editable version. To use the latest version of an include, pass a value of latest for -CreateFromVersion.

New-PropertyIncludeVersion -IncludeName MyInclude -CreateFromVersion latest

versionLink                                                             includeVersion
-----------                                                             --------------
/papi/v1/includes/12345/versions/2?contractId=C-0N7RAC7&groupId=12345                2

Get includes

Pass your contract and group IDs get a list of all your includes. For a single include, add on the include's name or ID.

# Get all
Get-PropertyInclude -ContractID C-0N7RAC7 -GroupID 12345

# Get one
Get-PropertyInclude -ContractID C-0N7RAC7 -GroupID 12345 -IncludeName MyInclude

accountId         : A-CCT1234
contractId        : C-0N7RAC7
groupId           : 12345
latestVersion     : 2
stagingVersion    : 1
productionVersion : 
assetId           : 12345
includeId         : 12345
includeName       : MyInclude
includeType       : COMMON_SETTINGS

accountId         : A-CCT1234
contractId        : C-0N7RAC7
groupId           : 12345
latestVersion     : 1
stagingVersion    : 
productionVersion : 1
assetId           : 98765
includeId         : 98765
includeName       : MyIncludeClone
includeType       : MICROSERVICES

accountId         : A-CCT1234
contractId        : C-0N7RAC7
groupId           : 12345
latestVersion     : 2
stagingVersion    : 1
productionVersion : 
assetId           : 12345
includeId         : 12345
includeName       : MyInclude
includeType       : COMMON_SETTINGS

Get include rules

Get an include's rule schema by name or ID and version.

  • Set your include's 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.

To get the latest version of an include's rules, use a value of latest for -IncludeVersion.

# PS Object
$PropertyInclude =  Get-PropertyIncludeRules -IncludeName MyInclude -IncludeVersion latest

# Single file
Get-PropertyIncludeRules -IncludeName MyInclude -IncludeVersion latest -OutputToFile 

# Snippets
Get-PropertyIncludeRules -IncludeName MyInclude -IncludeVersion latest -OutputSnippets

# PS Object
accountId      : A-CCT1234
contractId     : C-0N7RAC7
groupId        : 12345
etag           : 1a2345bcd6e789012fg34h56i78901234j5678k9
rules          : @{name=default; children=[]; behaviors=[]; 
                 options={}}
ruleFormat     : v2024-10-21
includeId      : 12345
includeName    : MyInclude
includeVersion : 1
includeType    : COMMON_SETTINGS

# Single file
Wrote version 1 of include MyInclude to MyInclude.json

#Snippets
Creating new property directory MyProperty
Wrote version 1 of include MyInclude to MyInclude

Make changes to your rules as needed and then update the include.

If your include is already active, you need to create a new include version and then update that version of the include with your rules.

Update include rules

Once you're done making changes to your rules, use the name or ID, version, and location of your JSON file to update the rule set associated with the include.

Set-PropertyIncludeRules -IncludeName MyInclude -IncludeVersion latest -InputFile ./include-rules.json

accountId      : A-CCT1234
contractId     : C-0N7RAC7
groupId        : 12345
etag           : 1a2345bcd6e789012fg34h56i78901234j5678k9
rules          : @{name=default; children=[]; behaviors=[]; options={}}
errors         : {}
ruleFormat     : v2024-10-21
includeId      : 12345
includeName    : MyInclude
includeVersion : 1
includeType    : COMMON_SETTINGS

Activate your include to apply its settings to associated properties.

Activate include

Activating an include already associated with a property deploys the include's settings directly to your traffic.

When you're activating an include not associated with a property, its settings won't apply to your traffic until you add it to a property configuration's rules. To do this, update your property rules.

New-PropertyIncludeActivation -IncludeName MyInclude -IncludeVersion latest -Network staging -NotifyEmails jsmith@email.com

activationLink                                                                                               activationId
--------------                                                                                               ------------
/papi/v1/includes/12345/activations/1a234567-8b90-1c23-d4ef-g56h78i9jk0l?contractId=C-0N7RAC7&groupId=12345  1a234567-8b90-1c23-d4ef-g56h78i9jk0l

Returned is a link to the include's activation and its GUID ID needed if you want to check the activation's status.

Updated 4 months ago