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

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.

To combine first_name and last_name columns into a full name:

To generate an email address from the username column:

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

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.

• : CSV integration guide

• : All transformation functions

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.

Using the Upload CSV REST API

After creating a CSV upload integration, you can use the REST API operation Push Custom Provider Datasource CSV to upload new CSV data.

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

See for more details on creating API keys.

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:

1. On the Veza Integrations page, click the CSV integration to view details

2. On the Data Source tab, click the data source name to view details

3. Copy the values from the Properties table:

   1. The unique data source "Id"

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.

The CSV Upload integration supports notifications to inform subscribers about the status of file uploads and how queries affected by the upload re-evaluate once processing completes.

Notifications are opt-in and configured on the Notifications tab when creating or editing a CSV integration.

Two distinct categories of notification are available:

• Upload and extraction status — progress and outcome of receiving and processing an uploaded file.

• Query Results Refreshed — a summary of how the risk-scored queries affected by the upload were re-evaluated, and whether their results are reflected in the latest risk scores.

You can configure notifications for the following Veza Action integrations:

• Email: No additional configuration required.

• Slack App: Requires the to be configured.

• Microsoft Teams App: Requires the to be configured.

Subject and body are identical across email, Slack, and Microsoft Teams; only channel-specific formatting differs.

• Integration Owners: Notify the users assigned as , not only its creator. Owners can be users or groups; only owners that resolve to a user with an email address are notified. A group listed as an owner is not expanded to its members, so group owners do not receive these notifications.

• Additional Recipients: One or more email addresses, separated by commas.

A notification is only sent when at least one delivery option, one trigger, and one recipient are selected.

These notifications report progress as Veza receives and processes an uploaded file.

Veza polls upload status for up to 24 hours after the file is received to detect extraction events.

These messages are not customizable. Veza sends a fixed subject and body for each trigger, substituting the uploaded file name. For failures, the underlying error message is appended to the body.

Example messages for an uploaded file named employees.csv:

Enable this notification with the Query Results Refreshed checkbox in the integration's notification preferences.

After a CSV upload finishes processing, Veza re-evaluates the queries that depend on the uploaded data and refreshes their results, including any risk scores. The Query Results Refreshed notification summarizes the refresh for the latest risk-score cycle.

Query evaluation and risk-score evaluation run on separate, environment-configurable schedules (typically hourly and daily). The notification is sent once, after the first risk-score evaluation following the upload. If that evaluation does not run before Veza's timeout, the notification is sent anyway, with a subject noting that risk scores were not updated.

Only the queries that the upload could actually change are summarized. A query is included when all of the following are true:

• It has an assigned . Queries without a risk level are not refreshed.

• It is enabled. Disabled and hidden queries are excluded.

• Queries that the upload cannot affect are skipped.

The notification groups the included queries into three lists, based on whether each query finished in time to be reflected in the latest risk-score cycle:

The message shows a count of successful queries (for example, "12 of 14"), a combined count of failed or incomplete queries, and the query names in each group. The successful-query list is truncated after 15 entries, ending with a trailing - ....

The subject reflects the combined outcome and names the uploaded file:

The body opens with the outcome line, then a short note, the counts, and the queries in each group:

Notifications can be configured via REST API by setting the notification_preferences field on the custom provider when or updating an integration.

Example notification_preferences block:

• subscribed_events: FILE_RECEIVED, EXTRACTION_IN_PROGRESS, EXTRACTION_COMPLETED, EXTRACTION_FAILED, FILE_RECEIVE_FAILED, FAILURE (subscribes to all failure events), or QUERY_RESULTS_REFRESHED.

• — create and configure a CSV integration.

• — set up Slack and Microsoft Teams delivery.

This page provides a reference implementation for syncing employee data from an S3-hosted Excel file to Veza using AWS Lambda. Download the example deployment package, configure it for your environment, and schedule it with Amazon EventBridge.

The function reads an employee Excel file from S3 and pushes records to Veza using the HRIS template. It uses the oaaclient Python library to push data, and pandas with openpyxl as the Excel engine to read the employee spreadsheet. openpyxl is bundled in the zip; pandas is provided by the Lambda layer added in the next section.

What the example does

1. Reads environment variables for your Veza API key, S3 bucket, and HRIS name

2. Downloads the employee Excel file from S3 to Lambda's /tmp directory

3. Iterates each row to create an HRISProvider employee record

4. Creates departments as groups and links employees to them

5. Pushes the complete HRIS payload to Veza via the OAA API

6. Optionally enables Lifecycle Management provisioning on the provider

• An AWS account with permission to create and configure Lambda functions

• An S3 bucket containing the employee Excel file

• A Veza API key (see )

1. Open the and click Create function

2. Choose Author from scratch

3. Set the function name (for example, veza-hris-importer)

4. Set Runtime to

After uploading, verify the handler is set to lambda_function.lambda_handler under Runtime settings.

The function uses pandas to read Excel files, with openpyxl as the engine. openpyxl is bundled in the deployment package; pandas is not included in the standard Lambda Python runtime and must be added as a layer.

Add the layer:

1. Scroll to Layers and click Add a layer

2. Choose Specify an ARN

3. Paste the ARN for your AWS region:

   Region

Under Configuration → General configuration, set:

• Memory: 512 MB

• Timeout: 5 minutes

Under Configuration → Environment variables, add:

Same-account bucket:

1. Go to Configuration → Permissions and click the execution role name

2. Choose Add permissions → Attach policies

3. Attach AmazonS3ReadOnlyAccess

Cross-account bucket:

In addition to the role policy above, ask the bucket owner to add a bucket policy granting access to the Lambda execution role:

Replace YOUR-ACCOUNT, YOUR-LAMBDA-ROLE, and bucket-name with the appropriate values.

1. Open the Test tab

2. Create a test event with an empty payload: {}

3. Click Test

4. A successful run returns a statusCode

The S3 Excel file must include all of the following columns except Work Email. Column names are case-sensitive, and every required column must be present even where values are blank — update the names in lambda_function.py if your file uses different headers.

To run the function automatically on a schedule:

1. Go to Configuration → Triggers → Add trigger

2. Select EventBridge (CloudWatch Events)

3. Choose Create a new rule, give it a name, and set a schedule expression:

Before deploying to Lambda, you can run the function locally against a real Veza tenant using DATA_SOURCE=local. This is the fastest way to iterate on column mappings or custom properties.

Prerequisites: Python 3.11+. oaaclient and openpyxl are bundled in the zip. Extract it, then install the remaining dependencies:

Set environment variables and run:

A successful run logs Success and creates (or updates) an HRIS provider in Veza. Check Integrations in the Veza UI to confirm the provider and employee records appear.

The load_users function in lambda_function.py maps columns directly by name. To adapt it for a different Excel schema:

• Update the column name strings (for example, row['Employee Id']) to match your file headers

• Add custom employee properties by calling hris.property_definitions.define_employee_property() before iterating rows

• To link employees to an IdP (for example, Okta), add hris.system.add_idp_type() with the appropriate IdPProviderType

• — manual and API-based upload options

• — data model for employee records

• — automate provisioning based on HRIS data

This document provides practical examples for mapping data from CSV files into Veza using the CSV Upload 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.

• CSV Upload Examples

  • Mapping Concepts

When importing CSV data into Veza, you are typically establishing one or more of these key components:

1. Entities: Users, groups, and roles that exist in your application

2. Attributes: Properties that describe each entity (e.g., name, email, status)

3. Relationships: Connections between entities (user belongs to group, user has role)

The examples below demonstrate different approaches to mapping these components from CSV data into Veza's Access Graph.

For a simple file containing user records, one user per row with a list or groups and roles. You can map columns directly:

Example CSV:

Your CSV files may have column names that differ from Veza's standard attribute names.

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:

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

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 Member permission

This example shows how to represent a complex organizational structure with departments, teams, roles with permissions, and user assignments:

Column mapping for this example:

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

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

Any column can be mapped to a custom property for any entity type. When mapping to a custom property:

1. Select Custom Property as the attribute

2. Enter a name for the custom property

3. Select the data type (String, Number, Boolean, Timestamp

Designated Entity Owners can up supplied for supported Application entity types as part of the CSV. This allows for automatically assigning the owner from the value in the CSV.

This example indicates the owner of the Role and could be used auto-assign Access Review rows to the owner for each role.

Note that when a is configured, Owner Type is optional. Otherwise, the owner type is used to specify the type of entity in Veza Graph that will be assigned as an owner. This will typically be a User entity in your organization's Identity Provider (such as an Okta, Azure AD User, or Active Directory User), representing a top-level human identity.

For more information about Entity Owners, see:

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

• 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

• 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

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

2. Validate CSV format

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

   • Permissions must be assigned to roles, which are then assigned to users

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:

   • A sample of your CSV file (with sensitive data removed)

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.

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

• Specialized industry tools without native APIs

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.

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

• A plan for mapping between CSV columns and Veza attributes

For more information about user roles and permissions, see .

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

4. At minimum, you must map columns for unique identifiers (such as user ID or Name) for each entity type you plan to import (e.g., Users, Groups, Roles, or Employees).

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.

4. Enter an integration name

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)

4. For custom properties, specify a name and data type

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

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

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)

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.

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

4. Select your updated CSV file and click Upload

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Click Edit

4. In the integration configuration, click Edit above the table of current mappings

CSV integrations can send notifications about file upload and extraction status, and a Query Results Refreshed summary of how the risk-scored queries affected by an upload re-evaluate once it completes. Configure notifications on the Notifications tab when creating or editing a CSV integration.

For the available triggers, delivery options, recipients, message content, and REST API configuration, see .

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.

• 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)

Veza correlates the users in your CSV to users in your identity provider by comparing an identity value on each imported user against the attributes it reads from the identity provider. With the Application template, set that value in either of these ways:

• Enter the column names in the Identity field of the application configuration, as a comma-separated list such as email or email,username.

• Map a column to the local user Identities attribute in the column mapper. Mark the mapping as a list to split multiple values from one column.

If you upload a CSV without mapping columns, Veza uses the email column as the identity value.

The values you supply must equal one of the attributes Veza compares on the identity provider, such as the Okta login or email address, or the Entra ID and Active Directory user principal name. The comparison ignores case but is otherwise exact, so a value that differs by a domain, a formatting difference, or a trailing space does not correlate.

Veza does not compare employee IDs automatically. To correlate on an employee ID, or on any other attribute, add a property matcher on the identity provider integration and select the application as the destination. See .

For the attributes Veza compares for each provider, and for how to diagnose users that do not correlate, see .

With the HRIS template, Veza resolves the identity value from the IDP ID, Email, and Employee Number columns, in that order, and takes the first that has a value. An HRIS CSV integration can also hold its own mapping configuration.

Identity mapping does not govern Okta SSO last login enrichment. That enrichment reads the same identity values, but it compares them against one Okta user property that you configure separately, and it applies only to applications that specify an Okta App ID. Correlating a user to an Okta user is therefore not sufficient to produce a sso_last_login_at value. See .