Enrichments

General definition

Enrichments are tables containing properties that feed Piano Analytics.
They consist of a property used as a key and associated properties that can be fed with specific values as soon as a key is detected in the data.

Example

If the data sent in the hits contains the product_id:123456, you will be able to query the other properties and obtain the corresponding values for this identifier via the other columns of your enrichment.

Access

Access rights

Enrichments can only be defined and edited by the following users:

• Administrators

• Data Supervisors

Location

You can access Enrichments by going to Data Management > Enrichment (left side menu).

Dashboard

As soon as your organisation has at least one enrichment, you will see the list of enrichments from the dedicated dashboard.

Here you will find for each enrichment :

• The name of the enrichment

• The template category used

• The property used as a key for the enrichment

• The date the enrichment was created

• The status of the last update by API

• The status of the last update by CSV

• The retroactive configuration (on Retroactive and Retroactive (former) imports)

Types of Enrichments

Enrichments are always composed of a 1 key property / x associated properties structure.
These associated properties can vary according to the type of enrichment.

Scope

The associated properties must be of the same scope (visit, page view, or event) as the key property.

The type of enrichment also corresponds to a specific supply of associated properties.

 Standard

Definition

The Standard enrichment is used to feed Piano properties and custom properties. 
The values entered in the associated properties for a key feed the associated properties for any new (validated) event received once the value of the key and the associated property(ies) are configured in the import.
If there is no associated property value for a key value, the property can be fed with the content of a parameter tag collected in a hit.

Options

Enrichments are only available if at least one of your organisation's contracts has the Standard Enrichments option activated.
To benefit from this option, please contact our support centre.

Retroactive

Definition

The Retroactive enrichment is used to populate dedicated custom properties.
The values entered by import in the enrichment will be applied to any validated event (past/present/future).
These associated properties will only be fed by the values entered in the import (they cannot be fed by hits if the import line is empty).

Options

Enrichments are only available if at least one of your organisation's contracts has Standard and Retroactive Enrichments activated.
To benefit from the options, please contact our support centre.

Retroactive (former)

Définition

The Retroactive Enrichment (former) allows you to populate Piano properties and custom properties. 
The values entered in the associated properties for a key feed the associated properties for any validated event (past/present/future) received once the value of the key and the associated property(ies) are configured in the import.
If there is no associated property value for a key value, the property can be fed with the content of a parameter tag collected in a hit.

Options

Enrichments are only available if at least one of your organisation's contracts has Standard and Retroactive Enrichments activated.
To benefit from the options, please contact our support centre.

Creation

In Data Management > Enrichment, you can click on the "Create an enrichment" button.

If you have the Retroactive Enrichment option, then you will be able to choose the type of enrichment you wish to set up.

If you only have the Standard Enrichment option, you will be taken directly to the Standard Enrichment creation form.

Creating a Standard Enrichment

You will need to fill in the configuration listed below.

Name

The name displayed in the Enrichments dashboard.

Template

3 categories of templates are currently available to create your enrichment:

• The properties available for enrichment using the Custom ID template must meet the following criteria: :

• Property type: STRING / INTEGER

• Property treatment: Processed

• Property status: Validated

• The property is not one of the following: event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid

Templates or a key properties that are greyed out in the lists represent those already used in another enrichment and therefore not available.

Case-sensitive key

You can choose to distinguish the keys in your enrichment between upper and lower case versions.

Example

If you select Yes, you will have two keys for values such as mykey and MyKey, choosing No would give you only one key.

Alerts

In the event of an API error when importing data, we can notify you by email of this error to the emails you would have entered in the dedicated field.
This field has a list to help you choose a user from your organisation, you can also enter an email address not associated with an Piano Analytics account.

Structure

Once you have filled in the previous parameters, you can click on the Next button and see the properties that you can use as columns.

In the Columns table, you will find all the properties proposed by the template you have selected.
The first row represents the property used as a key that cannot be changed or deleted.
The other rows can be deleted by clicking on the bin icon at the end of the row.

You can also add other columns by selecting them from the Select property list.

In this list of properties you will find properties that match all these criteria:

• Property status: Validated

• Property treatment: Processed

• ReadOnly: No (editing of property rules is available)

• Use in another enrichment : None (currently or previously)

• Some properties are prohibited, even if they meet these criteria, you can consult the list of standard prohibited properties below

Creating a Retroactive Enrichment

You will need to fill in the configuration listed below.

Name

The name displayed in the Enrichments dashboard.

Key

The key designates the property consulted by our enrichment system, once its value is brought up in a hit, the associated properties will be completed according to the data you import.

You can choose as a key any property that meets these criteria.

• Property type: STRING / INTEGER

• Property treatment: Processed

• Property status: Validated

• The property is not part of the following list:

event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid

Case-sensitive key

You can choose to distinguish keys in your enrichment between upper and lower case versions.

Example

If you select Yes, you will have two keys for values such as mykey and MyKey, choosing No would give you only one key.

Alerts

In the event of an API error when importing data, we can notify you by email of this error to the emails you would have entered in the dedicated field.
This field has a list to help you choose a user from your organisation, you can also enter an email address not associated with an Piano Analytics account.

Structure

Once the previous parameters have been filled in, you can click on the Next button and create the associated properties for this import.

You have 3 parameters to create these associated properties:

• Name: label for displaying the property in the interfaces

• Type : format of the property (string/integer/data/boolean/decimal/array string)

• Property key: the property key that will be used in processing and API calls

To add a new property, you must fill in the 3 parameters and validate it with the dedicated button at the end of the line. You can also cancel the property creation with the cross icon at the end of the line as long as the import structure has not been saved.

Once your properties are filled in, you can click on the save button at the bottom of the page.

Import data

Once your enrichment configuration is set up, you will need to add data to the table.
To do so you can rely on 3 different import types.

API

To use the API in order to mange imports, it is important to follow several rules:

• Mandatory POST method

• Presence of the header x-api-key 

• The body of the JSON should be correctly formatted

• Checks on the call parameters are made:

• {codeOrga} : present and in capital letters

• {importId} : present

You can read our dedicated article on how to retrieve an API key allowing you to use the API.

Once your API key has been retrieved, you can go to the enrichment interface, select the enrichment of your choice and access the Import Data tab. You can find in there the API to use with an example.
Please note the API import can only work for 1 key at a time.

sFTP

You can also rely on our sFTP to upload large files relying on the details of your import:

• Host

• Login

• Public key

• Folder

To create your sFTP key please refer to this documentation, please feel free to reach out to your tech teams to assist you on creating this key.

Please note that the engine expects a .csv or .csv.gz format to process the file.
You should also download the header to make sure to rely on the expected format.

CSV

When using a CSV file it is important to follow several rules:

• The separator to use is the comma

• The size of the import file cannot exceed 10 Mb

You should also download the header to make sure to rely on the expected format.

Note

To make sure the file format or encoding is not altered by any program, please edit the csv file we provide with the most neutral text editor (not Excel).

Which one should you use?

Summary

Once you imported data, you can see a preview of your table in the Reporting tab.

In this tab you can find:

• The number of lines of your import

• The status of your last API import

• The status of your last CSV import

• The history of your CSV imports with the status of all imports

• A short preview of the data held in your enrichment table based on your last imports

Edition

Configuration

You can update an enrichment by clicking on it or on its pencil icon in the Enrichment dashboard.
Below is a detailed view of the ability to edit the configuration of an enrichment.

Update data

It is possible to update your enrichment's data at any time by adding new keys.
And you can also update the values associated to an already existing key.

Change the associated data

The value of an associated property can be updated by importing the line of your table with all columns filled as you want your enrichment done (no partial update of a line). If you updated the associated value, new events with the key will be enriched with the latest values while former events will not be updated (unless you rely on retroactive imports as described earlier in this article).

Empty the associated data

You may want to delete the value associated to a key for a specific column in your enrichment.
While you cannot delete historical data, you can make sure new events with this key will not enrich the column through different methods.

API

If the property is not in the API call in <DATA>, the value stored in our catalog isn’t modified. 
If it was empty, it remains empty
If it was completed, the recorded value is not changed.

Example 

If we don’t want to specify the email however defined in the import structure

{ 
  "user_id": "12345", 
  "age": 35 
} 

To force the deletion of a value stored in the catalog, you must specify « null » 

{ 
  "user_id": "12345", 
  "email": null, 
  "age": 35 
} 

CSV

The line imported into the CSV will be used. If a value is empty in the CSV and in our database we had a value for this cell, it will clear the value and make it empty.

Example 

In the import we have

We import the following file

After the update we will have

Deletion

An enrichment cannot be deleted, if you do not want any new event to be enriched, you can update your enrichments to empty the values associated to your key.