# Freshservice

### Overview

[Freshservice](https://www.freshworks.com/freshservice/) is a cloud-based IT service management (ITSM) platform by Freshworks. The Veza integration for Freshservice discovers agents, groups, and roles, and populates the Access Graph with authorization metadata. Optionally, CMDB extraction discovers Configuration Items and uses Cross-Service Correlation (CSC) to link them to identities in the Access Graph, enabling asset ownership visibility across your organization.

This integration enables:

* **Access visibility**: Discover Freshservice agents, groups, and roles. Use Query Builder and Graph to report on role assignments and group memberships.
* **Access reviews**: Certify Freshservice agent role assignments, with support for mapping IdP identities to Freshservice agents.
* **Asset ownership** (CMDB): Map CMDB configuration items to their owners across identity providers for Suggested Owners and compliance reporting.

```mermaid
graph LR
    subgraph "Freshservice Application"
        Agent[Agent / User]
        Group[Group]
        Role[Role]
    end

    subgraph "Freshservice CMDB (optional)"
        CI[Configuration Item]
    end

    subgraph "Veza Access Graph"
        IdP["Identity Provider User
        (e.g., OktaUser)"]
        Resource["Cloud Resource
        (e.g., S3Bucket)"]
    end

    Agent -->|member_of| Group
    Agent -->|assigned| Role
    CI -.->|"owner (CSC)"| IdP
    CI -.->|"asset link (CSC)"| Resource
```

See [Notes and supported entities](#notes-and-supported-entities) for details on discovered data.

### Prerequisites

Before configuring the integration:

* **Veza support enablement**: This Early Access integration must be enabled on your Veza tenant. Contact Veza support to request access.
* **Network connectivity**: Connection from Veza to your Freshservice instance via a [deployed Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) or direct connection.
* **Freshservice API key**: An API key generated from your Freshservice account (see below).
* **CMDB column labels** (if enabling CMDB): The display labels of the Freshservice fields you will use for owner and asset identification.

### Configuring Freshservice

#### Get an API key

Veza authenticates to Freshservice using an API key.

1. Log in to your Freshservice instance.
2. Click your profile avatar in the upper right and select **Profile Settings**.
3. Under the **API Settings** section, copy your API key.

For detailed instructions, see [API Authentication](https://support.freshservice.com/en/support/solutions/articles/50000000306-where-can-i-find-my-api-key-) in the Freshservice documentation.

### Configuring Freshservice on the Veza platform

1. In Veza, go to the **Integrations** page.
2. Click **Add Integration** and search for **Freshservice**.
3. Click **Next** to begin configuration.
4. Enter the required information (see table below).
5. Optionally, enable CMDB extraction and configure column mappings.
6. Click **Create Integration** to save and start the first extraction.

#### Configuration options

| Field                | Required | Notes                                                                                          |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| **Insight Point**    | Yes      | Choose the default data plane or a deployed Insight Point.                                     |
| **Name**             | Yes      | A friendly name to identify this integration.                                                  |
| **Freshservice URL** | Yes      | Your Freshservice instance URL (e.g., `https://yourcompany.freshservice.com`).                 |
| **API Key**          | Yes      | The API key from Freshservice Profile Settings.                                                |
| **Enable CMDB**      | No       | Check to enable CMDB asset extraction. When enabled, the Column Mapping Configuration appears. |

#### CMDB Column Mapping Configuration

Checking **Enable CMDB** shows additional fields for configuring cross-service connections. These tell Veza how to match Freshservice CMDB assets to identities in the Access Graph for Suggested Owners.

{% hint style="warning" %}
Column names must match the **display labels** of Freshservice fields exactly as they appear in the Freshservice UI — not the API field names. If a column name doesn't match any field label, Veza logs a warning during extraction.
{% endhint %}

**Entity Configuration (required when CMDB is enabled)**

| Field                      | Description                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Owner ID Column Name**   | Display label of the Freshservice field containing the owner identifier (e.g., `Owner Email`).                            |
| **Asset ID Column Name**   | Display label of the Freshservice field containing the asset identifier (e.g., `Serial Number`).                          |
| **Asset Type Column Name** | Display label of the Freshservice field containing an asset type override value.                                          |
| **Owner Node Type**        | The Veza entity type to resolve ownership against (e.g., `OktaUser`). Select from the dropdown.                           |
| **Owner ID Property**      | The property on the Owner Node Type to match against the owner ID column value (e.g., `email`). Select from the dropdown. |

**Asset Connections (optional)**

Asset Connections enable explicit mappings between Freshservice asset types and Veza entity types. Without explicit mappings, Veza uses fuzzy matching to resolve assets, which may not be accurate. Adding explicit mappings is strongly recommended.

Each Asset Connection maps one Freshservice asset type to a Veza entity type:

| Field                   | Description                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| **Asset Type Value**    | The Freshservice asset type name exactly as it appears in Freshservice (e.g., `AWS S3 Bucket`).   |
| **Asset Node Type**     | The Veza entity type to link this asset type to (e.g., `S3Bucket`). Select from the dropdown.     |
| **Asset Property Name** | The property on the Asset Node Type to use for matching (e.g., `name`). Select from the dropdown. |

Click **+ Add Asset Connection** to add additional mappings.

### Notes and supported entities

The Freshservice integration creates two extraction types:

* **Application**: Discovers agents (users), groups, and roles. Always runs.
* **CMDB**: Discovers Configuration Items. Only runs when **Enable CMDB** is checked.

#### Discovered entities

**Application entities:**

* **Local Users (Agents)**: Freshservice agents with email, name, and active status. Linked to identity provider users via email identity matching.
* **Local Groups**: Freshservice agent groups, classified by group type.
* **Local Roles**: Freshservice roles assigned to agents.

**CMDB entities (when enabled):**

* **Configuration Items**: CMDB assets from Freshservice. CSC links each CI to its owner identity and corresponding cloud resource. Only assets with a state of `In Use` are marked active.

#### Key attributes

**Agent (Local User)**

| Veza Attribute   | Freshservice Field        | Notes                                                   |
| ---------------- | ------------------------- | ------------------------------------------------------- |
| `name`           | `first_name`, `last_name` | Combined from first and last name, falls back to email. |
| `email`          | `email`                   | Primary identifier for identity matching.               |
| `first_name`     | `first_name`              | Custom property.                                        |
| `last_name`      | `last_name`               | Custom property.                                        |
| `Is Active`      | `active`                  | `true` when the agent account is active.                |
| `created_at`     | `created_at`              | Account creation timestamp.                             |
| `last_login_at`  | `last_login_at`           | Last login timestamp.                                   |
| `deactivated_at` | `deactivated_at`          | Deactivation timestamp, if applicable.                  |

**Role**

| Veza Attribute | Freshservice Field | Notes             |
| -------------- | ------------------ | ----------------- |
| `name`         | `name`             | Role name.        |
| `description`  | `description`      | Role description. |

**Group**

| Veza Attribute | Freshservice Field | Notes       |
| -------------- | ------------------ | ----------- |
| `name`         | `name`             | Group name. |

**Configuration Item (CMDB)**

| Veza Attribute  | Freshservice Field | Notes                                             |
| --------------- | ------------------ | ------------------------------------------------- |
| `cmdb_id`       | `id`               | Native Freshservice asset ID.                     |
| `cmdb_name`     | `name`             | Asset name.                                       |
| `cmdb_type`     | `asset_type_id`    | Asset type name.                                  |
| `cmdb_url`      | `display_id`       | Derived link to the asset in the Freshservice UI. |
| `status`        | `asset_state`      | Asset state value (e.g., `In Use`, `In Stock`).   |
| `asset_tag`     | `asset_tag`        | Asset tag or barcode.                             |
| `serial_number` | `serial_number`    | Serial number.                                    |
| `Is Active`     | `asset_state`      | `true` when `asset_state` is `In Use`.            |


---

# 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/freshservice.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.