# Freshservice Knowledge Base

Index and search Freshservice knowledge articles in Risotto

Connect your Freshservice workspace to Risotto to make your Solutions articles searchable through the AI assistant.

> **Note:** This indexes Freshservice's **Solutions** articles (your knowledge base). To
> index solved **tickets** instead, see [Freshservice
> Tickets](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-tickets).

## Prerequisites

Before setting up the Freshservice Knowledge Base integration, ensure you have:

1. **API Key**: a Freshservice API key. The account that owns the key needs an agent role in the workspace, with the access level **Across the workspace**. An admin role alone cannot read Solutions articles. See [Choose the account for the API key](https://www.tryrisotto.com/docs/integrations/ticketing/freshservice#choose-the-account-for-the-api-key).
2. **The Freshservice URL**: the URL for your Freshservice instance (e.g. `https://mycompany.freshservice.com`)
3. **Workspace ID**: the number of the workspace that contains the articles. Use the number, not the workspace name.

## Setup Process

### Step 1: Get Freshservice API Key

1. **Navigate to Freshservice**

   Go to your Freshservice instance.

2. **Go to your Profile settings**

   Click your profile picture (top-left) and choose **Profile settings**.

3. **Copy your API Key**

   Find **Your API Key** on the right side. Reveal it, copy it, and store it securely.

   > **Tip:** Don't see your API Key? Enable it under **Admin → Agents →** \[your user] **→ Permissions → API Key**.

   > **Warning:** Treat your API key like a password. Store it securely and never share it publicly.

4. **Copy your Workspace ID**

   In Freshservice, go to **Admin → Manage Workspaces** and click the workspace from the list. The URL will look like `https://mycompany.freshservice.com/a/admin/workspaces/2/edit`. The ID in this example is **2**. Enter this number, not the workspace name.

### Step 2: Configure Integration in Risotto

1. **Open Freshservice's page**

   Go to [**Settings** → **Integrations** → **Freshservice**](https://dashboard.tryrisotto.com/settings/integrations/freshservice) and open the **Knowledge** tab. In the **Knowledge base** section, click **Add workspace**. If nothing is connected yet, click **Index a workspace** on the **Freshservice workspaces** row. The **Index a knowledge base** dialog opens.

2. **Configure the Index**

   Enter the following required information:

   - **Site URL**: Your Freshservice instance URL (e.g. `https://mycompany.freshservice.com`). Risotto fills it in from your Freshservice connection when there is one. Start it with `https://`.
   - **Workspace ID**: The Workspace ID (e.g. `2`)
   - **API key**: A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds your Freshservice API key
   - **Excluded categories** (Optional): A comma-separated list of Solutions category IDs that Risotto does not index. To find a category ID, open the category on the **Solutions** page and copy the number after `/categories/` in the URL. When left empty, Risotto indexes the articles in every category of the workspace.
   - **Department** and **Audience**: Choose who gets answers from this index. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

   Risotto names the index after the workspace ID.

   *Product example: The Index a knowledge base dialog on the Freshservice integration page: the site URL and workspace ID, an API key from the vault, the optional excluded categories, Department and Audience, and Index articles.*

3. **Create and Monitor Index**

   Click **Index articles**. The workspace's card on the **Knowledge** tab shows the progress, and so does the **Indexing Jobs** panel on **Knowledge > Indexes**.

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a **Freshservice** index with the same details plus an **Index name**. It is the only place to set **Profile filters**.

## Content Considerations

- Risotto indexes the title and the text of each published article in the workspace's Solutions folders, including the articles in sub-folders. It does not index attachments.
- Risotto does not index draft articles. Publish the article in Freshservice, then click **Reindex**. A reindex also removes a draft that an earlier run indexed.
- Risotto skips the categories in **Excluded categories**. If you exclude every category, the index fails.
- A reindex gets the current version of each article.

## Reindexing Content

To pull in article updates:

1. Navigate to [**Knowledge** → **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your Freshservice Knowledge Base index
3. Click the row's **⋮** menu (**Index actions**), then click **Reindex**

> **Note:** Risotto does not reindex Freshservice Solutions articles automatically, and
> you cannot schedule a reindex. The index keeps the content from its last run.
> Click **Reindex** after large article changes, or on a regular cadence, for
> example once a week. During a reindex, Risotto removes the old content first,
> so answers do not use this index until the run completes.

## Troubleshooting

### The index fails with "No documents found"

Risotto found no articles in the workspace. Make sure that the **Workspace
ID** is the ID of the workspace that contains your Solutions articles.

### The index fails with "Server error while getting workspace"

Freshservice refused a request from Risotto. Risotto shows this message for every refused request, also when the cause is a wrong setting. Do not retry with the same settings. Check these causes:

- The **Workspace ID** is the workspace name (for example, `My Team`) or a number that does not exist. Enter the number from the workspace URL.
- The account that owns the API key has no agent role in the workspace. Freshservice then refuses to show Solutions articles. Add an agent role with the access level **Across the workspace**. See [Choose the account for the API key](https://www.tryrisotto.com/docs/integrations/ticketing/freshservice#choose-the-account-for-the-api-key).
- The **Site URL** or the API key is wrong.

### Some articles are missing from search results

- Make sure that the article is published. Risotto does not index drafts
- Make sure that the article's category is not in **Excluded categories**
- Make sure that the article is in the workspace that you set in **Workspace ID**
- If you changed the article after the last run, click **Reindex**

### Content Verification

After indexing, use [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to confirm Risotto can find and reference your indexed articles.

## Related Integrations

- [Freshservice Tickets](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-tickets) — index solved tickets alongside your Solutions articles
- [Freshservice Service Catalogs](https://www.tryrisotto.com/docs/integrations/knowledge/freshservice-service-catalogs): index your service catalog items
- [Freshservice Integration](https://www.tryrisotto.com/docs/integrations/ticketing/freshservice) — two-way ticket sync

Source: https://www.tryrisotto.com/docs/integrations/knowledge/freshservice
