Update a Customer Attributes Dataset via SFTP

This content is only for clients with the one-click DATASETS option in the top navigation bar. If you click DATASETS and see Product Data and Customer Data listed as menu options, 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 Attributes dataset. The automatic updates feature lets you regularly deliver full or partial file updates over SFTP to Monetate, which automatically checks for, processes, and updates the datasets and any associated experiences.

How Automatic Updates Work

Any current dataset created with the platform's Create Dataset Schema 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 the platform’s SFTP server, it automatically updates the dataset and all associated experiences.

If the update failed, you'll see an alert on the dataset's entry on the Customer Attributes view of the Datasets list page.

Callout of an 'UPDATE FAILED' message on the Customer Attributes list page

You can perform two types of updates for a Customer Attributes 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 Customer Attributes Dataset Details Page for information on the Add Attributes modal accessible from a dataset's details page. This modal allows you to add attributes to the dataset's schema without uploading a file.

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. While Monetate does periodically clean up the history folder, all files remain archived for a minimum of 24 hours.

You can also access these files on the Update History tab on the dataset's details page in the Monetate platform.

Monetate retains dataset files for 180 days from the date it was uploaded. Once a file is out of this retention period, it still appears on the dataset's Update History tab, but you cannot download it.

The 'Upload History' tab of a Customer Attributes dataset's details page. Two files were uploaded via SFTP.

If a file is available for download, its filename appears in purple in the Update History table.

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 the platform by selecting Sites from the settings cog 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 unique ID for the dataset you are updating. You can find this information in the platform by following these steps:

  1. Click DATASETS in the top navigation bar, and then select Customer Attributes from View on the Datasets list page.

    Callout of the View selector on the Datasets list page. One of the options is Customer Attributes.

  2. Find the Customer Attributes dataset that you want to update, click the upload icon for its entry, and then select SFTP Info.

    Callout of the upload icon and the SFTP Info option for a dataset entry on the Customer Attributes view of the Datasets list page

  3. Scroll to the bottom of the modal to find the dataset ID, and then copy it to add it to the dataset's filename.

    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.

    Callout of the dataset ID, which is a required prefix that must be included in a Customer Attributes dataset filename, listed on the 'SFTP Info for Updating' modal

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 match 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