Using the Generic Connector

The Aisera platform provides many pre-built integration and data source parameters. When you start a new integration by choosing Settings > Integration from the left navigation menu of the Aisera Administration application, you see the list of integration options.

If the application that you want to integrate with is not in that list of options, you can create a Generic integration to add your login parameters based on the authentication type that your application is using.

Create the Aisera Service User

The owner of each system that you want to integrate needs to allow the Aisera Service Account User to log into the system to transfer data to the Aisera platform (once or incrementally).

The system owner can restrict the Aisera Service Account User permissions to just Read or just Read/Write, as long as the Aisera Service Account User has Export or Export/Import ability on the data for the User, Ticket, Knowledge Article, and Service Catalog fields of the source system.

Creating a Generic Integration

The Aisera platform supports integrations that include basic authorization and authentication that requires an Access Token. If the data source that you're connecting is not listed in the Integration Search window, you can create a Generic integration, as long as you know which type of authentication your data source uses.

To create a generic integration:

1. Choose Settings > Integrations from the left navigation menu of the Aisera Administration application.

2. Click on the + New Integration button in the upper-right corner.

3. Type, ‘ Generic’ into the New Integration Search field.

4. Click Next.

5. Provide a name and an endpoint for your new integration and click Next.

6. Choose an authentication type from the Auth Type drop-down.

7. The dialog box will change to allow you to enter all of the parameters for the authentication type you want to use.

8. When you’re done entering parameters, select the OK button..

9. As a best practice, choose the OAuthPassword authentication and fill all the fields: Username, Password, Client ID, Client Secret, and Custom Headers (see the format in the screenshot below):

10. Check the Use Raw Token option.

11. Add the URL for the Access Token provided by the company who makes the software that you are integrating with.

Data Sources for Generic Integrations

Now that you’ve created a generic integration, you can configure your Data Sources.

Configure a Data Source

To configure the data source for your generic connector:

1. Choose Settings > Data Sources from the left navigation menu of your Aisera Administration application.

2. Type in the name of the data source you want to use with the generic connector.

3. Select the tasks that you want to perform with the data sources.

4. As an example, we’ll choose Knowledge Based Learning.

This choice causes the dialog box to expand to include learning-specific parameters, such as Schedule.

5. This is the window where you add the name of the generic integration that you created previously. Enter the name of your generic integration in the Integration field.

6. Click Next to continue.

Note: an Incremental setting will crawl for entries that are updated at a later date than the timestamp of the last successful crawl.

7. In the Configuration Tab, fill in the Custom Headers field. These headers should be the same as the headers you used in the Integration Setup.

8. Click Next.

9. Click Next to accept the defaults for Template and Ingestion Configuration.

10. Review the code in the parameters Summary.

11. Click Next to move on to the Overrides and Transformations window.

12. Data Sources for Generic integrations (like Fresh, Ivanti, Kace, and Request Tracker) can use any number of Transformation Scripts through the Override Document Transformations field in the Overrides tab of the Data Source Configuration window.

The following example is an Override Document Transformation (JSON) file:

{

"KnowledgeArticle": [

{

"externalSystemTypeId": 40,

"contentTypeName": "KnowledgeArticle",

"name": "Move RecId to id",

"transformationType": "SCRIPT",

"direction": "JSON2Proto",

"step": "PRE",

"content": "if (15000026857 ==

jsobject.get(\"folder_id\")) {\n\tprint(\"///////////Found valid

folder id: \" + jsobject.get(\"folder_id\"));\n} else

{\n\tprint(\"/////// Rejecting folder_id: \" +

jsobject.get(\"folder_id\"))\n\tjsobject.put(\"id\",

null);\n\tjsobject.put(\"title\",

null);\n\tjsobject.put(\"description\", null);\n}\njsobject;",

"transformationOrder": 1

}

]

}

The Override Document Transformation in the example above, uses the following pattern:

1. It contains a top-level key that specifies the content type to apply to the JS script(s). In this case, it is KnowledgeArticle, but you could use Incident,

Request, User, User Profile, or other entity objects.

2. For each content type, there is an array with JSONObjects, each one referring to a specific transformation.

3. Each transformation JSON file must have key-value pairs to specify the SystemType Id (in this case, "externalSystemTypeId": 40 refers to the Fresh external system).

The System Type ID can be found in the BaseExternalSystemTypeEnum class of the common repo, in theexternal_system_types table of the tenant-store in the database.

Some common Generic Connectors and their Type IDs are mentioned later in this document.

4. contentTypeName denotes the content type (must also be present here), name provides an identifier for the script, transformationType can be either SCRIPT or JOLT, direction should be JSON2Proto when we are ingesting items with a connector, or Proto2JSON if we are performing connector actions (such as Create Ticket).

5. The content field contains the actual script (JS code or JOLT block), properly escaped so it is contained in JSON format.

6. The transformationOrder field is used by the connector to define the order of script executions within the same category (Pre or Post).

Choose OK to complete the Data Source configuration.

Mappings

When a Data Source ingests entries (Tickets, KBs, Users) from a Rest API, the entries are fetched in json format.

Field mappings describe the link between response items in a json entry and the corresponding Aisera value. A field mapping contains a json path that instructs the connector how to extract the useful value from an entry regarding an Aisera or a Custom Field.

Field Mappings can be one of two types:

1. Aisera Mappings

2. Custom Mappings

Some default mappings are loaded, but you must edit them or delete the ones that are not useful. They can also create more mappings if needed.