XML Rule Definition Syntax

XML Rule Definition Syntax

Dynamic Roles are defined by a set of rules. These rules are expressed as XML. This page lists the available XML tags and gives some samples.

Logical Operators

Multiple rules can be combined by the logical operators AND and OR, and single rules can be negated by using the logical NOT operator.

The AND operator combines multiple rules by a logical AND. Thus, all rules enclosed in the AND tag must evaluate to true.

<and>
<rule1 />
<rule2 />
</and>

The OR operator combines multiple rules by a logical OR. Thus, at least one rule enclosed in the OR tag must evaluate to true.

<or>
<rule1 />
<rule2 />
</or>

The NOT operator negates a single rule enclosed in the OR tag. This, if the rule returns true, it is negated to false and vice versa.

<not>
<rule1 />
</not>

Please note that every ruleset must be enclosed in a logical outer tag. Thus, every ruleset must start with and AND, OR, or NOT operator – even if there is only one rule in your ruleset.

The logical operators can be combined with each other by nesting the corresponding tags.

<and>
<rule1 />
<rule2 />
<or>
<rule3 />
<rule4 />
<not>
<rule5 />
</not>
</or>
</and>
The pseudo-rules <true /> and <false /> can be used for testing purposes. They always evaluate to true or false.

Role Membership

Dynamic roles can be built on top of other roles. These roles can be static (so administered manually by a site operator) or they can be dynamic themselves. Please note that this rule always evaluates to false for anonymous requests.

<and>
<member role="goodCustomer" />
<member role="originGermany" />
</and>

In this example, the user must be in both roles “goodCustomer” and “originGermany” in order for the ruleset to evaluate to true.

  • role (required): The role to be checked for.

Cookies

You can check if a certain cookie is present, and (optionally) if it has a certain value.

<cookie name="first-visit" pattern="^2014-.*$" />

In this example, the user must have a cookie with the name “first-visit” present and the cookies content has to start with the string “2014-“.

  • name (required): The name of the cookie.
  • pattern (optional): The value of the cookie to match. This is a regular expression. If this parameter is not specified, the existence of the cookie is sufficient for the rule to evaluate to true.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.

Referer

Check the referer/referrer. This is the url of the page the user visited before coming to your site. Please note that you cannot rely on the referer: In many cases, browsers do not set this http request header.

<referer pattern="^http(s)?://(www.)?weweave.net/.*$" />

In this example, the user must come from weweave.net – either via http or via https, and either with or without “www.”.

  • pattern (required): A regular expression to check the referer against (case insensitive).

Browser

Check the browser (interpreted user agent) a user uses. Please note that user agents can be faked, so you should not rely on the correctness.

<or>
<browser type="internetexplorer" minVersion="6" maxVersion="9" />
<browser type="firefox" maxVersion="20.1" />
</or>

In this example, the user must use Internet Explorer 6-9, or Firefox <= 20.1.

  • type (required): One of the following values: internetexplorer, firefox, chrome, opera, safari.
  • minVersion (optional): The minimum version (major and minor, inclusive).
  • maxVersion (optional): The maximum version (major and minor, inclusive).

User Agent

Check the raw user agent reported by the client. Please note that user agents can be faked, so you should not rely on the correctness.

<userAgent pattern=".*lynx.*" />

In this example, the user must use a version of Lynx.

  • pattern (required): A regular expression matched against the HTTP request header “User-Agent” (case insensitive).

Request Parameter

Check if a certain request parameter (GET or POST) is present and, if desired, it has a certain value.

<requestParam name="query" pattern="^error.*$" method="get" />

In this example, the HTTP GET parameter “query” must be present and its value must start with the string “error”.

  • name (required): The name of the request parameter.
  • pattern (optional): A regular expression of the required parameter value.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.
  • method (optional): The request method employed. One of the following values: get, post. If this parameter is not supplied, the parameter is searched in both GET and POST section.

Date

Check if the current date is within a certain range. The server-side timestamp is used for this check.

<date min="2014-12-01" max="2014-12-24" />

In this example, the current date must be between 12/01/2014 and 12/24/2014.

  • min (required): The minimum date (inclusive). Format: yyyy-MM-dd
  • max (required): The maximum date (inclusive). Format: yyyy-MM-dd

Time

Check if the current time is within a certain range. The server-side timestamp is used for this check.

<time min="09:00:00" max="15:30:00" />

In this example, the current date must be between 9:00 AM and 3:30 PM.

  • min (required): The minimum time (inclusive) in 24h format. Format: HH:mm:ss
  • max (required): The maximum time (inclusive) in 24h format. Format: HH:mm:ss

Date and Time

Check if the current timestamp is within a certain range. The server-side timestamp is used for this check.

<dateTime min="2014-12-01 15:00:00" max="2014-12-31 09:00:00" />

In this example, the current date must be between 12/01/2014 3:30 PM and 12/31/2014 9:00 AM.

  • min (required): The minimum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss
  • max (required): The maximum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss

SQL Query

Run an SQL Query and evaluate the result. The rule evaluates to true if the value of the first column in the first row is “1”, and to false otherwise.

<sql query="SELECT COUNT(*) FROM sales WHERE customer_id = @UserId@ LIMIT 1" />

In this example, there must be a row in the “sales” table where the customer’s ID matches the current user’s ID.

  • query (required): The query to execute. You can use the placeholder @UserId@ which will be replaced with the current user’s ID, and @PortalId@ which will be replaced with the current portal’s ID. Please [email protected]@ is always null for anonymous requests. Both parameters are passed as int.

Geo Location

Check the user’s IP address against MaxMind‘s geo ip database. You need an account at MaxMind in order to use this rule.

<geoMaxMindCountry userId="1" licenseKey="abc" service="city" country="US" />

In this example, the user’s IP address must be located in the US.

  • userId (required): MaxMind User ID.
  • licenseKey (required): MaxMind License Key.
  • service (required): MaxMind’s endpoint to be used. One of the following values: city, country, insights
  • country (required): Two-letter ISO Country Code (i.e. “US” or “DE”).

Random >= 01.03.00

Evaluates randomly to true or false (i.e. useful for A/B testing).

<random ratio="0.5" />

In this example, the rule returns true in 50% of all requests, and false in the other 50%.

  • ratio (required): The ratio between 0.0 and 1.0 at which the rule evaluates to true.

Administrator User >= 01.04.00

Checks is the current user is an administrator.

<administratorUser />

Super User >= 01.04.00

Checks is the current user is a super user.

<superUser />

Unauthenticated User >= 01.04.00

Checks is the current user is an unauthenticated user.

<unauthenticatedUser />

Registered User >= 01.04.00

Checks is the current user is a registered user.

<registeredUser />

User’s email address >= 01.04.00

Checks if the user’s email address matches a specific pattern.

<email pattern=".[email protected]\.com" />
  • pattern (required): A regular expression of the required email address pattern.

User’s first name >= 01.04.00

Checks if the user’s first name matches a specific pattern.

<firstName pattern="A.*" />
  • pattern (required): A regular expression of the required first name.

User’s last name >= 01.04.00

Checks if the user’s last name matches a specific pattern.

<lastName pattern="A.*" />
  • pattern (required): A regular expression of the required last name.

User’s preferred locale >= 01.04.00

Checks if the user’s preferred locale matches a specific pattern.

<preferredLocale pattern="de_DE" />
  • pattern (required): A regular expression of the required locale.