Send feedback on this topic

Rules API

You can implement the Oracle Data Cloud category and rules web services to independently classify the page and user attributes ingested from your site or classify your onboarded offline data. Classification is the process in which your data that has been transferred into the Oracle Data Cloud platform is collected and mapped to categories in your private taxonomy. Implementing the category and rule chain APIs enables you to create hierarchical categories within your taxonomy and write rules that define when an attribute (and user) get added to each category.

With the rules API, you can create classification rules based on URLs and key-value pairs (phints) that map the user data extracted from your site with the categories you have created.

Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.

In this topic  

Explore the API

The embedded I/O doc below enables you to explore the API. The I/O  doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.

Open the link below in a new tab to see the I/O doc in a three-pane format.

rules1.docs.apiary.io

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the rules API is:

services.bluekai.com/rest/taxonomyRuleChains

Create a rule

To create a rule, include a request body with the following POST call:

services.bluekai.com/rest/taxonomyRuleChains?partner.id={yourPartnerId}

When you create a rule, you specify your partner ID in the query and include parameters in the JSON body of the request. The parameters define the rule. These are the parameters you specify:

Sample request bodies

In this example, the rule is restricted to site 48603.

{
	"rules": [ {
		"taxonomyRuleOperator": { "id": 1 },
		"taxonomyRuleOperatorParams": [
			{ "name": "key", "value": "drink" },
			{ "name": "value1", "value": "banana_smoothie" }
		]
	} ],
	"categories": [ { "id": 1042249} ],
	"sites": [ { "id": 48603}], 
	"partners": []
}

In this example, the rule is applicable to all sites owned by partner seat 99999..

{
	"rules": [ {
		"taxonomyRuleOperator": { "id": 1 },
		"taxonomyRuleOperatorParams": [
			{ "name": "key", "value": "drink" },
			{ "name": "value1", "value": "banana_smoothie" }
		]
	} ],
	"categories": [ { "id": 1042249} ],
	"sites": [], 
	"partners": ["id": "P99999"]
}

Response:

{
	"id": 31070824,
	"rules": [
		{
			"id": 33106879,
			"operatorExpression": "testKey=testValue",
			"taxonomyRuleOperator": {
				"id": 1,
				"name": "==",
				"formula": "{{key}}={{value1}}",
				"description": "is ",
				"createdAt": "2016-04-05T21:22:11-05:00",
				"updatedAt": "2016-04-05T21:22:11-05:00",
				"status": "active"
			},
			"taxonomyRuleOperatorParams": [
				{
					"name": "key",
					"value": "drink"
				},
				{
					"name": "value1",
					"value": "banana_smoothie"
				}
			]
		}
	],
	"categories": [
		{
			"id": 1042249,
			"name": "Banana Smoothie"
		}
	],
	"ruleChainMetaData": [],
	"classificationGroups": [],
	"sites": [
		{
			"id": 48603,
			"name": "Test"
		}
	],
		"partners": [],
		"createdAt": "2018-01-31T13:16:24-06:00",
		"updatedAt": "2018-01-31T13:16:24-06:00",
		"status": "active"
}

Bulk import (via file upload)

To create and edit multiple rules at the same time by uploading a TSV or TXT file:

  1. In the query string of your call to the Rules API, append import to the path.

    serviceUrl = 'https://services.bluekai.com/rest/taxonomyRuleChains/import?partner.id={yourPartnerId}'

  2. In the headers parameter, set the Content-Type to multipart/form-data .

    headers = {"Content-Type": "multipart/form-data; "Accept": "application/json","User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0"}

  3. Include a parameter that is set to the name of the .tsv or .txt file to be imported.
  4. Verify that the import file has the following columns:
  5. Column Description Required for Upload Value Required for Creating Rules via Upload
    Action The value entered in this column depends on the action:
    Create rule. Leave blank.
    Edit rule. Enter "modify".
    Delete rule. Enter "delete".
    YES NO
    Rule ID The unique ID generated for the rule. This is required for editing or deleting rules. YES (if editing) NO
    Site ID A pipe-separated list of the site IDs for which the rule is applicable. If the rules is applicable to all site IDs, your partner ID is listed with the following syntax: P{partnerId} (for example, P4021). YES YES
    Site ID Switch Internal-use only. Site ID switches are used to attribute the data collected from a site ID to another one. This is typically used for 3rd-party offline match partners. YES NO
    Key1

    The name of the phint key. Phint keys are case-insensitive, and they support alphanumeric and underscore characters (a-z, 0-9, and _).
    Spaces in the phint key are not supported. Do not use the period character (.) in your phint key if you plan on creating rules that use the contains operator (rules involving regex expressions will fail to evaluate the key properly).

    Rules with Multiple Phints: If a rule contains multiple phints, the export will include an additional key, op, and value column for each phint. For example, if a rule has three phints, the export will additionally include key2, Op2, Value2, key3, Op3, and Value3 columns.

    YES YES
    Op1

    The operator used to evaluate the phint value linked to the key. This may be one the following values:

    Symbol Name Description
    == is The phint value passed in the tag (or offline file) must exactly match the one in the rule.
    *_* contains The phint value must be contained within the one in the rule.
    _* starts-with The phint value must start with the one in the rule.
    *_ ends-with The phint value passed must end with the one in the rule.

    For rules created by Oracle service teams, the operator may be one of the following read-only values. These operators may be made available for rule creation in a future vesions of the Taxonomy Manager:

    Symbol Name Description
    [] range The phint value must be included between the range of two specified phint values.
    > greater than The phint value in the tag must be greater that the one in the rule.
    < less than The phint value in the tag must be less that the one in the rule.
    >= greater than or equal The phint value in the tag must be greater than or equal to the one in the rule.
    <= less than or equal The phint value in the tag must be less than or equal to the one in the rule.
    >,< greater than + less than The first phint value in the tag must be greater than the first value in the rule, AND the second phint value in the tag must be less than to the second one in the rule.
    >,<= greater than + less than or equal The first phint value in the tag must be greater than the first value in the rule, AND the second phint value in the tag must be less than or equal to the second one in the rule.
    >=,< greater than or equal + less than The first phint value in the tag must be greater than or equal to the first value in the rule, AND the second phint value in the tag must be less than to the second one in the rule.
    >=,<= greater than or equal + less than or equal The first phint value in the tag must be greater than or equal to the first value in the rule, AND the second phint value in the tag must be less be than or equal to the second one in the rule.
    YES YES
    Value1 The phint value. Phint values support all Latin-1 and UTF-8 characters (alphanumeric characters and special symbols). YES YES
    Category ID

    The unique ID assigned to the category. This column is required for editing categories via bulk upload because Taxonomy Manager identifies categories based on the unique category IDs.

    YES YES
    Category Path The full taxonomy path of the category. This column is required for adding categories with rules via bulk upload because Taxonomy Manager determines where to create new categories based on the taxonomy path. NO NO

Bulk import demo

The sample bulk_rules_import.py Python code demonstrates how to do a bulk rules import using the Rules API. To run this script, you must have the following:

You can use PIP (a Python Package Installation tool) to help install the requests library. To download and install PIP, install the requests library, and then delete the PIP installation file, enter the following commands in your console:

curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
sudo python get-pip.py
sudo pip install requests
rm get-pip.py

To run this script, you need to create a TSV file named rule_import.tsv (download template) that contains the categories you want to edit or create, and provide the following parameters:

The following example demonstrates the required syntax for calling this script:

bulk_rules_import.py --url https://services.bluekai.com -v -v -v -v --partnerid BlueKai Partner ID--bkuid WebServiceUserKey --bksecretkey WebServicePrivateKey

Update a rule

To update a rule, include your partner ID, the rule ID, and a request body with the parameters to be updated in a PUT call.

Sample PUT request:

https://services.bluekai.com/rest/taxonomyRuleChains/?partner.id={yourPartnerId}

Rules with Multi-byte Characters

To create rules for URLs that include multibyte encodings, you must encode the percentage symbols (%) in the UTF-8 encoded characters. For example, to create a URL rule for https://www.マネジメント/site.html, convert マネジメント to UTF-8, which results in the following encoding:

%e3%83%9e%e3%83%8d%e3%82%b8%e3%83%a1%e3%83%b3%e3%83%88

Encode the percentage symbols in the UTF-8 encoding (convert each % symbol to %25), which results in the following encoding:

%25e3%2583%259e%25e3%2583%258d%25e3%2582%25b8%25e3%2583%25a1%25e3%2583%25b3%25e3%2583%2588

This results in the following encoded string:

https://www.com%2F%25e3%2583%259e%25e3%2583%258d%25e3%2582%25b8%25e3%2583%25a1%25e3%2583%25b3%25e3%2583%2588%2Fsite.html

See also: Percent-encoding

Related API calls

These are the API calls you will typically make before you use the rules API:

Before rules API Use case
Containers API The use case for the containers API depends on which data ingest method you are using to transfer your data into the Oracle Data Cloud platform (online ingest, offline onboard, user data API, or mobile ingest):
  • Online ingest: Create a container to extract page and user attributes and transfer them to the platform for classification.
  • Offline onboard and user data API: Create a container to pass your unique user IDs (UUIDs) to the platform via an ID swap. Once a user has been ID swapped, their offline or server-side attributes can be transferred to the platform for classification.
  • Mobile ingest: Retrieve your site ID and insert it into the Oracle Data Cloud mobile core tag. The mobile core tag is used to extract page and user attributes from your mobile web pages and mobile apps and transfer them to the platform for classification.
Categories API Add first-party categories to your private taxonomy.

These are the API calls you will typically make after you use the taxonomy rule chains API:

After rules API Use case
Audiences API Create a target audience that includes your self-classified first-party categories.
Categories API View your categories and their inventory.

GET response summary

The taxonomy rule chains API GET request returns the rules used to map your categories with your site and offline data. Here are the properties included for each rule:

Property Type Description
status enum The current status of the rule chain: "active", "draft", or "flagged".
rules array A list of rules in the rule chain. The properties listed below belong to the Rules object.
- status enum The current status of the rule: "active", "draft", or "flagged".
- taxonomyRuleOperatorParams array A list of key-value pairs in the rule. For example:

{ "name": "key", "value": "one-changed" }, { "name": "value1", "value": "1" },
- note string Any user-specified notes related to the rule.
- taxonomyRuleOperator object Specifies the logic used to evaluate the phints in the taxonomyRuleOperatorParams object. This includes the id, name, and description of the operator, which may be one of the following values:

idnamedescription
1==is
2[]range
3_*starts-with
4*_ends-with
5*_*contains
6>greater than
7<less than
8>=greater than or equal
9<=less than or equal
10>,<greater than + less than
11>,<=greater than +less than or equal
12>=,<greater than or equal + less than
13>=,<=greater than or equal + less than or equal


createdAt string A GMT time stamp indicating when the rule chain was created (YYYY-MM-DDTHH:MM:SS+0000).
updatedAt string A GMT time stamp indicating when the rule chain was last updated (YYYY-MM-DDTHH:MM:SS+0000).
id int The unique ID generated for the rule chain. You will need this ID to update the rule chain via a PUT request.
categories object The category (id and name) for which the rule chain is applicable.
sites int A comma-separated list of the site IDs/containers for which the rule is applicable.

If the rule is applicable to all site IDs, the list is empty and the partner ID appears in the partners list.
partners int If the rule is applicable to all site IDs, your partner ID appears in this list.

If the rule is applicable to only one or more site IDs, this parameter is empty, and the site IDs are included in the sites list.

POST response errors

If the POST request for creating categories fails, the POST response will use one of the following codes:

Code Error message Description
400 Bad Request The body of the POST response will contain short description of the problems with the POST request.
401 Unauthorized You need to authenticate the request. See authentication and authorization for more information.
403 Forbidden You have reached the maximum number of categories (by default, the limit is 100).
404 Not Found The specified parent category is either not in your taxonomy or is not in your Partner seat

The body of the POST response will contain a list of error codes for each of the input attributes causing the error, which are as follows:

Code Description
BK-10001 Could not find resource for the specified path
BK-10002 Bad query parameters
BK-10003 Invalid JSON input
BK-10004 Input JSON does not pass schema validation
BK-10005 Input JSON contain bad property
BK-10006 Input JSON has missing properties
BK-10007 Input JSON has bad property that does not match min length requirement
BK-10008 Input JSON has bad property that does not match max length requirement
BK-10009 Not enough privileges to access requested resource
BK-10010 The request could not be completed by the service due to malformed data or syntax
BK-10011 Incorrect sorting parameter
BK-10012 Additional properties detected. Schema does not allow extra properties to be present
BK-26001 Taxonomy rule chain was not found

Related

Categories API

Taxonomy Manager

Percent-encoding