Best Practices for Connectors

Learn the best practices for configuring your connectors

Overview

The following sections provide best practices and tips for configuring a connector with the Aisera Application.

Ensure you choose the correct endpoint.
- The endpoint may vary depending on the Authorization Type and application.
The Authentication Type must be supported by both the third party application and the Aisera Platform.
Ensure the application or service account used for data ingestion has the necessary permissions in the third-party application.
If possible verify that the provided credentials are valid. You can achieve this using tools like Postman.. Follow these links for Supported Auth Types for Custom Integration and Roles and Access Controls.

Decide on your Data Retrieval Type.
- Initially, set it to Incremental if you want to get everything.
Changing the Data Retrieval Type value when you do a Knowledge Base Article (KBA) ingestion may have an impact on the ingested KBAs.
In incremental mode, changing the DS configuration by adding a new field map will only impact newly ingested data. To update existing data, use a date range to update all entries, then switch back to the Incremental retrieval type.
If you perform an initial KBA crawl for the past year and then adjust the date range to the first six months, the KBAs from the last six months (by update date) will be marked for deletion in the Knowledge Review.

A generic connector must have a correct JSON configuration to work to function.
Follow these steps to build a Generic Connector.
- In some cases code changes may be required to fulfill the request. Contact support.aisera.com if you need expert help.
By default, all the field mappings are added when you create a new generic Data Source so you may have to do a cleanup.
Generic connectors support two types of transformations: JavaScript and JOLT.
PRE and POST transformation scripts are supported.

Each Data Source that you can choose in the Aisera Admin UI has default field mapping for every supported content type.
Review the mapping before running a Data Source ingestion for the first time to ensure everything looks good.
Run a diagnostic run to get a sample record.
In the connector logs, find the first object that is fetched from your external system and look at the field mapping.
When cloning a Data Source, be aware that field mappings are not duplicated. You'll need to configure them again in the new Data Source.
If you ingest tickets and you don't see any ticket persisted in the DB, check analytics logs for field mapping errors. It is possible that you have duplicate field mappings. Delete them and run the ingestion again.
Personal Identifiable Information (PII) scrubbing can be set for any field mapping. PII is usually found in title and description fields.
Important fields that are mapped for KBAs are External Id (or Source) and Body. If one of these is missing, the KBAs will not be ingested.
- The External Id field mapping for KBAs is locked and cannot be changed from the UI.
Some connectors have hardcoded mappings and you don't need to add them explicitly. Other connectors have fallbacks for missing mappings.

Check the Data Source Details page for errors. If the crawl fails quickly it usually means you do not have the integration setup correctly.
Always look at the logs and search for errors that may give a clue for what the problem is.
If there is a lot of traffic in the pipeline, it may take time for the entities to show up in the Aisera Admin UI. See also Troubleshooting Data Ingestion.

Try to test your queries before running an ingestion if possible to ensure they are valid.
Do not change the queries between Data Source executions unless you understand both what you are doing and its impact, especially for KB learning.
In most cases connectors support the native query language of the external system, such as Salesforce Query Language (SOQL) for Salesforce.

Never run an ingestion while the pipeline of a previous ingestion is still running, even if the UI permits you to do so.
Avoid running two Data Sources that rely on the same integration or external system simultaneously. It may cause rate limit or authorization errors.
Avoid enabling Bypass Test Connection option in the DS configuration unless advised otherwise by an Aisera engineer. This will cause the connector to succeed even if credentials are wrong and that may have a negative impact in KB learning.
When the ingestion takes a long time, refresh the page to see the progress of the connector.
If the ingestion does not start you may ask help from the Platform team. It may be caused by an internal issue.
The metrics in the Data Source UI may differ from the final count of entities that will be persisted in the data base. For example a KBA that doesn't have any sections will not make it into the data base. See also Troubleshooting Data Ingestion.

KBAs may be in the Needs Review state if the pipeline is still running. Keep an eye on the KBPostProcess stage in the Data Sources UI.
KBAs will not be indexed unless they are committed.
If you notice a lot of deleted documents don't rush to commit. There might be an issue with DS configuration that led to deletion.
If you think that something is wrong with the ingestion you can use the rollback option. This will delete all the uncommitted documents.
If you don’t see the KBAs in Knowledge Review, make sure you have attached the DS to an application and the application is selected. Also check your filters.

To request a new default (OOTB) integration, contact support.aisera.com to create a feature request.

Last updated 3 days ago

Was this helpful?