What is the Configuration API?

The Configuration API enables you to change the content of Boxalino Winning Interactions Admin automatically without having to log into the admin and do manual changes.

In addition to changing the configuration data, the key actions of the Boxalino Winning Interactions Admin can also be triggered automatically, such as:

Duplicate Version (to create a duplicate of the current (unpublished) configuration version
Push Data (push all the data records, such as Campaigns and Content to be updated in the live platform)
Push to Test (update the test mode of the account so your stage environment is updated with the latest unpublished changes)
Publish (publish the current configuration version)

The Boxalino Winning Interactions Admin is fully documented here: Boxalino Winning Interactions Admin

End-points (URLs)

The End-point is always structured as follows:

POST https://intelligence-api.bx-cloud.com/api/v1/[SERVICE]

with:

SERVICE: the name of the available services

download
to download some of the current content of the configuration
upload
to upload and change the current content of the configuration with configuration data you have priorly downloaded with the download service (and have possibly modified)
transfer
to chain the download and the upload together without needing to download data and upload data from the server (particularly helpful when transferring between two different accounts)

Above: Example query with ARC (Advanced Rest Client) Chrome extension

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related

Before testing your integration with code, we recommend you test it with this extension to make sure it technically works.

Common elements to all services

Credentials

The credentials parameter include the account, the apiKey, and the apiSecret, required to authenticate your request.

{
  "credentials": {
    "account": "your_account",
    "apiKey": "your api key",
    "apiSecret": "your api secret"
  }
  //...
}

The Credentials information to provide are the same as the one needed for the Narrative API as documented here: Narrative API - Technical Reference

For the service “transfer” you will have two properties called “sourceCredentials” and “targetCredentials” instead of one called “credentials”. This is because you will typically use the transfer service to transfer the configuration from one account to another one and there need both sets of credentials to perform the operation.

Version

Boxalino Winning Interactions Admin is fully versioned. This means that every time you publish your account (or when you call for a duplicate action as documented below) a new version of your configuration will be created.

Typically, you will have the latest version (unpublished) with the status “dev” and the prior version which is live (published) with the status “prod” and all the prior versions with the status “archive”.

You can define both a “versionId” parameter in case you know which version you want to access (typically this will not be the case so you don’t have to set this value or can set it with the default value of 0).

Then, if you didn’t define a “versionId”, you must define a “versionStatus” parameter with the value “dev” or “prod”.

{
  //...
  "versionId": 0,
  "versionStatus": "dev"
  //...
}

Record Types

There are many different things that can be configured in Boxalino Winning Interactions Admin. Each of them is defined by a Record Type.

You can either indicate that you want all records by setting the parameter “allRecordTypes” to true.

Or you can define the ones you want in the parameter “recordTypes” as a list of strings.

{
  //...
  "allRecordTypes": false,
  "recordTypes": ["campaign"],
  //...
}

Here is a list of all the Record Types:

	Record Type	Description

	Record Type	Description
1	campaign	Marketing Campaigns as configured in the menu Marketing > Campaigns and as documented here: Campaigns
2	content	Headless Content as configured in the menu Data > Content
3	correlation	Data Correlations as configured in the menu Data > Data Correlations and as documented here: Data Correlations
4	data-enrichment	Data Enrichment as configured in the menu Data > Data Enrichment and as documented here: Data Enrichment
5	data-owner	Data Owners as configured in the menu Data > Data Owners and as documented here: Data Owners
6	facet *	Facets as configured in the menu Merchandising > Facets and as documented here: Facets
7	heuristic	Heuristics (domain business rules) as configured in the menu Merchandising > Heuristics and as documented here: Heuristics
8	layout-block *	Layout Blocks as configured in the menu Marketing > Layout Block and as documented here: Layout Block
9	narrative *	Narratives as configured in the menu Marketing > Narratives and as documented here: Narratives
10	request-rule	Request Rules (over-ruling of your request parameters for some widgets) as configured in the menu Merchandising > Request Rules
11	rule	Rules (curative business rules of the widget results) as configured in Merchandising > Rules and as documented here: Rules
12	segment *	Segments as configured in Merchandising > Segments and as documented here: Segments
13	response *	Responses as configured in the menu Merchandising > Response and as documented here: Response
14	taxonomy	Taxonomy (new fields and labelled fields) as configured in the menu Data > Taxonomy and as documented here: Taxonomy
15	template-resource *	Template Resources as configured in Advanced > Template Resources and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/305628423
16	widget *	Widgets as configured in the menu Strategies > Widget & Page Optimizers (main view of admin) and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/1376288

Record Ids

In addition to limiting the number of Record Types (see prior section), you can also limit a Download or a Transfer request to a list of record ids.

For Transfer requests : As ids are different in each account, the ids only refer to the ids of the source account and do not imply anything about the ids of the target account.

Merge mode

When you are uploading or transferring data, the question comes of what to do if these data already exist in the target version.

5 modes have been prepared to address different needs (from the most aggressive to the softest):

	Merge mode	description

	Merge mode	description
1	reset	deletes everything which was in this record type and replaces it with what you are loading (or transfering)
2	overwrite	adds everything which is not there and overwrite everything which was there already
3	overwriteIfNotOlder	adds everything which is not there and overwrite everything which was not changed after the last change of your uploaded (or transfered) records
4	overwriteIfNewer	adds everything which is not there and overwrite everything which was changed before the last change of your uploaded (or transfered) records
5	addIfMissing	adds everything which is not there but doesn’t update anything which was already there

Actions

You can also define some additional actions that should be taken (in addition to downloading, uploading, or transferring the configuration data)

Name (boolean properties, false by default)

Name (boolean properties, false by default)
createNewVersion	to create a duplicate of the current (unpublished) configuration version
pushData	push all the data records, such as Campaigns and Content to be updated in the live platform
pushToTest	update the test mode of the account so your stage environment is updated with the latest unpublished changes
publish	publish the current configuration version

download

This service provides you with the current content of the accounts for the records which are requested.