This document helps you identify and resolve common issues when importing CSV files into Veza.

Understanding CSV Import Behavior

Before troubleshooting, it's important to understand how the CSV import process works:

File Requirements

• Maximum file size: 100MB per CSV file

• Character encoding: UTF-8 recommended

• First row: Must contain column headers

Entity Requirements

• Users: Each user must have either an id or name (or both)

• Groups: Each group must have either an id or name (or both)

Processing Rules

• First-row behavior: For entities appearing in multiple rows, only the first row sets the entity properties

• Subsequent rows: Additional rows with the same identifier only process group and role assignments

• Role permissions: Permissions for the same role are added across all rows (additive)

Common Issues and Solutions

Configuration and Integration Issues

Mapping Issues

Data Format Issues

HRIS-Specific Issues

List Column Issues

Preparation Best Practices

1. Start with a test file

   • Begin with a small subset of data to verify your mapping configuration

   • Test with representative examples of your data structure

Current Limitations

Be aware of these current limitations in the CSV import functionality:

1. No application resources support

   • Resources within applications are not currently supported

2. No direct user-to-permission mapping

Getting Support

If you continue to experience issues after reviewing this guide:

1. Review the for details on supported formats and mapping options

2. Check the for guidance on structuring your CSV files

3. Contact Veza Support with:

Overview

In addition to using a simple web interface to update CSV data manually, you can automate a process to push new data using the Veza REST API and refresh the Veza graph. This document includes example utilities using Python and CLI tools.

When mapping CSV columns to Veza attributes, you can apply transformations to format, combine, or convert data during import. This enables data standardization without requiring modifications to source CSV files.

Transformations are useful for:

• Combining columns into a single attribute (e.g., display name from first and surname)

• Reformatting dates or times to match expected formats

• Standardizing case (uppercase, lowercase, title case)

• Padding numbers to fixed widths, trimming whitespace or removing characters

Using transformations

To apply a transformation, enter a formatter expression in the Value field when mapping a CSV column.

Formatter expressions use curly braces to reference column names. The pipe character (|) can chain transformation functions.

Examples

Combine two columns

To combine first_name and last_name columns into a full name:

Append a static string

To generate an email address from the username column:

Zero-pad a number

To ensure an employee ID is always 8 characters with leading zeros:

Supported transformers

The following transformation functions are available for CSV imports:

For function documentation including parameters and syntax, see the . While reference examples use Lifecycle Management terminology, syntax is the same for CSV transformations.

Related topics

• : CSV integration guide

• : All transformation functions

This document provides practical examples for mapping data from CSV files into Veza using the integration.

You can use the CSV integration to flexibly model user, group, and role relationships based on data exported from the source application. This document includes examples from basic user data import to modeling more complex organizational structures, which you can adapt based on your needs.

Overview

Use CSV Upload to integrate identity and authorization metadata from sources that don't have built-in Veza connectors, but can export or provide data in tabular format.

You can create a CSV integration in Veza to:

• Import user and authorization data from legacy or custom applications

• Integrate with SaaS applications that support CSV exports

• Model employee access to homegrown or specialized systems

• Upload employee metadata from your HRIS as a source of identity for Lifecycle Management workflows

The integration uses the Open Authorization API (OAA) to map CSV data to supported OAA templates:

• Application - Models Users, Groups, Roles, and Resources across applications for a wide variety of authorization use cases. An introduction to the Application Template .

• Human Resource Information Systems (HRIS) - Models employee information from HR sources for use with Lifecycle Management (LCM).

Application Template - Use Custom Applications to model business applications and access permissions:

• Models Users, Groups, Roles, and Resources across applications

• For example, you can upload user permissions from a homegrown CRM system, data store, or any other application users can access.

HRIS Template - Use for employee data from HR systems

• Models employee information and organizational structure

• For example, you can upload employee data for manager-based Access Reviews and automated provisioning with Lifecycle Management.

When to Use CSV Integration

CSV integration is ideal for systems that export tabular data but lack dedicated Veza connectors:

• Legacy applications with user permission exports

• Custom business applications built in-house

• HR systems for employee lifecycle management

CSV import enables modeling identity and permissions metadata for any application not natively supported by Veza, with flexible column mapping, custom properties, and support for multiple data formats.

Adding a CSV Integration

Prerequisites

To create an integration from CSV, you will need:

• A CSV file containing relevant data with column headers

• Sufficient permissions in Veza (Admin or OAA CSV Manager role)

• Understanding of the data model for the source application

For more information about user roles and permissions, see .

Format Requirements

CSV (Comma-Separated Values) is a widely used file format that stores tabular data in plain text. Each row represents a record or a relationship between entities (e.g., User to Role), and columns represent attributes.

When importing from CSV:

1. The first row must contain column headers

2. Each column can be mapped to a specific Veza attribute or custom attribute

3. Columns can be ignored after uploading the file

Create a CSV Integration

To create a new CSV integration:

1. Go to Integrations > Add Integration

2. Choose Upload CSV from the options

3. Upload a logo for the provider (optional) - This will appear throughout the Veza UI, including in Graph search, to identify the integration and entity types.

CSV Column Mapping

The CSV integration allows you to map columns in your file to specific Veza attributes. After uploading the CSV, Veza automatically detects all columns and presents them for mapping.

For each column, you can:

1. Select to include or exclude the column

2. Select the target entity type for mapping (available entities depend on the selected template)

3. Select the specific entity attribute to map to (only attributes applicable to the selected entity type will be shown)

Example: Mapping CSV columns to Application template entities and attributes

For more examples and detailed mapping patterns, see .

Additionally, you can apply to column data for more flexibility and additional formatting. Transformations can be used to:

• Combine columns to form a single attribute (e.g., first_name and last_name into a display name)

• Reformat data such as dates, times, and case (uppercase, lowercase)

• Apply padding, trimming, and character replacement

Supported Entity Types and Attributes

For all entities, an ID or Name is required. If ID is not provided, Name is automatically used as the unique identifier for the entity. Both are also supported.

The available entity types and attributes depend on the template you select. Each template supports different entity types.

Application Template Entities

User Attributes

Group Attributes

Role Attributes

HR System Template Entities

Employee Attributes

Data Type Handling

Boolean Values

The following values are treated as TRUE (case-insensitive):

• true, t

• yes, y

Any other value is treated as FALSE.

Timestamp Formats

Veza supports multiple timestamp formats:

• 2023-04-12T15:34:56.123456789Z (RFC3339 with nanoseconds)

• 2006-01-02T15:04:05Z07:00 (RFC3339)

• 20060102150405 (Active Directory format)

Timestamps are considered unset when the value is never, null, none, false, 0 or empty. Invalid timestamps will result in a processing error.

String Lists

For attributes that support lists (like Role Name List, and Group Name List), values should be comma-separated within the cell and the list enclosude by quotes ".

Updating a CSV Integration

Incremental updates are not supported; you must submit the complete data set for each update.

Push new data for an existing integration

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Under Data Sources, click Upload CSV

Update mappings for an integration

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Click Edit

CSV Manager Role

Veza provides a limited privilege "CSV Manager" role for users that need permission to manage a CSV integration, but should not have access to other functionality in Veza.

Users with this role can:

• Create new CSV integrations

• Upload new CSV data

• Edit existing CSV integrations, including delete

This role can be combined with to further limit a user's scope. When a user with the CSV manager role is added to a non-root team, they can only manage CSV integrations assigned to their team.

Processing Rules

• Multiple Rows per Entity: If the same entity (user, group, or role) appears in multiple rows, Veza processes them as follows:

  • Properties are set based on the first row where the entity ID (or Name if it is being used as the unique ID) appears

  • For subsequent rows with the same identifier, only relationship assignments are processed (for example user to group, or user to role)

Related Documentation