setVariable

  • Property Manager name: Set Variable
  • Behavior version: The v2023-01-05 rule format supports the setVariable behavior v1.5.
  • Rule format status: GA, stable
  • Access: Read-write
  • Allowed in includes: Yes

Modify a variable to insert into subsequent fields within the rule tree. Use this behavior to specify the predeclared variable‚ÄčName and determine from where to derive its new value. Based on this value‚ÄčSource, you can either generate the value, extract it from some part of the incoming request, assign it from another variable (including a set of built-in system variables), or directly specify its text. Optionally choose a transform function to modify the value once. See Support for variables for more information.

OptionTypeDescriptionRequires
variable‚ÄčNamestring (variable name)

Specifies the predeclared root name of the variable to modify. When you declare a variable name such as VAR, its name is preprended with PMUSER_ and accessible in a user namespace, so that you invoke it in subsequent text fields within the rule tree as {{user.‚ÄčPMUSER_‚ÄčVAR}}. In deployed XML metadata, it appears as %(PMUSER_‚ÄčVAR).

{"displayType":"string","tag":"input","type":"text"}
value‚ÄčSourceenum

Determines how you want to set the value.

{"displayType":"enum","options":["EXPRESSION","EXTRACT","GENERATE"],"tag":"select"}
EXPRESSION

Specify your own string expression.

EXTRACT

Extract it from another value.

GENERATE

Generate the value.

variable‚ÄčValuestring (allows¬†variables)

This directly specifies the value to assign to the variable. The expression may include a mix of static text and other variables, such as new_filename.{{builtin.‚ÄčAK_‚ÄčEXTENSION}} to embed a system variable.

value‚ÄčSource is EXPRESSION
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"valueSource","op":"eq","value":"EXPRESSION"}}
extract‚ÄčLocationenum

This specifies from where to get the value.

value‚ÄčSource is EXTRACT
{"displayType":"enum","options":["CLIENT_CERTIFICATE","CLIENT_REQUEST_HEADER","COOKIE","EDGESCAPE","PATH_COMPONENT_OFFSET","QUERY_STRING","DEVICE_PROFILE","RESPONSE_HEADER","SET_COOKIE"],"tag":"select"}
{"if":{"attribute":"valueSource","op":"eq","value":"EXTRACT"}}
CLIENT_‚ÄčCERTIFICATE

Client certificate.

CLIENT_‚ÄčREQUEST_‚ÄčHEADER

Client request header.

COOKIE

Cookie.

EDGESCAPE

For location or network data.

PATH_‚ÄčCOMPONENT_‚ÄčOFFSET

Substring within the URL path.

QUERY_‚ÄčSTRING

A query parameter.

DEVICE_‚ÄčPROFILE

For client device attributes.

RESPONSE_‚ÄčHEADER

A response header.

SET_‚ÄčCOOKIE

Cookie.

certificate‚ÄčField‚ÄčNameenum

Specifies the certificate's content.

extract‚ÄčLocation is CLIENT_‚ÄčCERTIFICATE
{"displayType":"enum","options":["VERSION","SERIAL","FINGERPRINT_MD5","FINGERPRINT_SHA1","FINGERPRINT_DYN","ISSUER_DN","SUBJECT_DN","NOT_BEFORE","NOT_AFTER","SIGNATURE_ALGORITHM","SIGNATURE","CONTENTS_DER","CONTENTS_PEM","CONTENTS_PEM_NO_LABELS","COUNT","STATUS_MSG","KEY_LENGTH"],"tag":"select"}
{"if":{"attribute":"extractLocation","op":"eq","value":"CLIENT_CERTIFICATE"}}
VERSION

The certificate's X509 version number.

SERIAL

The serial number, expressed in hex.

FINGERPRINT_‚ÄčMD5

The hex-encoded MD5 fingerprint.

FINGERPRINT_‚ÄčSHA1

The hex-encoded SHA1 fingerprint.

FINGERPRINT_‚ÄčDYN

The hex-encoded fingerprint generated based on the SIGNATURE_‚ÄčALGORITHM.

ISSUER_‚ÄčDN

The distinguished name field for the certificate's issuer.

SUBJECT_‚ÄčDN

The distinguished name field for the user.

NOT_‚ÄčBEFORE

The start of the time range, expressed in YYYY/MM/DD HH:MI:SS ZONE format, where the zone is optional.

NOT_‚ÄčAFTER

The end of the time range, expressed in YYYY/MM/DD HH:MI:SS ZONE format, where the zone is optional.

SIGNATURE_‚ÄčALGORITHM

The algorithm used to generate the certificate's signature.

SIGNATURE

The certificate's signature, expressed in hex.

CONTENTS_‚ÄčDER

The entire DER-encoded certificate, expressed in hex.

CONTENTS_‚ÄčPEM

The PEM-formatted certificate encoded as a single line of base64 characters.

CONTENTS_‚ÄčPEM_‚ÄčNO_‚ÄčLABELS

Same as CONTENTS_‚ÄčPEM, but not including the certificate's header and footer.

COUNT

The number of client certificates received.

STATUS_‚ÄčMSG

A short message indicating the status of a certificate's validation, such as ok or missing.

KEY_‚ÄčLENGTH

The size of the key in bits.

header‚ÄčNamestring

Specifies the case-insensitive name of the HTTP header to extract.

extract‚ÄčLocation is CLIENT_‚ÄčREQUEST_‚ÄčHEADER
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"extractLocation","op":"eq","value":"CLIENT_REQUEST_HEADER"}}
response‚ÄčHeader‚ÄčNamestring

Specifies the case-insensitive name of the HTTP header to extract.

extract‚ÄčLocation is RESPONSE_‚ÄčHEADER
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"extractLocation","op":"eq","value":"RESPONSE_HEADER"}}
location‚ÄčIdenum

Specifies the X-Akamai-Edgescape header's field name. Possible values specify basic geolocation, various geographic standards, and information about the client's network. For details on Edge‚ÄčScape header fields, see the Edge‚ÄčScape User Guide.

extract‚ÄčLocation is EDGESCAPE
{"displayType":"enum","options":["GEOREGION","COUNTRY_CODE","REGION_CODE","CITY","DMA","PMSA","MSA","AREACODE","COUNTY","FIPS","LAT","LONG","TIMEZONE","ZIP","CONTINENT","NETWORK","NETWORK_TYPE","ASNUM","THROUGHPUT","BW"],"tag":"select"}
{"if":{"attribute":"extractLocation","op":"eq","value":"EDGESCAPE"}}
GEOREGION

Region.

COUNTRY_‚ÄčCODE

ISO-3166 country code.

REGION_‚ÄčCODE

ISO-3166 region code.

CITY

City.

DMA

Designated Market Area.

PMSA

Primary Metropolitan Statistical Area.

MSA

Metropolitan Statistical Area.

AREACODE

Area code.

COUNTY

County.

FIPS

Federal Information Processing System code.

LAT

Latitude.

LONG

Longitude.

TIMEZONE

Time zone.

ZIP

Zip code.

CONTINENT

Two-letter continent code.

NETWORK

Network name.

NETWORK_‚ÄčTYPE

Network type.

ASNUM

Autonomous System Number.

THROUGHPUT

Tiered throughput level.

BW

Tiered bandwidth level.

path‚ÄčComponent‚ÄčOffsetstring

This specifies a portion of the path. The indexing starts from 1, so a value of /path/to/nested/filename.‚Äčhtml and an offset of 1 yields path, and 3 yields nested. Negative indexes offset from the right, so -2 also yields nested.

extract‚ÄčLocation is PATH_‚ÄčCOMPONENT_‚ÄčOFFSET
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"extractLocation","op":"eq","value":"PATH_COMPONENT_OFFSET"}}
query‚ÄčParameter‚ÄčNamestring

Specifies the name of the query parameter from which to extract the value.

extract‚ÄčLocation is QUERY_‚ÄčSTRING
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"extractLocation","op":"eq","value":"QUERY_STRING"}}
generatorenum

This specifies the type of value to generate.

value‚ÄčSource is GENERATE
{"displayType":"enum","options":["HEXRAND","RAND"],"tag":"select"}
{"if":{"attribute":"valueSource","op":"eq","value":"GENERATE"}}
HEXRAND

A random hex sequence.

RAND

A random number.

number‚ÄčOf‚ÄčBytesnumber (1-16)

Specifies the number of random hex bytes to generate.

generator is HEXRAND
{"displayType":"number","max":[16],"min":[1],"tag":"input","type":"range"}
{"if":{"attribute":"generator","op":"eq","value":"HEXRAND"}}
min‚ÄčRandom‚ÄčNumberstring (allows¬†variables)

Specifies the lower bound of the random number.

generator is RAND
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"generator","op":"eq","value":"RAND"}}
max‚ÄčRandom‚ÄčNumberstring (allows¬†variables)

Specifies the upper bound of the random number.

generator is RAND
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"generator","op":"eq","value":"RAND"}}
transformenum

Specifies a function to transform the value. For more details on each transform function, see Set Variable: Operations.

{"displayType":"enum","options":["NONE","ADD","BASE_64_DECODE","BASE_64_ENCODE","BITWISE_AND","BITWISE_NOT","BITWISE_OR","BITWISE_XOR","DECIMAL_TO_HEX","DECRYPT","DIVIDE","ENCRYPT","EPOCH_TO_STRING","EXTRACT_PARAM","HASH","HEX_TO_DECIMAL","HEX_DECODE","HEX_ENCODE","HMAC","LOWER","MD5","MINUS","MODULO","MULTIPLY","NORMALIZE_PATH_WIN","REMOVE_WHITESPACE","SHA_1","SHA_256","STRING_INDEX","STRING_LENGTH","STRING_TO_EPOCH","SUBSTITUTE","SUBSTRING","SUBTRACT","TRIM","UPPER","URL_DECODE","URL_ENCODE","URL_DECODE_UNI","UTC_SECONDS","XML_DECODE","XML_ENCODE"],"tag":"select"}
NONE

No transformation.

ADD

Arithmetic function.

BASE_64_DECODE

String encoding.

BASE_64_ENCODE

String encoding.

BITWISE_‚ÄčAND

Bitwise operation.

BITWISE_‚ÄčNOT

Bitwise operation.

BITWISE_‚ÄčOR

Bitwise operation.

BITWISE_‚ÄčXOR

Bitwise operation.

DECIMAL_‚ÄčTO_‚ÄčHEX

Numeric conversion.

DECRYPT

String encoding.

DIVIDE

Arithmetic function.

ENCRYPT

String encoding.

EPOCH_‚ÄčTO_‚ÄčSTRING

Time format.

EXTRACT_‚ÄčPARAM

String format.

HASH

Integer data digest.

HEX_‚ÄčTO_‚ÄčDECIMAL

Numeric conversion.

HEX_‚ÄčDECODE

String conversion.

HEX_‚ÄčENCODE

String conversion.

HMAC

Data digest.

LOWER

String function.

MD5

Data digest.

MINUS

Arithmetic function, reverse sign.

MODULO

Arithmetic function, get remainder.

MULTIPLY

Arithmetic function.

NORMALIZE_‚ÄčPATH_‚ÄčWIN

Convert Windows paths to Unix format and remove relative path syntax.

REMOVE_‚ÄčWHITESPACE

String conversion.

SHA_1

Data digest.

SHA_256

Data digest.

STRING_‚ÄčINDEX

String function: locate substring.

STRING_‚ÄčLENGTH

String function.

STRING_‚ÄčTO_‚ÄčEPOCH

Time format.

SUBSTITUTE

String function.

SUBSTRING

String function: locate index.

SUBTRACT

Arithmetic function.

TRIM

Trim surrounding whitespace in string.

UPPER

String function.

URL_‚ÄčDECODE

String conversion.

URL_‚ÄčENCODE

Unicode string conversion.

URL_‚ÄčDECODE_‚ÄčUNI

String conversion.

UTC_‚ÄčSECONDS

Time format.

XML_‚ÄčDECODE

String conversion.

XML_‚ÄčENCODE

String conversion.

operand‚ÄčOnestring (allows¬†variables)

Specifies an additional operand when the transform function is set to various arithmetic functions (ADD, SUBTRACT, MULTIPLY, DIVIDE, or MODULO) or bitwise functions (BITWISE_‚ÄčAND, BITWISE_‚ÄčOR, or BITWISE_‚ÄčXOR).

transform is either: ADD, BITWISE_‚ÄčAND, BITWISE_‚ÄčOR, BITWISE_‚ÄčXOR, DIVIDE, MODULO, MULTIPLY, SUBTRACT
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"in","value":["ADD","BITWISE_AND","BITWISE_OR","BITWISE_XOR","DIVIDE","MODULO","MULTIPLY","SUBTRACT"]}}
algorithmenum

Specifies the algorithm to apply.

transform is either: ENCRYPT, DECRYPT
{"displayType":"enum","options":["ALG_3DES","ALG_AES128","ALG_AES256"],"tag":"select"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
ALG_3DES

Triple DES.

ALG_‚ÄčAES128

Advanced Encryption Standard, 128 bits.

ALG_‚ÄčAES256

Advanced Encryption Standard, 256 bits.

encryption‚ÄčKeystring (allows¬†variables)

Specifies the encryption hex key. For ALG_3DES it needs to be 48 characters long, 32 characters for ALG_‚ÄčAES128, and 64 characters for ALG_‚ÄčAES256.

transform is either: ENCRYPT, DECRYPT
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
initialization‚ÄčVectorstring

Specifies a one-time number as an initialization vector. It needs to be 15 characters long for ALG_3DES, and 32 characters for both ALG_‚ÄčAES128 and ALG_‚ÄčAES256.

transform is either: ENCRYPT, DECRYPT
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
encryption‚ÄčModeenum

Specifies the encryption mode.

transform is either: ENCRYPT, DECRYPT
{"displayType":"enum","options":["CBC","ECB"],"tag":"select"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
CBC

Cipher Block Chaining.

ECB

Electronic Codebook.

noncestring (allows variables)

Specifies the one-time number used for encryption.

transform is either: ENCRYPT, DECRYPT
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
prepend‚ÄčBytesboolean

Specifies a number of random bytes to prepend to the key.

transform is either: ENCRYPT, DECRYPT
{"displayType":"boolean","tag":"input","type":"checkbox"}
{"if":{"attribute":"transform","op":"in","value":["ENCRYPT","DECRYPT"]}}
format‚ÄčStringstring

Specifies an optional format string for the conversion, using format codes such as %m/%d/%y as specified by strftime. A blank value defaults to RFC-2616 format.

transform is either: EPOCH_‚ÄčTO_‚ÄčSTRING, STRING_‚ÄčTO_‚ÄčEPOCH
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"in","value":["EPOCH_TO_STRING","STRING_TO_EPOCH"]}}
param‚ÄčNamestring (allows¬†variables)

Extracts the value for the specified parameter name from a string that contains key/value pairs. (Use separator below to parse them.)

transform is EXTRACT_‚ÄčPARAM
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"EXTRACT_PARAM"}}
separatorstring

Specifies the character that separates pairs of values within the string.

transform is EXTRACT_‚ÄčPARAM
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"EXTRACT_PARAM"}}
minnumber

Specifies a minimum value for the generated integer.

transform is HASH
{"displayType":"number","tag":"input","type":"number"}
{"if":{"attribute":"transform","op":"eq","value":"HASH"}}
maxnumber

Specifies a maximum value for the generated integer.

transform is HASH
{"displayType":"number","tag":"input","type":"number"}
{"if":{"attribute":"transform","op":"eq","value":"HASH"}}
hmac‚ÄčKeystring (allows¬†variables)

Specifies the secret to use in generating the base64-encoded digest.

transform is HMAC
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"HMAC"}}
hmac‚ÄčAlgorithmenum

Specifies the algorithm to use to generate the base64-encoded digest.

transform is HMAC
{"displayType":"enum","options":["SHA1","SHA256","MD5"],"tag":"select"}
{"if":{"attribute":"transform","op":"eq","value":"HMAC"}}
SHA1

SHA-1.

SHA256

SHA-256.

MD5

MD5.

ip‚ÄčVersionenum

Specifies the IP version under which a subnet mask generates.

transform is NETMASK
{"displayType":"enum","options":["IPV4","IPV6"],"tag":"select"}
{"if":{"attribute":"transform","op":"eq","value":"NETMASK"}}
IPV4

Use IPv4.

IPV6

Use IPv6.

ipv6Prefixnumber (0-128)

Specifies the prefix of the IPV6 address, a value between 0 and 128.

ip‚ÄčVersion is IPV6
{"displayType":"number","max":[128],"min":[0],"tag":"input","type":"range"}
{"if":{"attribute":"ipVersion","op":"eq","value":"IPV6"}}
ipv4Prefixnumber (0-32)

Specifies the prefix of the IPV4 address, a value between 0 and 32.

ip‚ÄčVersion is IPV4
{"displayType":"number","max":[32],"min":[0],"tag":"input","type":"range"}
{"if":{"attribute":"ipVersion","op":"eq","value":"IPV4"}}
sub‚ÄčStringstring (allows¬†variables)

Specifies a substring for which the returned value represents a zero-based offset of where it appears in the original string, or -1 if there's no match.

transform is STRING_‚ÄčINDEX
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"STRING_INDEX"}}
regexstring

Specifies the regular expression pattern (PCRE) to match the value.

transform is SUBSTITUTE
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"SUBSTITUTE"}}
replacementstring (allows variables)

Specifies the replacement string. Reinsert grouped items from the match into the replacement using $1, $2 ... $n.

transform is SUBSTITUTE
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"SUBSTITUTE"}}
case‚ÄčSensitiveboolean

Enabling this makes all matches case sensitive.

transform is either: EXTRACT_‚ÄčPARAM, SUBSTITUTE
{"displayType":"boolean","tag":"input","type":"checkbox"}
{"if":{"attribute":"transform","op":"in","value":["EXTRACT_PARAM","SUBSTITUTE"]}}
global‚ÄčSubstitutionboolean

Replaces all matches in the string, not just the first.

transform is SUBSTITUTE
{"displayType":"boolean","tag":"input","type":"checkbox"}
{"if":{"attribute":"transform","op":"eq","value":"SUBSTITUTE"}}
start‚ÄčIndexstring

Specifies the zero-based character offset at the start of the substring. Negative indexes specify the offset from the end of the string.

transform is SUBSTRING
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"SUBSTRING"}}
end‚ÄčIndexstring

Specifies the zero-based character offset at the end of the substring, without including the character at that index position. Negative indexes specify the offset from the end of the string.

transform is SUBSTRING
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"SUBSTRING"}}
except‚ÄčCharsstring

Specifies characters not to encode, possibly overriding the default set.

transform is URL_‚ÄčENCODE
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"URL_ENCODE"}}
force‚ÄčCharsstring

Specifies characters to encode, possibly overriding the default set.

transform is URL_‚ÄčENCODE
{"displayType":"string","tag":"input","type":"text"}
{"if":{"attribute":"transform","op":"eq","value":"URL_ENCODE"}}
device‚ÄčProfileenum

Specifies the client device attribute. Possible values specify information about the client device, including device type, size and browser. For details on fields, see Device Characterization.

extract‚ÄčLocation is DEVICE_‚ÄčPROFILE
{"displayType":"enum","options":["IS_MOBILE","IS_TABLET","IS_WIRELESS_DEVICE","PHYSICAL_SCREEN_HEIGHT","PHYSICAL_SCREEN_WIDTH","RESOLUTION_HEIGHT","RESOLUTION_WIDTH","VIEWPORT_WIDTH","BRAND_NAME","DEVICE_OS","DEVICE_OS_VERSION","DUAL_ORIENTATION","MAX_IMAGE_HEIGHT","MAX_IMAGE_WIDTH","MOBILE_BROWSER","MOBILE_BROWSER_VERSION","PDF_SUPPORT","COOKIE_SUPPORT"],"tag":"select"}
{"if":{"attribute":"extractLocation","op":"eq","value":"DEVICE_PROFILE"}}
IS_‚ÄčMOBILE

Basic device attributes, boolean.

IS_‚ÄčTABLET

Basic device attributes, boolean.

IS_‚ÄčWIRELESS_‚ÄčDEVICE

Basic device attributes, boolean.

PHYSICAL_‚ÄčSCREEN_‚ÄčHEIGHT

Device screen size in millimeters.

PHYSICAL_‚ÄčSCREEN_‚ÄčWIDTH

Device screen size in millimeters.

RESOLUTION_‚ÄčHEIGHT

Device screen size in pixels.

RESOLUTION_‚ÄčWIDTH

Device screen size in pixels.

VIEWPORT_‚ÄčWIDTH

Device viewport size in millimeters.

BRAND_‚ÄčNAME

Basic device attributes, string values.

DEVICE_‚ÄčOS

Basic device attributes, string values.

DEVICE_‚ÄčOS_‚ÄčVERSION

Basic device attributes, string values.

DUAL_‚ÄčORIENTATION

Whether the display adapts to portrait/landscape orientation.

MAX_‚ÄčIMAGE_‚ÄčHEIGHT

Maximum image size that can be displayed, in pixels.

MAX_‚ÄčIMAGE_‚ÄčWIDTH

Maximum image size that can be displayed, in pixels.

MOBILE_‚ÄčBROWSER

Basic device attributes, string values.

MOBILE_‚ÄčBROWSER_‚ÄčVERSION

Basic device attributes, string values.

PDF_‚ÄčSUPPORT

Device support capabilities, boolean.

COOKIE_‚ÄčSUPPORT

Device support capabilities, boolean.