# Bullhorn

**Early Access**: This integration is provided as an Open Authorization API (OAA) connector package. Contact our support team for more information.

## Bullhorn Connector for Veza

The Veza connector for Bullhorn enables users to import Bullhorn User entitlements into Veza. Users are imported along with the entitlements summary to show the Bullhorn User Type for each user and the permissions that the user type is entitled to.

### Application Mappings

The Bullhorn connector uses the OAA Custom Application model. The following table shows how Veza Custom Application entities correspond to Bullhorn entities.

| Bullhorn    | Veza        |
| ----------- | ----------- |
| Instance    | Application |
| User        | Local User  |
| User Type   | Local Role  |
| Entitlement | Permission  |

### Properties

The following entity properties are imported:

| Entity | Property                 | Description                              |
| ------ | ------------------------ | ---------------------------------------- |
| User   | `primary id`             | User's login                             |
| User   | `is_active`              | Boolean if User is active                |
| User   | `email`                  | Primary email configured for user        |
| User   | `additional_emails`      | List of any additional emails configured |
| User   | `user_id`                | Bullhorn unique user ID                  |
| User   | `master_user_id`         | Bullhorn master user ID                  |
| User   | `title`                  | User's title configured in Bullhorn      |
| User   | `primary_department`     | User's primary department                |
| User   | `additional_departments` | List of any additional departments       |
| User   | `user_type`              | String of User's type                    |

### Running the Importer

Bullhorn does not currently provide the necessary API endpoints to extract the authorization information programmatically. Identity and authorization information is imported through CSV data that can be collected from Bullhorn.

The importer takes in a parameter `--name`, this name will appear in the name of the Application entity in Veza as `Bullhorn - {name}` and will be used for the Veza data source name. The name must remain consistent for subsequent imports. After the initial run, if `--name` does not match a previously used name the importer will stop. To create new instances run with `--create` once to create the new data source.

#### Bullhorn

1. Export the User list from Bullhorn and convert to CSV file. The exported data should include the following required headers. Additional columns are ignored:

```
Master UserID,UserID,Login Name,First Name,Last Name,Email,Additional Email Addresses,Title,Enabled?,UserType,Primary Department,Additional Departments
```

2. Request an export of the User Type entitlements from Bullhorn support. The provided data should be converted to CSV if not already in CSV format. Expected format is Entitlements as rows and User Types as columns with `Type` and `Entitlement` columns.

#### Veza

1. Generate a Veza user API key by navigating to **Administration** -> *API Keys*. Choose *Add New*. Give the key a name and copy the token, which will only be shown once.

### Running the Connector

#### Command Line

1. Install the requirements:

   ```shell
   pip3 install -r requirements.txt
   ```
2. Set the secrets:

   ```shell
   export VEZA_API_KEY="ZXldTcj...JCWGU3Qlo1OHR3RTBfc00yN3lfSFk="
   ```
3. Run the connector:

   ```shell
   ./oaa_bullhorn.py --veza-url https://<your-org>.vezacloud.com --users <user_export.csv> --entitlements <entitlements_export.csv> --name "Prod"
   ```

#### Parameters

| CLI Parameter         | Environment Variable | Description                                               |
| --------------------- | -------------------- | --------------------------------------------------------- |
| `--veza-url`          | `VEZA_URL`           | URL of Veza system                                        |
|                       | `VEZA_API_KEY`       | API key for Veza connection                               |
| `-u`/`--users`        |                      | Path to user list export CSV file                         |
| `-e/``--entitlements` |                      | Path to user type entitlements export CSV file            |
| `-n`/`--name`         |                      | Name of Bullhorn instance for managing multiple instances |
| `--create`            |                      | Create new datasource for `name` if doesn't already exist |
| `--debug`             |                      | Enable verbose debug output                               |
| `--save-json`         |                      | Save OAA Payload as local JSON file before upload         |


---

# 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/integrations/integrations/bullhorn.md?ask=<question>
```

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.