Solutions for common CSV import issues in Veza
This document helps you identify and resolve common issues when importing CSV files into Veza.
Before troubleshooting, it's important to understand how the CSV import process works:
Maximum file size: 100MB per CSV file
Character encoding: UTF-8 recommended
First row: Must contain column headers
Column delimiters: Commas
Text qualifiers: Double quotes for fields containing commas
Users: Each user must have either an id or name (or both)
Groups: Each group must have either an id or name (or both)
Roles: Each role must have either an id or name (or both)
If only id or name is provided for an entity, that value is used for both fields and must be unique
Minimum mapping: You must map at least one column for each entity type you want to import
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)
All properties: All properties (including custom properties) are set only from the first row where that entity appears
CSV file is rejected with validation error
Verify you've mapped the minimum required fields (id or name for all entity types)
Only some properties appear
Check that columns are mapped to the correct entity types and attributes
Users appear without group/role assignments
Ensure you've correctly mapped group and role columns
Entities appear multiple times
Ensure that the value you're using for id is unique (Veza automatically cleans whitespace and is case-insensitive)
Boolean values not interpreted correctly
Use standard values: true, t, yes, y, 1, active, or enabled for TRUE
Timestamp data not processed
Multiple groups/roles not assigned properly
For list columns, ensure values are comma-separated and enclosed in quotes if they contain commas
Special characters causing parsing issues
Save your CSV with UTF-8 encoding and ensure text with commas is properly quoted
Groups/roles in comma-separated lists not assigned
Verify you've selected the list option when mapping the column
Only first value in list is processed
Check for proper quoting around values that contain commas
Only some list values appear
Check for inconsistent naming between list items and other references to the same entity
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
Validate CSV format
Ensure proper comma delimitation
Quote fields containing commas
Use consistent data formats across rows
Pre-plan your mapping
Identify which columns map to which entity types and attributes
Determine how to handle multi-value fields (as lists or multiple rows)
Identify custom properties and their data types
Consider data quality
Standardize identifiers (case consistency, no trailing spaces)
Use consistent naming for groups and roles
Validate data formats before import
Be aware of these current limitations in the CSV import functionality:
No application resources support
Resources within applications are not currently supported
No direct user-to-permission mapping
Permissions must be assigned to roles, which are then assigned to users
Direct user-to-permission mappings (without a role) are not supported
No column transformations
The system cannot combine or transform column values during import
Column transformations or combinations are not supported
Full replacement updates
Each update completely replaces the previous data
Incremental updates are not supported
Custom property types are fixed after creation
Once a custom property type is set and data processed, it cannot be changed
Changing custom property types requires deleting the integration and recreating it
Default permissions
If no column is mapped to role permissions, Veza assigns a default "Uncategorized" permission.
If you continue to experience issues after reviewing this guide:
Contact Veza Support with:
A sample of your CSV file (with sensitive data removed)
Your mapping configuration
A description of the unexpected behavior
Common patterns for importing identity and permissions metadata from CSV files
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.
When importing CSV data into Veza, you are typically establishing one or more of these key components:
Entities: Users, groups, and roles that exist in your application
Attributes: Properties that describe each entity (e.g., name, email, status)
Relationships: Connections between entities (user belongs to group, user has role)
Permissions: Actions that roles allow users to perform
The examples below demonstrate different approaches to mapping these components from CSV data into Veza's Authorization Graph.
For a simple file containing user records, one user per row with a list or groups and roles. You can map columns directly:
employee_id
local_user
id
Yes
display_name
local_user
name
No
email_address
local_user
No
account_status
local_user
is_active
No
join_date
local_user
created_at
No
last_access
local_user
last_login_at
No
password_updated
local_user
password_last_changed_at
No
termination_date
local_user
deactivated_at
No
groups
local_group
name list
No
roles
local_role
name list
No
Example CSV:
Your CSV files may have column names that differ from Veza's standard attribute names.
departments, department_names, teams
local_group
name list
job_titles, positions, roles_assigned
local_role
name list
permissions, access_rights
local_role
permissions list
The CSV integration supports two methods for assigning users to groups and roles:
Use a single column containing comma-separated values to assign a user to multiple groups or roles at once.
Column mapping:
user_id
local_user
id
groups
local_group
name list
roles
local_role
name list
Example CSV:
Key points about list columns:
Values must be comma-separated
Enclose lists in quotes if they contain commas
Whitespace around values is automatically trimmed
Empty values are ignored
Veza automatically creates any groups or roles that don't already exist
Additional properties on Groups and Roles is not supported
You can incrementally assign roles or groups using multiple rows with the same user id. This approach is useful when:
You have many groups or roles per user
Your source system exports data in this format
You need to include additional details for roles or groups such as custom properties
Example CSV:
Key points about multiple row assignments:
The first occurrence of an entity id sets all properties for that entity. If the same user or role is listed more than once, the user or role attributes are not updated for rows after the first.
Subsequent rows only process new group and role assignments
The CSV can include a column with a list of permissions for each role. This enables searching and filtering by permission in Veza:
You can assign permissions to roles and then users to roles:
Note: If permissions column is not defined any Roles are automatically assigned the
Memberpermission
This example shows how to represent a complex organizational structure with departments, teams, roles with permissions, and user assignments:
Column mapping for this example:
user_id
local_user
id
display_name
local_user
name
local_user
active
local_user
is_active
department
local_group
name
team
local_group
name
job_title
local_user
custom property (String)
role
local_role
name
role_permissions
local_role
permissions list
This example CSV will create:
7 user entities with their properties
Department groups (Engineering, Product, Marketing, Finance, HR, Sales)
Team groups (Backend, Architecture, Frontend, Product Management, UX Research, Content, Social, Accounting, Recruiting, Enterprise Sales)
Multiple role assignments per user
Role permission assignments for different functional areas
The CSV integration supports various timestamp formats:
Timestamps are considered unset when the value is never, null, none, false, or 0. Invalid timestamps will result in a processing error.
When mapping to boolean attributes like is_active:
TRUE values: true, t, yes, y, 1, active, enabled
FALSE values: Any other value including false, f, no, n, 0, inactive, disabled
Any column can be mapped to a custom property for any entity type. When mapping to a custom property:
Select Custom Property as the attribute
Enter a name for the custom property
Select the data type (String, Number, Boolean, Timestamp, or String List)
Automating updating CSV integration data
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.
Whenever a CSV is submitted, it is processed based on the current configuration of the CSV Upload Integration provider, including any column mapping settings.Authentication: To make API calls, you must include an authorization token in the header of each request. This can be:
A Personal API Key for a Veza administrator
A Team API Key, for a team assigned to manage CSV Upload integrations
Note: The CSV data must be complete for each upload. Veza will remove entities from the Graph for any entities that were present in the previous upload, but not in the current upload.
Using the REST API requires the Integration (Provider) and Data Source IDs. You can retrieve these in Veza on the Integration Details > Data Source tab:
On the Veza Integrations page, click the CSV integration to view details
On the Data Source tab, click the data source name to view details
Copy the values from the Properties table:
The unique data source "Id"
The "Provider Id"
Both values are in UUID format, e.g., 19b0c736-6686-4708-87e2-92171db6afb3.
Uploading the CSV data is made with a post call to the /api/v1/providers/custom/{provider_id}/datasources/{data_source_id}:push_csv endpoint.
Note: The CSV contents must be base64-encoded into the JSON body of the request. Raw CSV values are rejected. You can automatically convert the data as part of your implementation, as shown below.
Import identity and authorization data from CSV files into Veza
Use CSV Upload to integrate identity and authorization metadata from sources that don't have built-in Veza connectors, but support exporting this information 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
CSV import enables modeling identity and permissions metadata for any application not natively supported by Veza, with support for:
Flexible column mapping: Map any exported CSV column to Veza identity attributes
Support for custom properties: Map columns to custom attributes in Veza
Multiple data formats: Process timestamps, booleans, and string lists in various formats
To create an integration from CSV, you will need:
A CSV file containing relevant data with column headers
Sufficient permissions in Veza (Administrator or CSV Manager role)
Understanding of the data model for the source application
A plan for mapping between CSV columns and Veza attributes
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:
The first row must contain column headers
Each column can be mapped to a specific Veza attribute or custom attribute
Columns can be ignored after uploading the file
At minimum, you must map columns for unique identifiers (such as user ID or Name)
To create a new CSV integration:
Go to Integrations > Add Integration
Choose Upload CSV from the options
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.
Enter an integration name
Use a title that uniquely identifies this integration source
Avoid generic terms like "application" or "CSV"
If you have multiple environments, consider including that in the name
Select a data source template (currently supports Application and HR Systems)
Enter template-specific information (fields will vary based on the selected template):
For Application Template:
Name: A unique identifying name for this specific application instance (e.g., "Marketing CRM - Prod", "HR Portal - Dev").
Type: The general category or system type (e.g., "CRM", "DevOps Tool"). In Veza, the type appears as a prefix on entity names, e.g., CRM User, DevOps Tool Role.
For HR System Template:
Name: A unique identifying name for the HR system (e.g., "Workday - Production", "HR Portal - Dev")
Type: The type of HR system (e.g., "HRIS", "ATS", "Benefits")
URL: The URL of the HR system
Note: Naming is critical for easy search in Veza. For Applications, the Type enables searching for all entities of that category, while the Name differentiates between multiple instances of the same system type.
Upload the CSV file - Veza will read the column headers and show them for mapping
Map your columns to Veza attributes (see Column Mapping section)
Click Create Integration to trigger extraction and parsing
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:
Select to include or exclude the column
Select the target entity type for mapping (available entities depend on the selected template)
Select the specific entity attribute to map to (only attributes applicable to the selected entity type will be shown)
For custom properties, specify a name and data type
Example: Mapping CSV columns to Application template entities 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
The following values are treated as TRUE (case-insensitive):
true, t
yes, y
1
active
enabled
Any other value is treated as FALSE.
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)
2006-01-30 15:04:05Z07:00
2006-01-30 15:04:05
2006-01-30
2006-01-30T
2006-01-30T15:04:05
2006-01-30T15:04:05Z
1/2/2006 (MM/DD/YYYY format)
Timestamps are considered unset when the value is never, null, none, false, 0 or empty. Invalid timestamps will result in a processing error.
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 ".
Incremental updates are not supported; you must submit the complete data set for each update.
Find the CSV integration on the Veza Integrations page
Click on the integration name to view details
Under Data Sources, click Upload CSV
Select your updated CSV file and click Upload
Find the CSV integration on the Veza Integrations page
Click on the integration name to view details
Click Edit
In the integration configuration, click Edit above the table of current mappings
Modify your column mappings as needed
Click Save Configuration to apply the changes
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
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)
Role permissions are the only properties that are additive across all rows
Ignored Columns: Columns that are not mapped (unchecked) are ignored during processing
Additional Columns: CSV files can contain more columns than are mapped - extra columns are ignored
Entity Identifiers: Every entity type (user, group, role) requires an ID or Name (or both). If only one is provided, the same value is used for both fields and must be unique.
Identity Mapping: When using the Application template, you can choose the column(s) used to connect external identities.
Ensure timestamps are in one of the supported formats listed in the
Review the for details on supported formats and mapping options
Check the for guidance on structuring your CSV files
This document provides practical examples for mapping data from CSV files into Veza using the integration.
After creating a CSV upload integration, you can use the REST API operation to upload new CSV data.
See for more details on creating API keys.
The integration uses Open Authorization API (OAA) to enable modeling a range of different source applications. Uploading CSV data creates an . It also populates Authorization Graph entities with the specified attributes. The integration currently supports Users, Groups, and Roles (using the Custom Application template) and Employees (Custom HRIS).
For more examples and detailed mapping patterns, see .
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.
ID
Unique identifier for the user
Name
Display name for the user
Is Active
Boolean indicating if the user is active
Created At
Timestamp when the user was created
Last Login At
Timestamp of the user's last login
Deactivated At
Timestamp when the user was deactivated
Password Last Changed At
Timestamp of the last password change
User's email address
Custom Properties
Map any column to a custom user property (type varies)
ID
Unique identifier for the group
Name
Name of the group (supports list format)
Created At
Timestamp when the group was created
Custom Properties
Map any column to a custom group property (type varies)
ID
Unique identifier for the role
Name
Name of the role (supports list format)
Permissions
Permissions assigned to the role (supports list format)
Custom Properties
Map any column to a custom role property (type varies)
ID
Unique identifier for the employee
Name
Employee name (typically full name)
Employee Number
Alternative employee identifier
Company
Employee's company
First Name
Employee's first name
Last Name
Employee's last name
Preferred Name
Employee's preferred name
Display Full Name
Complete display name
Canonical Name
Standardized name format
Username
Employee's username
Primary email address
IDP ID
Identity Provider ID
Personal Email
Personal email address
Home Location
Employee's home location
Work Location
Employee's work location
Cost Center
Cost center assignment
Department
Employee's department
Managers
Employee's manager(s) (supports list format)
Groups
Group memberships (supports list format)
Employment Status
Current employment status
Is Active
Boolean indicating active employment
Start Date
Employment start date
Termination Date
Employment end date
Job Title
Employee's job title
Employment Types
Types of employment (supports list format)
Primary Time Zone
Employee's primary time zone
Custom Properties
Map any column to a custom employee property (type varies)
