Update a Customer Dataset via SFTP

This content is only for clients with Product Data and Customer Data options in the DATASETS menu in the top navigation bar. If no menu options appear when you click DATASETS, then this content doesn't apply to your account. Instead, see the alternate version of this documentation.

Data onboarding allows you to upload offline data about your customers to the platform as a customer dataset. The automatic updates feature lets you regularly deliver full or partial file updates over SFTP to the platform, which automatically checks for, processes, and updates the datasets and any associated experiences.

How Automatic Updates Work

Any current dataset created with the Datasets Upload wizard is assigned a dataset ID. This ID is used in the filename of the update to match it to an existing dataset. Once you upload a file to Monetate's SFTP server, it automatically updates the dataset and all associated experiences.

If the update failed, you'll see an alert in the Current Updates column on the Customer Datasets list page.

Callout of the 'Current Updates' column on the Customer Datasets list page

You can perform two types of updates for a customer dataset:

  • Full update: Replaces the entire dataset with the next successfully processed full file that the platform ingests
  • Partial update: Adds rows or updates rows with the next successfully processed partial file that the platform ingests

You cannot add columns, also called attributes or fields, to a dataset through a partial update sent via SFTP. See Update or Replace a Customer Dataset for the steps to add attributes using the Datasets Upload wizard.

In addition to CSV and TSV files, you can upload Gzip (.gz) and ZIP (.zip) files via SFTP.

You can only use the .gz file extension for a Gzip file. Monetate doesn't accept files with the .gzip file extension.

Any full or partial updates that are older than the most recent full file update are archived. You can access these files from the Update History modal that you open from the additional actions menu on the dataset's details page.

The Upload History modal

Monetate periodically cleans up the history folder. However, all files remain archived for a minimum of 24 hours.

Setting Up Automatic Updates

To set up automatic updates, add the following information to your SFTP client:

  • Host: https://sftp.monetate.net
  • Port: 22
  • Protocol: SFTP

The username(s) you can find within Monetate by selecting Sites from the settings menu in the platform.

Callout of the Sites option in the platform settings menu

From that same page you can create new SFTP credentials or change an existing SFTP user password. See Manage SFTP Users for more information.

You must have the Administrator role in Monetate to set up SFTP users in the platform settings.

File-Drop Directories and Naming Conventions

There are two file-drop directories:

  • /datasets/partial — Use this location for partial file updates
  • /datasets/full — Use this location for full file updates

Follow this format when naming an update file: {datasetid}-examplefilename.csv.

Replace {datasetid} with the dataset's specific ID. You can find this information in the platform by following these steps:

  1. Click DATASETS in the top navigation bar, and then select Customer Data.
  2. Find the dataset you want to update on the Customer Datasets list page, and then place the mouse pointer in the upper-right corner of the dataset's tile to reveal the additional options menu.

    The additional actions menu for a customer dataset on the Customer Datasets list page

  3. Click Manage Auto Updates to open the Configure Automatic Updates (SFTP) modal.

    The 'Configure Automatic Updates (SFTP)' modal

The numeric prefix that appears in the SFTP Directories table is the dataset ID you use in place of {datasetid} in the filename.

Callout of the dataset ID listed in the 'Configure Automatic Updates (SFTP)' modal

You must use a hyphen (–) between the dataset ID and the filename. The upload or update will fail if the dataset ID and filename are not separated by a hyphen.

You can change the portion of the filename that follows the hyphen from update to update. However, you cannot change the dataset ID.

If you want to update an existing dataset without adding new columns, you can optionally exclude the header row from the file. Add NOHEADER to the end of the filename ({datasetid}-filename_NOHEADER.csv) to indicate that the file doesn't contain a header row.

If you exclude a header row from a dataset update, ensure the columns in the file match the order of the columns in the existing dataset. If the columns are not in the same order, the platform cannot matched them up with the corresponding columns in the dataset.

Receiving Notifications for Automated Updates

You can receive an email notification every time a file successfully uploads via SFTP as well as a notification every time an error occurs during the upload process. Follow these steps to enable one or both notifications.

  1. Click the settings cog, select Users, and then click the user account for which you want to enable notifications.
  2. Enable one or both SFTP-related email notifications.

    Callout of the 'Receive Dataset SFTP Error email notifications' setting and the 'Receive Dataset SFTP Success email notifications' setting for an individual Monetate user on the Users page of the platform settings

  3. Click Save.

    Callout of the SAVE button for an individual Monetate user's settings on the Users page of the platform settings

If you have questions, see the FAQ or submit a support ticket using the Monetate Technical Support portal (support.monetate.com).

Related Articles