How to Configure Salesforce Knowledge Ingestion using Generic Adapter

Pre-Requisites

Please ensure the required Salesforce Connector has been created with the necessary permissions. Please refer the Salesforce Access Requirements Doc for details.

Please ensure the API credentials being used for connecting to Salesforce have access to the Knowledge API and necessary objects.

Configuration

Start by creating a new Ingestion under Answers > Ingestion > Internal Knowledge Settings

First, select the Connector created for the ingestion and then provide a name for the ingestion under Ingestion Name.

Then, choose a Domain. The domain is the functional areas of employee service that is most related to the knowledge being ingested for this configuration.

Setup Knowledge Bases in Advanced Mode

In the Advanced mode, in order to ingest knowledge articles from Salesforce Knowledge, we need to select the System as Generic Config.

The Generic Config allows us to ingest content from an API response. This is done by mapping the Response to the Moveworks Internal Attributes.

With this, we are able to call a start URL, fetch the content details and map it internally.

Start URL Configuration

Configure the Start URL to point to your Salesforce Knowledge Article API endpoint:

https://<your-instance>.salesforce.com/services/data/v58.0/query?q=SELECT+Id,Title,UrlName,Summary,ArticleNumber,CreatedDate,LastModifiedDate,LastPublishedDate,ArticleCreatedById,ArticleCaseAttachCount+FROM+KnowledgeArticleVersion+WHERE+PublishStatus='Online'+AND+Language='en_US'+ORDER+BY+LastModifiedDate+DESC+LIMIT+200

Define the Type of content which will be received from the URL. In this case, the Content type being returned is an KNOWLEDGE_URL_TYPE_ARTICLE_LIST which includes the knowledge articles.

Now that we have configured the Start URL and the Type of Content Moveworks can expect, we now need to map the API response to the internal Moveworks Mapping Attributes in order to successfully process the content.

Response Mapper Configuration

Response Mapper for KNOWLEDGE_URL_TYPE_ARTICLE_LIST

Let’s start by mapping the KNOWLEDGE_URL_TYPE_ARTICLE_LIST. You would need to select this as the Type in Response Mapper.

This mapper handles pagination and extracts knowledge articles from the Salesforce response:

1
{
2
  "knowledge_urls": {
3
    "CONDITIONAL()": {
4
      "condition": "NOT(NOT(response.nextRecordsUrl))",
5
      "on_pass": [
6
        {
7
          "parsed_url": {
8
            "base_url": {
9
              "CONCAT()": {
10
                "separator": "\"\"",
11
                "items": "[\"https://<your-instance>.salesforce.com\", response.nextRecordsUrl]"
12
              }
13
            }
14
          },
15
          "type": "\"ARTICLE_LIST\"",
16
          "method": "\"GET\""
17
        }
18
      ],
19
      "on_fail": "[]"
20
    }
21
  },
22
  "knowledge_articles": {
23
    "CONDITIONAL()": {
24
      "condition": "NOT(NOT(response.records))",
25
      "on_pass": "response.records",
26
      "on_fail": "[]"
27
    }
28
  }
29
}

Explanation:

• The knowledge_urls section checks if there’s a nextRecordsUrl in the response (indicating more pages of results)
• If pagination exists, it constructs the next URL to fetch
• The knowledge_articles section extracts the actual article records from the response

Article Mapper Configuration

Once the Response Mapper has been configured, we need to define the final Article Mapper that transforms each Salesforce Knowledge Article into the Moveworks internal format:

1
{
2
  "created_at": "$TIMECONV(CreatedDate)",
3
  "article_id": "Id",
4
  "display_id": "ArticleNumber",
5
  "article_visibility": "\"VISIBLE\"",
6
  "article_class": "\"KNOWLEDGE_PAGE\"",
7
  "article_hierarchies": [
8
    {
9
      "tier_values": {
10
        "CONDITIONAL()": {
11
          "condition": "NOT(NOT(ArticleType))",
12
          "on_pass": "[ArticleType]",
13
          "on_fail": "[\"\"]"
14
        }
15
      },
16
      "tier_label": "\"CATEGORY\""
17
    }
18
  ],
19
  "title": "Title",
20
  "updated_at": "$TIMECONV(LastModifiedDate)",
21
  "article_url": {
22
    "CONCAT()": {
23
      "separator": "\"/\"",
24
      "items": "[\"https://<your-instance>.salesforce.com/lightning/r/Knowledge__kav\", Id, \"view\"]"
25
    }
26
  },
27
  "article_state": "\"PUBLISHED\"",
28
  "body": {
29
    "COALESCE()": {
30
      "items": [
31
        "Summary",
32
        "\"\""
33
      ]
34
    }
35
  },
36
  "author_ids": {
37
    "CONDITIONAL()": {
38
      "condition": "NOT(NOT(ArticleCreatedById))",
39
      "on_pass": "[ArticleCreatedById]",
40
      "on_fail": "[]"
41
    }
42
  },
43
  "language": "\"EN\""
44
}

Field Mapping Explanation:

• article_id: Maps to Salesforce’s Id field (unique identifier for the article version)
• display_id: Maps to ArticleNumber (user-friendly article number)
• title: Maps to the Title field
• body: Maps to the Summary field (or you can use custom fields like Description__c)
• article_url: Constructs the Lightning Experience URL for the article
• article_hierarchies: Maps to ArticleType for categorization
• author_ids: Maps to ArticleCreatedById for author information
• created_at/updated_at: Converts Salesforce timestamps to Moveworks format

Customizing for Your Salesforce Instance

You may need to customize the mappers based on your specific Salesforce configuration:

1. Custom Fields: If you’re using custom fields in your Knowledge Articles (e.g., Custom_Body__c, Department__c), update the mapper accordingly:

1
{
2
  "body": "Custom_Body__c",
3
  "article_hierarchies": [
4
    {
5
      "tier_values": "[Department__c]",
6
      "tier_label": "\"DEPARTMENT\""
7
    }
8
  ]
9
}

2. Multiple Languages: If you support multiple languages, adjust the SOQL query in the Start URL and add language mapping:

1
{
2
  "language": {
3
    "CONDITIONAL()": {
4
      "condition": "Language == \"en_US\"",
5
      "on_pass": "\"EN\"",
6
      "on_fail": {
7
        "CONDITIONAL()": {
8
          "condition": "Language == \"es\"",
9
          "on_pass": "\"ES\"",
10
          "on_fail": "\"EN\""
11
        }
12
      }
13
    }
14
  }
15
}

3. Data Categories: If you use Salesforce Data Categories for organization, you can add them to article_hierarchies:

1
{
2
  "article_hierarchies": [
3
    {
4
      "tier_values": "[ArticleType]",
5
      "tier_label": "\"CATEGORY\""
6
    },
7
    {
8
      "tier_values": {
9
        "CONDITIONAL()": {
10
          "condition": "NOT(NOT(DataCategorySelections))",
11
          "on_pass": {
12
            "MAP()": {
13
              "items": "DataCategorySelections",
14
              "converter": "item.DataCategoryName"
15
            }
16
          },
17
          "on_fail": "[]"
18
        }
19
      },
20
      "tier_label": "\"SUBCATEGORY\""
21
    }
22
  ]
23
}

Advanced Configuration: Filtering Articles

You can modify the Start URL SOQL query to filter which articles get ingested:

Filter by Article Type:

WHERE+PublishStatus='Online'+AND+ArticleType='FAQ__kav'+AND+Language='en_US'

Filter by Date:

WHERE+PublishStatus='Online'+AND+LastModifiedDate>=2024-01-01T00:00:00Z

Filter by Custom Field:

WHERE+PublishStatus='Online'+AND+Include_In_Chatbot__c=true

Adding Permissions for the Salesforce Content

In order to serve ingested knowledge in the Assistant, we need to enable permissions for the Connector which is being used to ingest the Knowledge.

Navigate to Resource Permissions > Permissions Rules under the Core Platform module. Click on Create.

Here we need to define the following fields:

• Strategy Config: Public to all members of the organization
• Integration Id: Name of the connector for Salesforce
• Resource Type: kb
• Action: ACTION_VIEW

Validation

Once you have submitted the Knowledge ingestion configuration, it will kick off the Ingestion pipeline in the background. The status of the same can be tracked on the Ingested Knowledge View.

You can search for the Articles with their Titles here, and if they are listing on the Console, that means they have been ingested successfully.

Troubleshooting Common Issues

1. No Articles Ingested:

   • Verify the Salesforce connector has proper API access
   • Check that the SOQL query returns results when run directly in Salesforce
   • Ensure the service account has “View All” permission on Knowledge Articles

2. Missing Fields:

   • Verify all fields referenced in the Article Mapper exist in your Salesforce Knowledge Article object
   • Check field-level security settings in Salesforce

3. Pagination Issues:

   • Ensure the nextRecordsUrl handling in the Response Mapper is correct
   • Verify the base URL matches your Salesforce instance URL

4. Permission Errors:

   • Confirm the Resource Permission rule is properly configured
   • Verify the Integration Id matches exactly with your connector name