Best Practices for Integration

The following sections provide an overview of integration best practices information from the Aisera Development Teams:

Integration Setup

Choose the correct endpoint.
The endpoint may vary depending the Auth Type (such as with Jira and Confluence)
Select an available Auth Type
Fill in the credentials you received from the customer for the integrated application
Verify with the customer that user permissions for the service acct/app are entitled to ingest the required content.
If possible verify that credentials are valid (such as with 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 KB ingestion may have an impact on the ingested KBs
If you change DS configuration (add a new field map) and you are in incremental mode, then only the updated tickets will be impacted. You may use a date range temporarily for the given ingestion, to update all Aisera Entities and then revert back to Incremental (proceed with caution when you perform a KB Learning job).
In case you do an initial KB crawl for the last year and then change the date range for the first six months, the ingested KBs of the last 6 months (based on their update date) will be marked for deletion in Knowledge Review.

For more information about Aisera Entities, see Roles and Access Controls.

A generic connector must have a correct JSON configuration to work, otherwise it will do nothing.
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 (Aisera Entity Object)
Review the mapping before running a DS 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.
Pay attention when you clone a Data Source. Field mappings are not cloned currently, so you need to set them up again after cloning in the cloned DS.
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.
PII scrubbing can be set for any field mapping. PII is usually found in title and description fields.
Important fields that are mapped for KBs are External Id (or Source) and Body. If one of these is missing, the KB will not be ingested.
The External Id field mapping for KBs 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. For more information about Aisera Entities, see Roles and Access Controls.

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 (Authorization errors, bad queries, etc)
If there is a lot of traffic (time lag) 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 in between data source executions if you are not sure what you are doing and what the impact will be (especially for KB learning)
In most cases connectors support the native query language of the external system (i.e. SOQL for Salesforce)

Never run an ingestion while the pipeline of a previous ingestion is still running (even if the UI permits to do so).
Avoid running two data sources that rely on the same integration (or the same 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 the engineering team. This will cause the connector to succeed even if credentials are wrong and that may have a negative impact in KB learning.
If the ingestion does not start you may ask help from the Platform team, it can be an Airflow issue.
When the ingestion takes long, refresh the page often to see the progress of the connector.
The metrics in the Data source UI may differ from the final count of entities that will be persisted in the db. For example a KB that doesn’t have any sections will not make it to the db.
Do not compare ingestion metrics between different instances (i.e. dev vs prod) or data sources that have different configurations. See also Troubleshooting Data Ingestion.

KBs may be in Needs Review state if the pipeline is still running (keep an eye on KBPostProcess stage in data sources UI)
KBs 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 KBs 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 8 months ago