What Are the Runner Types?

OAA runner supports four destination_type values that determine which Veza provider template is used and which destination objects you can map data to. This guide explains the differences and helps you choose the right one.

Overview

All integrations use the same runner class (CustomAppRunner) and the same CLI command (oaa app run). The destination_type field in config.yaml selects the Veza provider template and controls which destination object types are available.

destination_type	Provider Class	Destination Objects	Use Case
CUSTOM_APP (default)	CustomApplication	LocalUser, LocalGroup, LocalRole, Resource	Any application with its own users, groups, roles, or resources
HRIS	HRISProvider	Employee, Group	Workforce/HR systems (Workday, BambooHR, Personio, etc.)
IDP	CustomIdPProvider	User, Group	Identity providers (custom LDAP, in-house SSO, non-native IdP)
ENTITY_ENRICHMENT	EntityEnrichment	EnrichedEntity	Enriching existing Veza entities with additional data

Decision Guide

If your system is an HR source of record (it manages employees, employment status, departments): → Use HRIS

If your system authenticates users (it is an identity provider, SSO, or directory): → Use IDP

If your system manages its own users, roles, or resources (a SaaS app, internal tool, database): → Use CUSTOM_APP (the default)

If you are adding supplemental data to existing Veza entities (enrichment, not primary identity data): → Use ENTITY_ENRICHMENT

Required Fields Per Destination Object

CUSTOM_APP (default)

Destination	Required Fields	Additional Notes
LocalUser	name, unique_id
LocalGroup	name, unique_id
LocalRole	name, unique_id	Supports do_perm_mapping: true for permission auto-registration
Resource	name, unique_id	Requires source-level resource_type field

HRIS

Destination	Required Fields	Additional Notes
Employee	unique_id, name, employee_number, first_name, last_name, is_active, employment_status	7 mandatory fields
Group	name + one of (identity, unique_id)	Exactly one identifier must be mapped. GROUP_TYPE config defaults to Department

IDP

Destination	Required Fields	Additional Notes
User	identity, name, email	3 mandatory fields
Group	name + one of (identity, unique_id)	Exactly one identifier must be mapped

ENTITY_ENRICHMENT

Destination	Required Fields	Additional Notes
EnrichedEntity	id	Also requires source-level entity_type and data_source_id

CLI Invocation

All runner types use the same CLI entry point. The destination_type in config.yaml determines the behavior:

# All types use the same command
uv tool run --from oaa-runner oaa app run --config=config.yaml

# Validate
uv tool run --from oaa-runner oaa app validate --config=config.yaml

# Dry run (no push)
uv tool run --from oaa-runner oaa app run --config=config.yaml --dry_run=True --save-json=True

There is no oaa hris run or oaa idp run subcommand. The runner reads destination_type from the config file to determine which provider template to use.

App Configuration Fields by Type

Each destination_type expects different metadata in the app block:

CUSTOM_APP

app:
  name: My Application          # required
  application_type: Custom App  # optional
  url: https://app.example.com   # optional

HRIS

app:
  name: My HR System             # required
  hris_type: workday             # required
  url: https://hr.example.com     # required

IDP

app:
  name: My Identity Provider    # required
  idp_type: custom_idp          # required
  domain: idp.example.com       # required

ENTITY_ENRICHMENT

app:
  name: My Enrichment Source    # required

Custom Properties

All destination types support custom properties using custom_type in field mappings:

Type	Description
STRING	Text values
BOOLEAN	True/False values
NUMBER	Numeric values
STRING_LIST	Array of strings
TIMESTAMP	ISO 8601 date/time
TIMESTAMP_AD	Windows AD timestamp

For complete details, see What are Veza Custom Properties?.

How-To Guides

For step-by-step instructions on creating each type of integration:

• How to Create an HRIS Integration — Employee and Group destinations

• How to Create an IDP Integration — User and Group destinations

• How to Create a Custom App Integration — LocalUser, LocalGroup, LocalRole, and Resource destinations