# Custom HRIS Provider ### 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](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management.md) 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](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#create-custom-provider) with the API. ### HRIS template example ```json { "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": "jdoe@example.com", "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": "jane.doe@example.com", "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](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md). 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. ```json { "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": "cabbott@efficientoffice.com", "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": "cbarnet@efficientoffice.com", "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 | N | N | The url for this HRIS system. | | IDP Providers | `idp_providers` | String list | N | N | List of destination IdP provider types to connect this system to (e.g. `okta`, `azure_ad`). | | Identity Mapping Configuration | `identity_mapping_configuration` | Object | N | N | Configuration for mapping employees to identities in external data sources. | #### 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 | N | 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 | N | N | The employee's first name. | | Last Name | `last_name` | String | N | 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` | EntityRef | N | N | Reference to the group representing the cost center the employee is in (e.g. `{"id": "cost-center-001"}`). | | Department | `department` | EntityRef | N | N | Reference to the group representing the department the employee is in (e.g. `{"id": "engineering"}`). | | Managers | `managers` | EntityRef list | N | N | References to the employee's managers (e.g. `[{"id": "987654"}]`). | | Groups | `groups` | EntityRef list | N | N | References to the groups this employee is in (e.g. `[{"id": "all_employees"}]`). | | Employment Status | `employment_status` | String | N | N | The employment status of the employee. Possible values include - `ACTIVE`, `PENDING`, `INACTIVE`. | | Is Active | `is_active` | Boolean | N | 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` | String list | 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` | EntityRef | N | N | Reference to the parent group (e.g. `{"id": "parent-group-id"}`). | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/hris-template.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.