File Upload

Uploading data files into the platform is a foundational step for enabling event-based analytics. Whether you are integrating real-time user interactions or historical event records, it’s essential to format and structure your data correctly for a seamless upload and mapping experience. This article outlines everything you need to know before uploading a file, including technical requirements, recommended practices, supported file formats, and tips to help avoid common issues.

The file upload process enables you to ingest offline or batch data into the Analytics Store. This is particularly useful for onboarding historical data and testing event flows in non-production environments. Once a file is uploaded, the platform allows you to map its contents (For Example: timestamps, event names, user identifiers) to predefined schemas for consistent processing and analysis.

If you are using the Customer-State Analytics (CSA) for the second time or later, you can also reuse previously Saved Mappings during file upload. The platform lets you select from existing mappings, making the process faster and reducing repetitive configuration.

Key capabilities

• Supports both structured and compressed file formats

• Enforces standardized timestamp formats for time-based analysis

• Integrates with mapping tools to align data with business objects

• Prevents duplicate uploads to maintain data integrity

Upload Guardrails

To ensure a smooth and successful file upload experience, your data file must meet the following technical requirements:

• File Format: Only CSV and Parquet file types are supported. You may optionally compress your file using Gzip, which is compatible with both formats.

• File Size: Each file must be under 1GB. If your dataset exceeds this limit, we recommend splitting it into smaller chunks before uploading.

• Timestamp Format: Uploaded data files must include timestamps in ISO 8601 format. While including a time zone offset is optional, it is highly recommended, especially if your data originates from a non-UTC time zone. Without a time zone offset, Xponent will assume the timestamps are already in UTC. This may lead to inaccurate interpretations in visualizations such as heatmaps or journey timelines, particularly when analyzing user activity patterns across different regions.

  For Example: A valid timestamp would look like 2023-12-09T14:30:00-05:00. Files with timestamps in unsupported or ambiguous formats will be rejected.

  

  Xponent uses UTC as the default time zone across all components of the platform. All timestamps are automatically normalized to UTC during data processing.

• Required Fields: At a minimum, your file should include key fields such as event type, timestamp, channel, and a unique identifier like user_id or transaction_id.

• Column Headers: All columns must have defined, non-empty headers. Avoid duplicate or blank column names, as these can interfere with the mapping process.

File Upload

• Navigate to the Discovery page within the Analytics section. Click on the Import Data button located at the bottom-right corner of the page. This will open the Import Data page.

  If you are uploading data for the first time, the system will take you directly to the Import Data page.

• If the Journey Discovery Analytics Dashboard already has data, it will display the Sankey chart along with details and filters at the bottom. By default, the dashboard shows data from the last full quarter of the year. You can also use the Import Data button, located at the bottom-right corner of the page, to upload files.

• You can either drag and drop your file or click the Drop File area to begin the upload process. In the file picker, select a file that meets the required criteria, CSV or Parquet format, under 1GB in size, with optional Gzip compression, or

• Double-click the file or click Open to initiate the upload. The system will automatically validate the file’s format and size. The upload may take a few minutes, depending on your internet speed and file size. Please wait until the upload is fully complete.

• Once the upload finishes, the platform will prompt you to map your file’s columns headers such as timestamps, event types, and identifiers, to predefined business objects. This step ensures your data is properly structured for analysis.

Best Practices

• Ensure that your file contains only supported identifiers and remove any unsupported attributes before uploading, to help keep file size smaller.

• If your data includes separate date and time columns, merge them into a single column in the correct timestamp format before uploading. Always format your timestamps according to the required standard (For Example: 2023-12-09T14:30:00-05:00) to ensure compatibility with the system.

• Convert any formulas in your file to static values before uploading to prevent processing failures.

• Clean your dataset by removing unnecessary blank rows, columns, or extra headers that could interfere with the upload process.

• Use correct and consistent column headers that exactly match the predefined identifiers supported by the system.

Saved Mapping

Saved Mapping is a new enhancement to Current-State Analytics. It allows you to reuse an existing mapping configuration from a previous upload, rather than creating a new mapping from scratch each time. This feature is especially useful when you are working with recurring datasets that share the same or similar structure.

By applying a saved mapping, CSA automatically fills in your field mappings based on what you set up earlier. You can then make small adjustments if needed, such as removing an identifier, reassigning an event, or mapping new fields.

How it Works

When you reach the mapping step in Current-State Analytics (Identifiers, Channels, or Events), a new Use Saved Mapping toggle becomes available. This option appears only if at least one mapping has already been saved with a name.

Once you enable the Use Saved Mapping toggle, Current-State Analytics displays a dropdown list of your previously saved mappings. You need to first select a mapping from the dropdown and then upload your dataset file. After the file is uploaded, CSA automatically applies the saved field mappings from the selected mapping to the dataset.

• If your uploaded file has new fields not covered in the saved mapping, they remain unmapped and must be mapped manually.

• If the saved mapping includes fields not present in your uploaded file, those are ignored.

• If a saved mapping references a deleted identifier, channel, or mapping, you will need to recreate it in CSA before completing the mapping.

• Column headers are case sensitive. The capitalization in your uploaded file must exactly match the saved mapping in order to be applied.

Concurrent Data Import

Only one user can perform a data import for a project at a time. If another user tries to import data while an import is already in progress, the system displays the following prompt:

• Data Import has been initiated by another user. You can upload a new data file when this one has completed.

• First-Time Import (No Data on JDA Dashboard)

  • When a user starts the first data import for a project, the Journey Discovery Analytics (JDA) dashboard has no data available.

  • If another user opens the Analytics tab during this time, they will only see the restriction prompt.

  • The dashboard remains unavailable until the import and processing are complete.

• JDA Dashboard Available with Existing Data

  • If data is already available in the Sankey chart on the JDA dashboard, it continues to be visible to all users, even when a new data import is in progress.

  • However, if another user attempts to click on the Import Data button, the system again shows the restriction prompt.

  • Once the ongoing import and processing finish, any user can start a new data import.

Only one data import session can be active for a project at a time.