> 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-ticketing.md).

# Freshservice ticketing system

Connect OpenIAM's ticketing integration to a Freshservice account, so ticket rules create, update and close Freshservice tickets through the Freshservice API v2 with an agent's API key.

The **ticket connector** (`ticket-connector-rabbitmq`) lets OpenIAM open, update and close tickets in an external ticketing system when something happens to a person or their access — an access request submitted, approved or rejected, a user terminated, a provisioning operation failed. One connector serves Jira, ServiceNow and Freshservice; the managed system's **Ticketing system** field picks which one. This page covers **Freshservice**: the connector talks to the Freshservice API v2 (`/api/v2`) of your account and writes ordinary Freshservice tickets.

This is not the [Freshservice connector](https://docs.openiam.com/connector-configuration/freshservice.md), which provisions OpenIAM users to Freshservice as agents. The two are separate connectors and can run side by side.

Data flows one way for content (OpenIAM writes the ticket) and back for status: the ticket's status, assignee and last update are read back for display in OpenIAM. Nothing that happens to the ticket in Freshservice changes access in OpenIAM.

| Operation                                 | Supported                                                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Create ticket                             | ✅ as an incident, or as the ticket type a rule sets in `type`                                                                         |
| Update ticket (fields and a private note) | ✅                                                                                                                                     |
| Close / move a ticket (transition)        | ✅ by setting its **Status**, optionally with other fields                                                                             |
| Read ticket status back (sync-back)       | ✅ status, assignee (agent), last update; Freshservice has no resolution field                                                         |
| Test connection                           | ✅                                                                                                                                     |
| Labels                                    | ✅ as Freshservice **tags**, added and never removed                                                                                   |
| Service catalog requests                  | ❌ OpenIAM does not place service catalog requests                                                                                     |
| User and group provisioning               | ❌ Not what this connector is for — use the [Freshservice connector](https://docs.openiam.com/connector-configuration/freshservice.md) |

The acronyms on this page — REST, API and JSON — are defined in the [*Glossary*](https://docs.openiam.com/glossary.md#acronyms).

## Versions and compatibility

The connector uses the Freshservice **API v2** at `https://<account>.freshservice.com/api/v2`. It needs no app from the Freshworks marketplace. Freshservice is a cloud service with no version of its own, so **Test connection** reports the deployment type `Cloud` and no version.

The account URL must be the `freshservice.com` address of the account. Freshservice serves its API on that address only, so a custom domain (a CNAME such as `helpdesk.example-corp.com`) does not work as the managed system's address.

Accounts with workspaces and accounts without them both work; see [Workspaces](#workspaces).

## Prerequisites

* [ ] The ticket connector is running — it is the same connector as for Jira and ServiceNow. If OpenIAM already creates Jira or ServiceNow tickets, nothing more is installed.
* [ ] Network access from the connector host to `https://<account>.freshservice.com` on port 443.
* [ ] A dedicated Freshservice **agent** for OpenIAM, not a person's, and that agent's **API key** (in Freshservice, the agent's profile settings). The key carries the agent's permissions, so the agent's role needs to:
  * view, create and edit tickets, and add notes to them, in every workspace your rules write to;
  * optionally, read the ticket form fields, list the workspaces and view agents. Without these the connector still works: it uses Freshservice's default statuses and priorities, offers only the primary workspace and no field list in the rule editor, and shows an agent's id instead of the name as the assignee. Without the right to list workspaces, the synchronization also reads the primary workspace only.
* [ ] A **requester** for the tickets: an e-mail address Freshservice accepts as a requester, such as a shared `it-requests@example-corp.com` mailbox. Freshservice will not create a ticket without one; see [The requester of a ticket](#the-requester-of-a-ticket).

## Installing the connector

The ticket connector ships as the container image `ticket-connector-rabbitmq`. Install it once per environment; Jira, ServiceNow and Freshservice managed systems share it.

| Deployment | What to deploy                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Kubernetes | The `ticket-connector-rabbitmq` Helm chart (a StatefulSet of the same name). It ships with `openiam.replicas: 0`; set the replica count to `1` |
| Docker     | The `ticket-connector` service of the OpenIAM Docker compose stack                                                                             |

## Starting, stopping, and restarting

| Deployment | Commands                                                        |
| ---------- | --------------------------------------------------------------- |
| Kubernetes | `kubectl rollout restart statefulset/ticket-connector-rabbitmq` |
| Docker     | `docker compose restart ticket-connector`                       |

## Command-line parameters and properties

The connector is a Spring Boot application and takes no connector-specific command-line flags. Its settings are read from `${confpath}/conf/properties/ticket-connector-rabbitmq.properties`, which overrides the defaults below.

| Property                                  | Default | Purpose                                                                                 |
| ----------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `ticket.freshservice.connect.timeout.ms`  | `10000` | TCP connect timeout to the account                                                      |
| `ticket.freshservice.read.timeout.ms`     | `30000` | How long to wait for an answer; raise it if large searches time out                     |
| `ticket.freshservice.max.retries`         | `3`     | Retries after a rate limit (`429`), a server error or an I/O failure; `0` disables them |
| `ticket.freshservice.retry.base.delay.ms` | `1000`  | First wait between retries; doubles on every retry                                      |
| `ticket.freshservice.retry.max.delay.ms`  | `60000` | Cap of any single wait, including the `Retry-After` Freshservice sends                  |

Freshservice limits the API calls an account may make per minute, and the limit depends on the plan. When the account is over it, Freshservice answers `429` with a `Retry-After` time; the connector waits that long, up to the cap above, and tries again. The cap is 60 seconds for Freshservice, twice the Jira and ServiceNow default, because Freshservice counts per minute.

A ticket **create** is never repeated after a server error or an I/O failure, because Freshservice may already have created the ticket. OpenIAM's own retry looks for the ticket's `openiam-<subject key>` tag first and adopts the ticket it finds instead of creating a second one.

## Verifying the connector is running

1. Open the Freshservice managed system and select **Test connection**. It reports success once Freshservice accepts the API key and the key may read tickets.
2. Create a ticket rule for a test trigger, such as **Request submitted**, and submit one request.
3. Check that the ticket appears in Freshservice, and that it carries the tags `openiam` and `openiam-<request id>`.
4. Open **Tickets** on the managed system: the ticket shows its key, such as `INC-42`, and links to the ticket.

## Troubleshooting

| Symptom                                                                                                                                                                                          | Likely cause                                                                                                          | Resolution                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Freshservice rejected the credentials (HTTP 401)`                                                                                                                                               | Wrong or revoked API key, or an agent password entered instead of the key                                             | Copy the API key from the agent's profile into **API key** and save                                                          |
| `Managed system <id> has no password (API key) set`                                                                                                                                              | **API key** is empty                                                                                                  | Enter the API key and save                                                                                                   |
| `Freshservice denied access (HTTP 403)`                                                                                                                                                          | The agent's role may not do this, or not in this workspace                                                            | Give the agent's role the ticket permissions in [Prerequisites](#prerequisites)                                              |
| `Freshservice resource not found (HTTP 404)`                                                                                                                                                     | The account URL has a path or names the wrong account, or the ticket was deleted                                      | Enter the bare `https://<account>.freshservice.com` address                                                                  |
| `Freshservice rate limit exceeded (HTTP 429) after 4 attempts`                                                                                                                                   | The account used up its API calls for the minute                                                                      | Nothing to fix in OpenIAM; the delivery is retried later. Lower the number of rules on the system, or raise the plan's limit |
| `A Freshservice ticket needs a requester: set the rule's additional field email (or requester_id), the managed system attribute TICKET_REQUESTER_EMAIL or an e-mail as the managed system login` | No requester for a new ticket                                                                                         | Set one of the three; see [The requester of a ticket](#the-requester-of-a-ticket)                                            |
| `Freshservice has no workspace '<name>'; use 'default', a workspace id or one of: …`                                                                                                             | The rule's project names a workspace that does not exist or is not active                                             | Use a name from the list, the workspace id, or `default`                                                                     |
| `Priority '<value>' is not a Freshservice priority; available: …`                                                                                                                                | The rule's priority is not on the workspace's ticket form                                                             | Use a priority from the list in the message, or its number                                                                   |
| `Status '<value>' is not a status of Freshservice ticket <key>; available: …`                                                                                                                    | The rule's transition names a status the workspace does not have                                                      | Use a status from the list in the message                                                                                    |
| `Freshservice transition '…' is not '<state> \| <field>=<value> \| ...'`                                                                                                                         | Malformed transition                                                                                                  | Write the status first, then `\|`-separated `field=value` pairs                                                              |
| `Freshservice rejected the request (HTTP 400): <field>: <message>`                                                                                                                               | Freshservice refused a field — a required field of the form is missing, or a value is not one of a dropdown's choices | Set the field the message names as an additional field, with a value the form accepts                                        |
| `The Freshservice filter query is <n> characters long; Freshservice accepts 512: …`                                                                                                              | A search's native query, together with OpenIAM's tag conditions, is too long                                          | Shorten the query                                                                                                            |
| The rule editor offers only **Primary workspace**                                                                                                                                                | The account has no workspaces, or the agent may not list them                                                         | Expected on an account without workspaces; otherwise type the workspace id or name                                           |
| The rule editor offers no additional fields                                                                                                                                                      | The agent may not read the ticket form fields                                                                         | Type the field names; see [Attribute mapping and policy map](#attribute-mapping-and-policy-map)                              |

For problems common to all connectors — the queue, the connector not starting — see [Connector troubleshooting](https://docs.openiam.com/connector-configuration/4-troubleshootingconnector.md).

## Registering the connector in OpenIAM

The ticket connector is registered out of the box as **Ticket Connector** with the queue **base name** `TICKET_Connector_1`. Nothing needs to be registered for Freshservice.

That base name is what the connector record holds; it is not a queue. The queues derived from it are `TICKET_Connector_1_Request`, which the connector consumes, and `TICKET_Connector_1_Response`, which it replies on. Look for those two names when checking the broker — searching for the base name alone finds nothing.

## Configuring the managed system

**Provisioning → Managed System → New**, at `/webconsole/mngsystem`.

| Field                | Value                                                                                                 |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Connector**        | Ticket Connector                                                                                      |
| **Ticketing system** | Freshservice (stored as `FRESHSERVICE`)                                                               |
| **Account URL**      | `https://<account>.freshservice.com`, without a path                                                  |
| **Agent e-mail**     | Optional: the e-mail address of the OpenIAM agent, for example `openiam-integration@example-corp.com` |
| **API key**          | The agent's API key; it is stored in Vault as the managed system's password                           |

Save, then select **Test connection**.

Freshservice authenticates an API call with the API key alone: the connector sends the key as the user name of HTTP Basic authentication, as Freshservice expects, and never sends the agent e-mail. The agent e-mail is used for two things only: when it is an e-mail address it is the [requester](#the-requester-of-a-ticket) of new tickets that name no other, and it is reported as the account by **Test connection** (`API key` when the field is empty).

**Test connection** reads one page of tickets, which proves both the key and the agent's right to read tickets.

### The requester of a ticket

Every Freshservice ticket has a requester, and Freshservice refuses a ticket without one. The connector takes the first of these that is set:

1. The rule's additional field `email`, `requester_id` or `phone` (the requester's e-mail, Freshservice id or phone number). `email` can be a template, such as `${requester.email}` on a request trigger, so each ticket names the person it is about.
2. The managed-system attribute `TICKET_REQUESTER_EMAIL`, added to the managed system's **Attributes** table, which appears once the managed system has been saved.
3. **Agent e-mail**, when it is an e-mail address.

When none is set, the create fails with `A Freshservice ticket needs a requester: set the rule's additional field email (or requester_id), the managed system attribute TICKET_REQUESTER_EMAIL or an e-mail as the managed system login`.

| Name                     | Value                                                             |
| ------------------------ | ----------------------------------------------------------------- |
| `TICKET_REQUESTER_EMAIL` | The default requester, for example `it-requests@example-corp.com` |

`TICKET_REQUESTER_EMAIL` wins over **Agent e-mail**, so you can keep the agent's own address there and still file the tickets under a shared mailbox.

## Attribute mapping and policy map

A Freshservice managed system gets the same read-only TICKET policy map as Jira and ServiceNow. The connector maps its eight standard attributes to Freshservice ticket fields:

| OpenIAM attribute | Freshservice  | Notes                                                                                                                                                          |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`         | the workspace | `default` for the primary workspace, a workspace id, or a workspace name; see [Workspaces](#workspaces)                                                        |
| `issuetype`       | `category`    | Optional                                                                                                                                                       |
| `summary`         | `subject`     | Required on create                                                                                                                                             |
| `description`     | `description` | Sent as HTML: OpenIAM escapes the text and keeps its line breaks. When it is blank on create, the subject is used, because Freshservice requires a description |
| `priority`        | `priority`    | A name from the workspace's ticket form (`Low`, `Medium`, `High`, `Urgent` by default) or its number (`1`–`4`). A new ticket without a priority is **Low**     |
| `labels`          | `tags`        | See [How labels are kept](#how-labels-are-kept)                                                                                                                |
| `transition`      | `status`      | See [Closing and moving tickets](#closing-and-moving-tickets)                                                                                                  |
| `comment`         | a note        | Added as a **private note**, visible to agents only                                                                                                            |

A new ticket is created with the status **Open**. The ticket key OpenIAM shows is the one the Freshservice agent portal shows: `INC-<id>` for an incident, `SR-<id>` for a service request. Where you type a key, the bare ticket number works too. The **Key** link opens `https://<account>.freshservice.com/a/tickets/<id>`.

**Additional fields** on a rule, and extra rows of the TICKET policy map, set any other field of the ticket:

* **Freshservice ticket fields** are written as such: `email`, `requester_id`, `phone`, `name`, `responder_id` (the agent), `group_id`, `department_id`, `type`, `status`, `priority`, `category`, `sub_category`, `item_category`, `urgency`, `impact`, `source`, `due_by`, `fr_due_by` and `cc_emails`. A value made only of digits is sent as a number for the id and number fields (`requester_id`, `responder_id`, `group_id`, `department_id`, `status`, `priority`, `urgency`, `impact`, `source`). `cc_emails` takes a comma-separated list of addresses.
* **Any other name is a custom field** of the ticket form, by its field name, such as `cost_center`. `true` and `false` are sent as booleans, everything else as text. Prefix the name with `custom_fields.` — `custom_fields.priority` — to set a custom field whose name is also the name of a ticket field.
* A name must be a letter followed by letters, digits and underscores, or `custom_fields.` followed by such a name.

The rule editor lists the fields of the workspace's ticket form, with the fields Freshservice requires marked and the choices of dropdown fields as a list: the requester as `email`, the group as `group_id`, the agent as `responder_id`, the department as `department_id`, the ticket type as `type`, and custom fields by their name. Fields that point to another record — requester, group, agent, department — offer no list of values; enter the id (or, for `email`, the address).

### Workspaces

The rule's project is a Freshservice **workspace**:

| Project                     | Workspace                                                                     |
| --------------------------- | ----------------------------------------------------------------------------- |
| `default`                   | The primary workspace — also the only choice on an account without workspaces |
| All digits, such as `3`     | The workspace with that id                                                    |
| Anything else, such as `IT` | The active workspace of that name, ignoring case                              |

The rule editor lists the account's active workspaces. It offers **Primary workspace** alone when the account has no workspaces or the agent may not list them. Priorities, statuses, categories and the field list are read from the chosen workspace's ticket form.

### How labels are kept

Labels are Freshservice **tags**. Every ticket OpenIAM creates carries two of its own next to the rule's labels:

| Tag                     | Used for                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `openiam`               | Marks the ticket as OpenIAM's                                                                                 |
| `openiam-<subject key>` | Ties the ticket to its subject, so a retried create finds the existing ticket instead of opening a second one |

Freshservice replaces a ticket's whole tag list on every update. So on an update the connector first reads the ticket's tags, adds the labels it lacks, and writes the merged list; it never removes a tag, including one someone added in Freshservice. Do not remove OpenIAM's two tags from its tickets.

### Closing and moving tickets

A rule's transition names the **status** to move the ticket to, by name (`Resolved`) or number (`4`), from the workspace's ticket form: **Open**, **Pending**, **Resolved**, **Closed** and any custom status. Freshservice has no workflow transitions, so the connector sets the status directly. An unknown status fails with the list of the available ones.

Where the account requires more fields with a status — resolution notes when a ticket is resolved, for example — add them after the status, separated by `|`:

{% code overflow="wrap" %}

```
Resolved | resolution_notes=Access granted by OpenIAM | group_id=7
```

{% endcode %}

The fields are written like additional fields, in the same update as the status. The rule's comment is added as a private note after it.

## Reconciliation and synchronization

OpenIAM seeds a synchronization configuration of type **TICKET** for every ticketing managed system; it reads ticket status back for Freshservice as for Jira. Freshservice-specific behavior:

* A synchronization run reads the tickets updated since the last run from the Freshservice ticket list, which compares update times exactly, and keeps those tagged `openiam`.
* A search without a project — the synchronization and the duplicate check before a retried create — reads **every active workspace** the API key can list and merges the results, oldest update first, up to the maximum of the search. So tickets of every workspace are read back, and a retried create finds its ticket in any workspace. A search with a project reads that workspace only (`default` = the primary one). An account with no workspace or one, or whose key may not list them, is searched in the primary workspace only.
* Each extra workspace costs at least one more API call per synchronization run, which counts against the account's rate limit.
* **Ticket status** is the status name, **Assignee** the agent's name — or the agent's id when the agent cannot be read — and **Resolution** stays empty, because Freshservice tickets have no resolution field.
* Every other search — the duplicate check before a retried create, a search with a native query — uses the Freshservice ticket filter. A native query fragment is a Freshservice filter query, for example `priority:3 AND status:2`; it is ANDed with OpenIAM's tag conditions. The filter compares dates by day only, so OpenIAM filters the results to the exact time itself, and Freshservice accepts at most 512 characters for the whole filter query.

## Limitations

* Tickets are incidents unless a rule sets the additional field `type`. Service catalog requests, with their catalog items and variables, are not created.
* Custom number and date fields are sent as text.
* An additional field that renders empty is not sent, so a rule cannot clear a Freshservice field.
* Only the `freshservice.com` address of an account works; custom domains do not.

## Use cases

* **Service desk fulfillment visibility.** Every approved access request opens a ticket in the workspace of the team that owns the application, filed under the requester, and is resolved when OpenIAM finishes provisioning.
* **Leaver follow-up.** A user termination raises a ticket for the asset team to collect hardware, assigned to the asset group with `group_id`.
* **Provisioning failures as tickets.** A failed provisioning operation opens a high-priority ticket for the integration team, so failures are worked in the same queue as everything else.

## Related

* [Ticket integration](https://docs.openiam.com/administration-guide/ticketing.md) — ticket rules, the Tickets screen and how tickets are kept
* [Connect a ticketing system](https://docs.openiam.com/administration-guide/ticketing/connect-a-ticketing-system.md) — the managed system, field by field
* [How fields reach Jira, ServiceNow and Freshservice](https://docs.openiam.com/administration-guide/ticketing/jira-and-servicenow.md#system-freshservice) — the field mapping next to the other two systems
* [ServiceNow ticketing system](https://docs.openiam.com/connector-configuration/servicenow-ticketing.md) — the same connector for ServiceNow
* [Freshservice connector](https://docs.openiam.com/connector-configuration/freshservice.md) — provisioning OpenIAM users to Freshservice as agents
* [Connector troubleshooting](https://docs.openiam.com/connector-configuration/4-troubleshootingconnector.md)


---

# 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-ticketing.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.
