Freshworks Connector

Overview

The Freshworks Connector supports the ingestion of Users and User Profiles. This page describes the steps and configurations needed to ingest these entities from Fresh’s external system.

By default, a new Fresh Data Source is configured to fetch Requesters.

Prepare

Before setting up the Freshworks connector, ensure you have the required credentials and complete any necessary preparations.

Endpoint

You'll need your base Freshservice URL, which will follow this format: https://<your_company>.freshservice.com.

Authentication

The Freshworks connector supports Basic Authentication with an API Key. For guidance on obtaining an API key, consult the Freshworks authentication documentation. The API Key will serve as the username for the integration step.

Integration Setup

To set up a Freshworks integration:

1. In the Aisera Admin UI navigate to Settings > Integrations

2. Click on + New Integration

3. In the menu, select Freshworks and click Next

   
4. Enter the configuration details and select Next

   Field

   Description

   Name

   The name used to identify the integration

   Endpoint

   The base URL for your Freshservice tenant

   Description

   A description of the integration and it's purpose

   
5. Input the API key for the Username

6. Input DUMMY for the password, then click Next

7. Click OK to save the integration

Data Source Setup

1. In the Aisera Admin UI navigate to Settings > Data Sources

2. Click + New Data Source in the upper right corner

3. Select Freshworks and click Next

4. The required fields will vary based on the selected functions. Enter the configuration details and select Next

   Field

   Description

   Name

   The name used to identify your Data Source

   Functions

   Functions dictate how a data source behaves and what data is ingested into the Aisera platform

   Integration

   The integration with the necessary authentication information for data retrieval

   Schedule

   This determines how often the Data Source will request new data

   Description

   A description of the integration and it's purpose

5. All remaining options are optional. See the section below for more information. Click Next until the window closes to complete the creation of the Data Source

Instructions on ingesting agents will be covered below.

Optional Setup

Bypass Test Connection

Disable if you want to bypass the test connection.

Custom Query

This is used to change filtering logic. All articles will be retrieved by the connector, and then checked against the filters set in this field. Articles which do not pass the set criteria will be discarded.

For example, the following filter can be applied:

{
    "folder_visibility" : 3,
    "status" : 1
}

The connector will now exclusively fetch draft articles visible to agents.

Transformation Script

This field is used to transform data at it is being ingested into the Aisera platform. This script is written in JavaScript.

Post Setup Actions

Please refer to the following sections before running a data source job. Freshworks has a very important distinction between Agents and Requesters. By default, all Freshworks Connector functions are configured to fetch Requesters. If you want to configure your data source to fetch Agents, keep in mind that changing mapped fields and queries in between data ingestion jobs can lead to unexpected behavior.

User Learning

Requesters

By default, the Freshworks Data Source is set to retrieve Requesters from Freshservice when configured to use the Learn Users function. The mappings are loaded by default and are ready to be used.

Agents

To retrieve Agents from Freshservice, configure the Overrides Configuration field in the Datasource settings. Consult your Aisera Team for the necessary JSON override file.

The email-related field mapping will need to be changed for Agents from primary_email to email .

User Profile Learning

To ingest User Profiles, you also need to ingest Users. This means that you must choose both the Users Learning and the User Profiles Learning function in the Functions field for the Data Source. Choosing only the latter will prevent the entries from being properly stored in the database.

Requesters

The Freshworks Data Source is configured by default to ingest Requesters. However, it is necessary to remove the userProfileRoleName field. This field mapping is designed to indicate that a User Learning entry is an agent. You may either change the fixed value or delete it if it is not necessary.

Agents

To use Agents as User Profiles, apply the same JSON Override Configuration used for Agent User entries. Consult your Aisera Team for the necessary JSON override file.

The email-related field mapping will need to be changed for Agents from primary_email to email .

User Groups Learning

By default, the Freshworks Connector ingests Requester Groups when the User Groups Learning function is selected. Consult your Aisera Team for the necessary JSON override file.

Learn KBs with ACL Tags

Documents in Freshworks can contain various attributes that are related to the ACL mechanism.

By default, the Freshworks connector does not ingest tags connected to visibility. You need to use Override configs in a Data Source configuration. Consult your Aisera Team for the necessary Override Configuration and Transformation script.

Data Ingestion

After you've successfully set up your connector, your data will automatically begin syncing according to the schedule parameters defined during the Data Source Configuration step. However, you should perform a manual sync immediately. This initial run will serve two key purposes:

1. It confirms the connector is working properly.

2. It provides an immediate view of the information being ingested into the Aisera Application, allowing you to validate and begin working with the data.

To manually ingest data:

1. In the Aisera Admin UI navigate to Settings > Data Sources.

   
2. Click on the Data Source you wish to manually ingest data from.

3. At the top right of the Data Source Details page, click the Play button to manually ingest data.

   

Review Crawled Knowledge Documents

After the Data Source run completes, the administrator may review all the knowledge documents and ingested sections.

To view all the ingested documents:

1. Navigate to AI Workbench > Review on the left-hand main navigation panel

2. Click the Knowledge Review tab at the top of the page

3. You will see Commit Reviewed and the number of documents that are ingested

4. Since this is the first crawl, all the documents are Reviewed by default

5. Click on Commit Reviewed and click Commit

6. Navigate to SOR > Knowledge window in the left panel and you will see all the ingested documents