The SFTP Connection enables BlueConic to exchange data with SFTP servers using delimited flat files (e.g., CSV, .csv.gz). By importing or exporting customer profile, group, and Timeline event data, the connection helps synchronize marketing data between BlueConic and external platforms.
Connection details:
Goal types: Import and export (Profiles, Groups, Timeline events)
Frequency: Batch (scheduled or manual)
Use the SFTP Connection to:
Import group data (households, companies, accounts, etc.).
Import and export customer profiles to keep systems synchronized.
Import and export events (e.g., orders).
Apply data processors to transform or filter CSV data.
Use PGP encryption for secure file transfers.
Exchange marketing lifecycle data for orchestration and targeting
Before you begin
Confirm access to an SFTP server (with hostname, port, and directory path).
Retrieve your authentication credentials: username ,password, private key, or multifactor authentication setup.
(Optional) PGP keys if you plan to use encrypted file transfers.
Plan for the CSV file format and data fields you’ll import or export.
Create a SFTP Connection
Click Connections > Add Connection.
Search or select the SFTP Connection from the pop-up window.
Enter the name and metadata details for the connection.You can expand metadata (favorite, labels, description, edit rights) by clicking the gray chevron at the top of the page.
Click Save.
Authenticate
On the Set up and run page, enter your authentication credentials; SFTP server, Port (usually, this value is 22) and username.
Choose an authentication method:
a. Password (enter password).b. Private key (upload or drag-and-drop).
c. Multi-factor (password + private key).
(Optional) Check Use PGP encryption for SFTP file transfers. A settings menu appears. Enter the Private key (for decrypting files), Public key (for encrypting files), and optionally a Passphrase.
(Optional) Specify the SFTP user directory under advanced settings. Enter the user home directory on the SFTP server, a path relative to the root where the user is restricted. Depending on your setup, you may need the correct path for BlueConic to read or write files properly.
Click Save.
Note: BlueConic supports private key authentication for SFTP connections but does not generate SSH keys. If you don’t already have an SSH key pair, reach out to your IT team. Supported private key formats include: ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa, and ssh-dss
Configure the import
Generate the profile import goal
Select the Import profiles into BlueConic goal.
(Optional) Edit the name to describe your import. Click away and the name will update.
Select a domain group for the import to ensure that the correct profiles are updated or added. Note: This setting is visible only when additional domain groups exist beyond the default.
1. Select SFTP source files to be imported
Select the SFTP source files to be imported. Select the directory that contains your source files for the import. All files for import must be in the same directory.
A lightbox opens showing file columns and sample data.
Use the Connect icon (+) to link related files and to choose how data in CSV columns should be linked together. For example, you might match customer profiles in the profiles file with the products file using matching order IDs.
Click Save.
Note: The name of the root file (Orders.csv in the example shown below) must be unique. The root file cannot have the same filename as the files linked to it, or the files will not be imported. You can also use regular expressions or wildcards to choose the files.
2. Correct your files before the import
(Optional) Add one or more Data Processors to transform or filter the data in your CSV file, to ensure that BlueConic imports the data correctly.
Once select it you can configure it's settings via the cog wheel icon.
Click Save.
Tip: You can use a Data Processor to normalize email addresses, filter data fields, or transform data during the import, before it is matched and mapped to BlueConic properties.
3. Define file and field handling
Customize how your CSV files and fields should be handled during the import:
a. Field separator: specify how the files' fields should be handled by entering a field separator. This is usually ',', ';', or '\t' (for tab-separated files).b. Decimal separator: Select the character that is used as a decimal separator within your files (the symbol used to separate the integer part from the fractional part of a number).
Click Show advanced settings to configure settings such as the date format for the time stamp for data exports:
Multi-value separator: Enter the character(s) used as a separator between multiple values within a single field. This is typically ',' or '|'.
Quote character: If your CSV file uses quotation marks around quotes, you need to specify your quote character here. If your CSV does not use quotation marks, you can remove the default character.
Escape character: If your CSV file uses escape character, you need to specify your escape character here. If your CSV does not use escape character, you can remove the default character.
Date format: Specify the date format used in the files so BlueConic can import these fields correctly.
Automatically detect date format: The system automatically determines the date.
Set a custom date format: For example: the format "YYYY-MM-DD" results in "2019-11-30".
Rename files: Enabling this setting will add a ".done" suffix to the end of the file name when the file is imported.
Delta file: Select whether the file being imported is a delta file, containing only the data that’s been updated since the last import. Otherwise, BlueConic will check the data and import only the updated data. This helps to optimize the import speed.
4. Link identifiers between SFTP files and BlueConic profiles
Click Add identifier and select the BlueConic profile property that serves as the unique identifier for the matching profiles.
This should be a field that exists in both systems (for example, email address, CRM ID, or loyalty ID).
(Optional) check Allow the creation of new profiles if you want BlueConic to create new profiles when no match is found for the selected identifier. If unchecked, only existing profiles will be updated.
Click Save.
Note: Profiles without a value for the chosen identifier will be excluded from the import/export. Data without matching identifiers will not be linked to profiles.
5. Map SFTP data to BlueConic profile properties
1. Click Add mapping to select the BlueConic data to map.
2. Select a data field from the drop-down list, and select the BlueConic profile property it populates by entering a search term.
3. (Optional) Use bulk mapping by selecting Add all detected fields. This also allows you to set a merge rule for these fields simultaneously.
4. (Optional) Add a prefix to the BlueConic properties. If you set the prefix and then add an empty mapping, the right side automatically adds the prefix as well.
5. Select how to import the data from the drop-down menu on the right of each property:
Set: Always overwrite the profile property value in BlueConic.
Set if empty: Import the value in BlueConic only if the profile property does not contain a value yet.
Set or clear: Clear the value in the profile property if the CSV contains no value for the field.
Add: Add the imported value to the list of values for the profile property. The list will only contain unique values, doubles are not imported.
Sum: Numerically add the imported value to the value of the profile property in BlueConic. If the profile property was empty, it will be treated as 0. If the imported value is not a number, it is not imported.
6. (Optional) Import Timeline events into BlueConic
Click Add a Timeline event type.
Choose the default Order event type, or select a custom Timeline event type you created with a plugin XML file .
Map order details in the left column with order event properties, event date/time, and the event ID.
Use the checkbox to say whether order event details should be added to a Product store, which collects data to feed product recommendations.
Click Add mapping to link additional nested Order event details, such as additional products. If many fields are detected, select Add all event properties for faster setup.
Click Save.
For details on how Timeline events work in BlueConic, see Timeline Events Overview.
Generate the group import goal
Click Add goal and select Import groups into BlueConic. This allows you to import data into BlueConic groups, such as households, accounts, companies,
(Optional) Edit the name to describe your import. Click away and the name will update.
Click Save.
1. Select a group type
Select a group type to import to; Households, Accounts, Companies.
Use the drop-down menu to select from the group types defined for your BlueConic tenant.
Click Save.
2. Select SFTP source files to be imported
Select the directory that holds your import files, or navigate the file structure.
A lightbox opens showing file columns and sample data.
(Optional) Specify files using wildcards or regex.
Click Save.
Note: If you use a wildcard, make sure the value of that wildcard matches your root file and all nested files. For instance, if example_course_20*.csv is used for your root file, and this results in example_course_20244.csv being selected, then your nested files must contain the wildcard value of 244 in their filenames to avoid an error.
3. Correct your files before the import
(Optional) Add one or more Data Processors to transform or filter the data in your CSV file, to ensure that BlueConic imports the data correctly.
Once selected you can configure it's settings via the cog wheel icon.
4. Define file and field handling
Customize how your CSV files and fields should be handled during the import:
a. Field separator: specify how the files' fields should be handled by entering a field separator. This is usually ',', ';', or '\t' (for tab-separated files).b. Decimal separator: Select the character that is used as a decimal separator within your files (the symbol used to separate the integer part from the fractional part of a number).
Click Show advanced settings to configure settings such as the date format for the time stamp for data exports:
Multi-value separator: Enter the character(s) used as a separator between multiple values within a single field. This is typically ',' or '|'.
Quote character: If your CSV file uses quotation marks around quotes, you need to specify your quote character here. If your CSV does not use quotation marks, you can remove the default character.
Escape character: If your CSV file uses escape character, you need to specify your escape character here. If your CSV does not use escape character, you can remove the default character.
Date format: Specify the date format used in the files so BlueConic can import these fields correctly.
Automatically detect date format: The system automatically determines the date.
Set a custom date format: For example: the format "YYYY-MM-DD" results in "2019-11-30".
Rename files: Enabling this setting will add a ".done" suffix to the end of the file name when the file is imported.
Delta file: Select whether the file being imported is a delta file, containing only the data that’s been updated since the last import. Otherwise, BlueConic will check the data and import only the updated data. This helps to optimize the import speed.
5. Link identifiers between SFTP files and BlueConic groups
Choose the BlueConic group property that serves as a unique identifier and link it to the corresponding SFTP field.
6. Map imported fields to BlueConic group properties
Click Add mapping.
Select an SFTP data field and the BlueConic group property it should populate.
(Optional) Use Bulk mapping to add all detected fields at once.
(Optional) Add a prefix to BlueConic properties for easier organization.
Configure the export
Generate a Profile or Event Export goal
Select the Export profiles from BlueConic goal.
Edit the name to describe your export.
Click away and the name will update.
Click Save.
1. Select the BlueConic segment to export profile data from
Click Select segment and select or search for your desired segment.
(Optional) check Export all profiles (including unchanged profiles) if you want to export all profiles in the selected segment each run instead of only exporting the changed profiles. Note: This increases your run time.
2. Select and SFTP directory to export to
Select a directory for the exported files.
A lightbox opens showing file columns and sample data.
Click Save.
3. Define file and field handling
Specify how to set up your export files and their fields.
Choose how BlueConic names your export files:
Segment name and timestamp: Creates a new file for every export run.
Custom name (replaces file every run): Overwrites the same file each time the export runs.Use the segment name and timestamp option to maintain historical files. Use a custom name when you only need the latest file version.
Field separator: specify how the files' fields should be handled by entering a field separator. This is usually ',', ';', or '\t' (for tab-separated files).
Decimal separator: Select the character that is used as a decimal separator within your files (the symbol used to separate the integer part from the fractional part of a number).
Click Show advanced settings to configure settings such as the date format for the time stamp for data exports:
Multi-value separator: Enter the character used to separate multiple values within a single field (commonly , or |).
Quote character: Specify the character used for quoted values (default is ").
ID replacement: Select Replace BlueConic IDs with name if you want the file to display profile or group names instead of internal BlueConic IDs.
File compression: Select gzip file to compress the exported file into a .gz format.
Date format: Choose how dates appear in the exported file:
a. Timestamp (Default): Exports numeric timestamps.
b. Set a custom date format: Exports humna-readable dates (for example yyyy-MM-dd HH:mm).Timezone: Select the timezone that matches your data (for example, Europe/Amsterdam). Click Preview date and time to confirm that the displayed date format appears as expected.
Tip: If your exports show raw timestamps instead of readable date and time values, select Set a custom date format to control the format used.
4. (Optional) Modify your data before the export.
Add one or more Data Processors to transform or filter your profile or event data, to ensure that BlueConic exports the data correctly.
5. Map BlueConic data to SFTP
Click Add mapping to select the BlueConic data to map.
Select the BlueConic icon to open a drop-down menu.
Select the type(s) of information to match and export:
Profile property: The value of a specific profile property.
BlueConic profile identifier: The unique identifier for a profile.
Associated segments: All segments, or a selection of one or more specific segments that the profile is associated with.
Associated lifecycles: All lifecycles this profile is associated with.
All viewed interactions (all time): The interactions that the profile has seen.
Permission level: The permission level set in the profile.
Text value: Enter any static text.
Click Save.
6. (Optional) Export Timeline events to SFTP
Choose whether to export Timeline events for profiles in the segment.
Select All event types or a specific event type.
Select the time period (all time, last X days, or next X days).
Note: BlueConic creates a separate CSV for each event type (e.g., order.csv)
If there are nested events (for example, products), BlueConic creates additional CSV files in the same directory for each nested event.
7. (Optional) Create BlueConic events for exported profiles
If this goal is part of a BlueConic Lifecycle, this step will appear.
Check the Add Lifecycle event box to count each exported profile as a “plus one” toward the Lifecycle stage threshold.
Leave the box unchecked if you do not want this export to count toward the threshold.
Run the connection
Activate the goal
Check the goal you want to activate. We recommend testing import and export goals separately.
The green arrow indicates the active direction for the connection.
Click Save.
Tip: Reorder goals by dragging the handle on each goal card to set run order.
Run Manually
To run the connection:
Turn the connection On.
Click Save.
On the Set up and run page, scroll to the Run history section.
Click Run now to run all activated goals in the connection manually.
The run appears at the top of the table.
Run on a Schedule
Click the Settings icon.
Choose an option from the drop-down list to configure by:
Number of times per day
Days of the week
Days of the month
Weekday of the month
Select the time of day if required.
Click OK.
Click Save.
Confirm data exchanged successfully
See the total number of unique profiles imported or exported via the connection under Data exchange.
Use SFTP Connections with BlueConic Lifecycles
You can add SFTP export goals as touchpoints in BlueConic Lifecycles. Here are some key points to consider:
Exporting Lifecycle stage information to SFTP: When you add a SFTP export goal to a BlueConic Lifecycle, you can use that export goal to send a list of profiles that attain a certain lifecycle stage along their customer journeys and use this information for campaigns.
Setting Lifecycle stage restrictions: You can restrict a connection goal to export only the profiles that are currently part of a certain lifecycle stage.
Setting thresholds on marketing touchpoints: You can use lifecycle stage thresholds to limit campaign pressure on customer profiles in a certain lifecycle stage. For example, you can make sure a customer is exposed to only 3 marketing touchpoints per week, per month, or per quarter during a particular stage on their customer journey. The SFTP connection can now counts towards the threshold.
Next steps
Create and activate as many import and export goals as needed within this connection.
Add this connection an Objective (as needed), allowing for privacy management of the information that is being picked up.
FAQ
Why doesn’t my SFTP export include all profiles from my segment?
If your SFTP Connection doesn’t export the full set of profiles even when the segment and mapping are correct, the issue may be caused by having too many goals in the same connection. Running multiple goals in parallel can prevent large exports from completing. To resolve this, try running the export in a copy of that connection with only that goal. If the export succeeds, you can keep it isolated or restructure your goals across multiple connections for stability.
How does selecting PGP encryption affect the connection setup process?
When you enable PGP encryption, files will be encrypted securely, so you may notice several subtle changes to the connection setup process:
Source preview files will not be available.
Fields for the mappings will not be found.
Bulk mapping will not be available.
You cannot prefill mappings in the import and export goals.
If you prefer to use the bulk mapping feature or field selection feature, you can set up the import and export goals first using a file with identical fields that is not encrypted, before you enable PGP encryption, so mappings are found and filled more easily.