> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/freshservice.md).

# Freshservice connector

Configure the Freshservice connector to provision agents to Freshservice using the Freshservice REST API and an API key.

The **Freshservice connector** (`freshservice-connector-rabbitmq`) provisions users to [Freshservice](https://www.freshworks.com/freshservice/) over its REST API (`/api/v2`). Users are provisioned as Freshservice **agents**, including their group assignments (`group_ids`).

| Operation                                | Supported                                                               |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| Create / update user (Save)              | ✅ (as a Freshservice agent)                                             |
| Delete user                              | ✅                                                                       |
| Suspend / resume user                    | ✅                                                                       |
| Reset password                           | ✅                                                                       |
| Test connection                          | ✅                                                                       |
| Search, login                            | ❌ Not implemented in the current connector                              |
| Group provisioning (as separate objects) | ❌ Not implemented — manage membership via the agent's group assignments |

{% hint style="warning" %}
The connector ships handler classes for the full operation set, but **search**, **login**, and the standalone **group** operations are empty stubs. Group membership is carried on the agent record (`group_ids`) rather than provisioned as separate group objects.
{% endhint %}

## Use cases

* Managing the **agent lifecycle in Freshservice** — create, update, suspend/resume, and remove agents as part of the joiner/mover/leaver flow.
* Driving **agent group assignments** from OpenIAM entitlements (via `group_ids` on the agent).
* **Not** a synchronization source — the search operation is not implemented, so plan on provisioning *to* Freshservice.

## Versions and compatibility

The end application is **Freshservice**, reached over its REST API. As with the Freshdesk connector, the API version is fixed at **v2** and the host comes from the managed system.

<table><thead><tr><th width="161">Property</th><th>Value</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>Freshservice</td></tr><tr><td><strong>Interface</strong></td><td>Freshservice REST API <strong>v2</strong>, over HTTPS</td></tr><tr><td><strong>Host</strong></td><td>The managed system's URL, for example <code>https://yourcompany.freshservice.com</code></td></tr></tbody></table>

## Prerequisites

* A Freshservice **API key** — it belongs to a Freshservice agent (profile settings → API key); the agent needs privileges to manage agents.
* Network access from the connector host to `https://<your-domain>.freshservice.com` (HTTPS).

## Installing the connector

### Kubernetes

In Kubernetes deployments, the connector is deployed as part of OpenIAM — enable it in your deployment configuration; no separate installation is required.

### RPM

Run the connector JAR directly:

{% code overflow="wrap" %}

```bash
java -Dlogging.level.root=INFO -Dconfpath=/data/openiam/ -jar freshservice-connector-rabbitmq.jar > freshservice.out &
```

{% endcode %}

Or, when managed by systemd, use the connector service unit (`openiam-connector@freshservice-connector-rabbitmq`). To deploy on a separate host, see [Connectors via RPM](/installation/rpm/rpm-single-node/add-a-connector.md).

## Starting, stopping, and restarting

<table><thead><tr><th width="174">Deployment</th><th>Commands</th></tr></thead><tbody><tr><td>RPM (systemd)</td><td><code>systemctl start|stop|restart openiam-connector@freshservice-connector-rabbitmq</code></td></tr><tr><td>RPM (manual)</td><td>Start with the <code>java -jar</code> command above; stop by killing the process.</td></tr><tr><td>Kubernetes</td><td><code>kubectl rollout restart</code> the connector deployment.</td></tr></tbody></table>

## Command-line parameters and properties

The connector is a Spring Boot application. Its defaults ship inside the jar, and you override them in either of two places:

* **An external property file**, read at `${confpath}/conf/properties/freshservice-connector-rabbitmq.properties`. The file is optional, and `confpath` is itself a system property, set with `-Dconfpath=/data/openiam/`.
* **Directly on the command line**, as `-D` arguments, which win over the file.

{% code overflow="wrap" %}

```bash
java -Dconfpath=/data/openiam/ -Dlogging.level.root=INFO -Dorg.openiam.connector.queue=FRESHSERVICE_Connector_1_Request -jar freshservice-connector-rabbitmq.jar
```

{% endcode %}

| Property                                  | Default                                   |
| ----------------------------------------- | ----------------------------------------- |
| `org.openiam.connector.queue`             | `FRESHSERVICE_Connector_1_Request`        |
| `org.openiam.connector.queueResponseName` | `FRESHSERVICE_Connector_1_Response`       |
| `org.openiam.connector.name` / `.type`    | `Freshservice` / `Freshservice Connector` |

The connection details themselves are **not** set here — they are managed system parameters, covered under [Configuring the managed system](#configuring-the-managed-system).

## Verifying the connector is running

{% stepper %}
{% step %}
In the Webconsole, open the managed system — the **Running connector status** indicator must be green.
{% endstep %}

{% step %}
Click **Test Connection** — it must return success.
{% endstep %}

{% step %}
In the RabbitMQ management console, confirm the `FRESHSERVICE_Connector_1_Request` queue exists and has a consumer.
{% endstep %}

{% step %}
Check the connector log for startup errors.
{% endstep %}
{% endstepper %}

## Troubleshooting

| Symptom                                             | Likely cause                                                        | Resolution                                                                          |
| --------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Connector never receives messages                   | Queue-name mismatch                                                 | The connector record's queue must equal `FRESHSERVICE_Connector_1_Request` exactly. |
| Operations fail with `401`/`403` from Freshservice  | Wrong API key, or the key's agent lacks agent-management privileges | Regenerate/verify the API key and the agent's role.                                 |
| Search/login "appear to succeed" but return nothing | Those operations are unimplemented stubs                            | Expected — see the operations table above.                                          |
| Group create/delete does nothing                    | Standalone group operations are stubs                               | Manage membership through the agent's `group_ids` instead.                          |

See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes).

## Registering the connector in OpenIAM

Register the connector under **Provisioning → Connectors** and attach it to the managed system — see [Registering the connector](/administration-guide/lifecycle/connectors-and-managed-systems.md). Match the queue name exactly:

## Configuring the managed system

<table><thead><tr><th width="189">Managed-system field</th><th>Value</th></tr></thead><tbody><tr><td><strong>URL</strong></td><td>Your Freshservice domain base URL, e.g. <code>https://&#x3C;your-domain>.freshservice.com</code>. The connector calls <code>/api/v2/agents</code>.</td></tr><tr><td><strong>Password</strong></td><td>Your Freshservice <strong>API key</strong>, sent in the <code>Authorization</code> header.</td></tr></tbody></table>

## Attribute mapping and policy map

Map OpenIAM user attributes to the Freshservice agent fields (name, email, and group assignments via `group_ids`) in the managed system's [policy map](/administration-guide/lifecycle/policy-map.md).

## Reconciliation and synchronization

The search operation is **not implemented** in the current connector, so Freshservice cannot serve as a synchronization source — provision *to* Freshservice rather than importing from it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/connector-configuration/freshservice.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.