Configuration API
- Sylvain Paillard
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: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/393380
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 configurationupload
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
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: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/8749643
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 | |
|---|---|---|
| 1 | campaign | Marketing Campaigns as configured in the menu Marketing > Campaigns and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/1409312 |
| 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: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/316866589 |
| 4 | data-enrichment | Data Enrichment as configured in the menu Data > Data Enrichment and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/316833797 |
| 5 | data-owner | Data Owners as configured in the menu Data > Data Owners and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/316833825 |
| 6 | facet * | Facets as configured in the menu Merchandising > Facets and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/8716345 |
| 7 | heuristic | Heuristics (domain business rules) as configured in the menu Merchandising > Heuristics and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/305628345 |
| 8 | layout-block * | Layout Blocks as configured in the menu Marketing > Layout Block and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/8618382 |
| 9 | narrative * | Narratives as configured in the menu Marketing > Narratives and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/8749189 |
| 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: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/8617985 |
| 12 | segment * | Segments as configured in Merchandising > Segments and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/305595224 |
| 13 | response * | Responses as configured in the menu Merchandising > Response and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/310051068 |
| 14 | taxonomy | Taxonomy (new fields and labelled fields) as configured in the menu Data > Taxonomy and as documented here: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/316833844 |
| 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 | |
|---|---|---|
| 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) |
|
|---|---|
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.
Request
The request, as below is fully built on the elements described in the prior section:
Response
The response includes the versionId and status as well as the lastModification of any of the returned records.
It then provides the actual records grouped by Record Type.
upload
This service provides you a way to change the configuration of an account based on what you are providing in the data property.
Request
The request, as below is fully built on the elements described in the prior section:
Response
The response includes the information about the version id which was affected by the upload, the current dev (currently unpublished) version id as well as the current prod (currently live) version id.
It then provides the records information of what was skipped and did not update anything in the account configuration (with the explanation in the “message” parameter as below:
transfer
This service lets you copy configuration content from one account (source) to another account (target).
Request
The request, as below is fully built on the elements described in the prior section:
Response
The response includes the information about the version id which was affected by the transfer, the current dev (currently unpublished) version id as well as the current prod (currently live) version id.
It then provides the records information of what was skipped and did not update anything in the account configuration (with the explanation in the “message” parameter as below: