Custom HRIS Provider

OAA Template for Human Resources Information Systems

Overview

Use this Open Authorization API template to publish employee metadata for Human Resources Information Systems (HRIS) platforms, typically used by organizations as a single source of truth for employee information.

Unlike an Identity Provider, HR platforms typically do not provide access to other systems. Employee profiles within an HRIS platform are instead used to store important details such as employment status, who individuals report to, department, and country. Veza can use this metadata to:

• Trigger Lifecycle Management events when there is a change in the integrated HRIS data source.

• Correlate employees in the HRIS system with identities in your identity provider (IdP).

• Enrich Access Reviews with details about linked HRIS employees for users under review.

The template supports:

• A top-level System entity representing the HRIS tenant, organization, or account.

• Employee entities representing current and inactive workers

• Group entities representing teams, departments, cost centers, or other units to which users are assigned.

To enable this payload format, specify the hris custom template when creating an OAA provider with the API.

HRIS template example

{
  "name": "HRIS Example",
  "hris_type": "HR Platform",
  "custom_property_definition": {
    "system_properties": {},
    "employee_properties": {
      "job_level": "STRING"
    },
    "group_properties": {}
  },
  "system": {
    "id": "7D8A21AE-6650-4357-842B-3FCEC8F29195",
    "name": "HRIS Example",
    "url": "https://hris.example.com",
  },
  "employees": [
    {
      "id": "123456",
      "name": "jdoe",
      "employee_number": "E123456",
      "first_name": "John",
      "last_name": "Doe",
      "canonical_name": "Doe, John",
      "email": "[email protected]",
      "home_location": "Anytown, CA",
      "work_location": "San Francisco, CA",
      "employment_status": "HIRED",
      "start_date": "2022-05-22T00:00:00Z",
      "job_title": "Software Developer",
      "employment_types": [
        "FULL_TIME"
      ],
      "custom_properties": {
        "job_level": "L3"
      },
      "is_active": true,
      "groups": [
        {
          "id": "all_employees"
        }
      ],
      "managers": [
        {
          "id": "987654"
        }
      ],
      "department": {
        "id": "engineering"
      }
    },
    {
      "id": "987654",
      "name": "jane.doe",
      "employee_number": "E987654",
      "first_name": "Jane",
      "last_name": "Doe",
      "canonical_name": "Doe, Jane",
      "email": "[email protected]",
      "home_location": "Anytown, CA",
      "work_location": "San Francisco, CA",
      "employment_status": "HIRED",
      "start_date": "2021-03-13T00:00:00Z",
      "job_title": "Software Developer",
      "employment_types": [
        "FULL_TIME"
      ],
      "custom_properties": {
        "job_level": "M2"
      },
      "is_active": true,
      "groups": [
        {
          "id": "all_employees"
        }
      ],
      "department": {
        "id": "engineering"
      }
    }
  ],
  "groups": [
    {
      "id": "all_employees",
      "name": "All Employees",
      "group_type": "Employee Group"
    },
    {
      "id": "engineering",
      "name": "Engineering",
      "group_type": "Department"
    }
  ]
}

Custom properties

The HRIS template supports custom properties. After specifying a custom property definition in the payload, you can assign additional attributes to entities. These enable attribute filters for searches and access reviews in Veza, and enrich results with entity metadata unique to the source system or your organization.

{
  "name": "BambooHR",
  "hris_type": "BambooHR",
  "custom_property_definition": {
    "employee_properties": {
      "division": "STRING",
      "office_extension": "STRING"
    },
    "group_properties": {
      "headquarters_location": "STRING"
    }
  },
  "system": {
    "name": "BambooHR",
    "id": "BambooHR",
    "url": "https://vezai.bamboohr.com",
    "idp_providers": ["okta"]
  },
  "employees": [
    {
      "name": "Charlotte Abbott",
      "id": "1",
      "custom_properties": {
        "division": "North America",
        "office_extension": "1234"
      },
      "employee_number": "1",
      "email": "[email protected]",
      "work_location": "Lindon, Utah",
      "job_title": "Sr. HR Administrator"
    },
    {
      "name": "Cheryl Barnet",
      "id": "10",
      "custom_properties": {
        "division": "North America",
        "office_extension": "5678"
      },
      "employee_number": "10",
      "email": "[email protected]",
      "work_location": "Lindon, Utah",
      "job_title": "VP of Customer Success"
    }
  ],
  "groups": [
    {
      "name": "North America-Human Resources",
      "id": "North America-Human Resources",
      "group_type": "Department",
      "custom_properties": {
        "headquarters_location": "Lindon, Utah"
      }
    }
  ]
}

Identity mappings

Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or id value in the HRIS payload with the IdP entity's Name, Principal Name, or Identity. The matching process checks these fields in the following sequence:

1. idp_id

2. email

3. id

If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the id is used. Veza issues a warning if no matching entity is found.

Custom HRIS System

The account/tenant/etc. that contains the HR information.

Property	Attribute Name	Type	Required	Unique	Description
URL	url	String	Y	N	The url for this HRIS system.

Custom HRIS Employee

Used to represent any person who has been employed by a company.

Property	Attribute Name	Type	Required	Unique	Description
Employee Number	employee_number	String	Y	Y	The employee's number that appears in the third-party integration.
Company	company	String	N	N	The company (or subsidiary) the employee works for.
First Name	first_name	String	Y	N	The employee's first name
Last Name	last_name	String	Y	N	The employee's last name
Preferred Name	preferred_name	String	N	N	The employee's preferred first name.
Display Full Name	display_full_name	String	N	N	The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.
Canonical Name	canonical_name	String	N	N	The employee's canonical name.
Username	username	String	N	N	The employee's username that appears in the integration UI.
Email	email	String	N	Y	The employee's work email.
IDP ID	idp_id	String	N	N	The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used
Personal Email	personal_email	String	N	N	The employee's personal email.
Home Location	home_location	String	N	N	The employee's home location.
Work Location	work_location	String	N	N	The employee's work location.
Cost Center	cost_center	String	N	N	The cost center ID (Group ID) that the employee is in.
Department	department	String	N	N	The department ID (Group ID) that the employee is in.
Managers	managers	STRINGLIST	N	N	The IDs of the employee's managers.
Groups	groups	STRINGLIST	N	N	The IDs of groups this user is in
Employment Status	employment_status	String	Y	N	The employment status of the employee. Possible values include - ACTIVE, PENDING, INACTIVE.
Is Active	is_active	BOOLEAN	Y	N	If the employee is active or not.
Start Date	start_date	TIMESTAMP	N	N	The date that the employee started working. If an employee was rehired, the most recent start date will be returned.
Termination Date	termination_date	TIMESTAMP	N	N	The employee's termination date.
Job Title	job_title	String	N	N	The title of the employee.
Employment Types	employment_types	STRINGLIST	N	N	The employee's type of employment. Possible values include - FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.
Primary Time Zone	primary_time_zone	String	N	N	The time zone which the employee primarily lives.

Custom HRIS Group

Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.

Property	Attribute Name	Type	Required	Unique	Description
Group Type	group_type	String	Y	N	The type of group, possible values include - TEAM, DEPARTMENT, COST_CENTER, BUSINESS_UNIT, GROUP. This is intended as to not have each type as their own nodes.
Parent	parent	String	N	N	The group ID of its parent group.