How to Configure Managed Uploads in Piano Audience

Introduction

The User Profile Data Import (Managed Uploads) feature in Piano Audience enables you to upload user profile attributes from external storage directly into the platform. This is the recommended approach for onboarding first-party data. Once imported, these attributes are available for building audience segments in the Segment Builder and activating them across channels, including Composer integrations.

Prerequisites

Access Requirements

Before beginning setup, confirm the following access conditions are met:

• You have access to Audience → Connectivity → Configurations → User Profile Data Import.

• You have administrative access to Account Management → Data Sources in order to create a Data Source.

• All user profile attributes you intend to import have been created in advance via Integration Designer. Imports will silently skip any attributes that do not already exist in the system.

• Your external storage solution Amazon S3 has granted Piano the necessary read permissions, and write permissions if post-processing options (move, delete, rename) will be used.

• The User ID prefixes stored in your files match the prefix configuration in Piano Audience.

File Format Requirements

• Supported formats: CSV or TSV

• Encoding: UTF-8 (required)

• Files may optionally be compressed.

• Files must include a User ID column that matches the prefix type configured in the connection.

• Column headers must match the property names defined in the linked Data Source.

  Example:

  

File & Folder Naming Restrictions

• Maximum name length: 250 characters for both files and folders.

• Prohibited characters:

  # % & { } \ < > * ? / $ ! ' " @ + ` | =

• Allowed delimiters in dynamic name structures: _, -, :, <space>, .

Step 1: Review & Create Attributes in Integration Designer

All attributes you intend to import must exist in Piano Audience before the import runs. Attributes are created and managed in the Integration Designer.

1. Navigate to Integration Designer within Piano Audience.

2. Review the list of existing attributes to identify which ones are already available.

3. For any attribute not yet created, create it now with the correct data type and label.

4. Note the exact attribute names, you will need them when mapping properties in the Data Sources.

Step 2: Create a Data Source

A Data Source defines the structure of your import file and maps each column to the corresponding User Profile attribute in Piano Audience. Data Sources act as the meta layer connecting your external file schema to internal attributes.

1. Navigate to Account Management → Data Sources (administrator access required).

2. Click Create.

   

3. Set the Usage parameter to User profile data import. This is required for the Data Source to appear as a linkable option in the import connection.

Configure File Header & Delimiter

• Indicate whether your file includes a header row (recommended: Yes).

• Select the appropriate delimiter — comma for CSV, tab for TSV.

  

Map Properties to User Profile Attributes

Properties are the intermediary objects that bridge your file's columns to existing User Profile attributes in Audience.

1. Use drag-and-drop auto-mapping where column names match attribute names exactly. Manually link any remaining columns using the Mapped to selector.

2. For the column containing the User ID, switch the mapping to the internal property User ID.

3. Ensure every column you wish to import is mapped. Unmapped columns will be ignored during import.

You can find a demo walkthrough video below:

[video width="960" height="544" mp4="https://docs.piano.io/wp-content/uploads/2026/03/Screen-Recording-2025-10-30-at-09.18.21.mp4"][/video]

Step 3: Create the Import Connection

The import connection defines where Piano Audience retrieves your files, how to find them, and when to run the import.

1. Navigate to Audience →

   Connectivity → Configurations → User Profile Data Import.

   

2. Click Configure.

3. Select S3 as your storage type and provide the required credentials. Example:

   

4. Click Test connection and wait for a positive result before proceeding.

Configure Import Folder

• Use Name if your folder has a fixed, static path.

• Use Name structure if the folder name is dynamically generated — for example, based on a date or customer name. Configure name structures using static text components, customizable elements (such as date tokens), and the allowed delimiters listed in Section 2.3.

Configure Import File Name

• Select the File type: CSV or TSV.

• Indicate whether the file is compressed.

• Use Name for a static file name, or Name structure for a dynamically named file.

  

Link Data Source & User ID Type

• Select the Data Source created in Step 2. This tells the import connection how to parse and map columns from your file.

• Select the User ID type (prefix). This prefix will be matched against the User ID values already stored in Piano Audience for that prefix type. Ensure it matches what is present in your import file.

  

Configure Post-Processing

Post-processing controls what happens to your import files after they have been successfully processed. This helps prevent duplicate imports and keeps your storage organized.

Recommendation: Use Rename or Move to folder as a safeguard against re-importing the same file in subsequent runs.

Set Import Frequency

Step 4: Activate the Connection

1. Toggle the activation switch to On.

   

2. Click Create (for new connections) or Save (for edits).

Step 5: Enable Attributes in the Segment Builder

After a successful import, newly ingested attributes may not appear immediately in the Segment Builder. This is expected behavior.

Attributes are only surfaced in the Segment Builder once destinations have been enabled in the Composer connector. To make imported attributes available for segmentation:

1. Navigate to your Composer connector settings within Piano Audience.

2. Enable the relevant destinations for the attributes you have imported.

3. Once destinations are enabled, all imported attributes will become available for use in segment conditions.

Monitoring: History & Errors

Piano Audience provides two tabs for monitoring the status of your import connections:

• History tab: Displays a summary of each import run, including the number of rows successfully processed and the number of rows discarded. Rows may be discarded due to empty values, incorrect data formatting, or mismatched User ID prefixes.

• Errors tab: Displays errors that prevented an import from executing at all. Common error causes include expired storage tokens, regenerated API keys, and deleted or renamed folders that the connection can no longer locate.

Recommendation: Review both tabs after the first import run and on a recurring basis, especially following any changes to your storage environment or credentials.

Best Practices

• Create all attributes in Integration Designer before running any imports. Attributes that do not exist at the time of import will be silently skipped, there is no error or warning for missing attributes.

• Always use UTF-8 encoding. Files encoded in other formats may cause character corruption or import failures.

• Validate User ID prefix alignment across your file, Data Source configuration, and Piano Audience connection settings before the first run.

• Use the Test Connection feature every time you create or modify a connection. Do not activate a connection until the test returns a positive result.

• Schedule imports after your upstream export pipeline completes. Use the "Start import after" time setting with an appropriate buffer to account for pipeline variability.

• Implement a post-processing strategy (rename, move, or delete) to prevent the same file from being imported multiple times across recurring runs.

• Enable Composer connector destinations immediately after your first import if you intend to use the imported attributes in the Segment Builder.

• Monitor the History and Errors tabs regularly, particularly after storage credential rotations, infrastructure changes, or file naming convention updates.

• Use name structures for dynamic file and folder paths rather than relying on manual updates to static names, especially in automated pipelines that include date-stamped output paths.

Troubleshooting

Last updated: June 24, 2026