Integration Models

An Integration Model is used to define an API for an Integration. A model is loaded into Itential Platform using an OpenAPI specification. Itential Platform supports the OpenAPI 3 specification.

This page walks you through the steps for creating and using Integration Models for Integrations in Admin Essentials. Current limitations with regard to creating an Integration Model are covered also. Please note that available views, features, and interactions in the Platform interface can be limited based on user permissions.

Swagger & OpenAPI Support

Swagger 2.0 and OpenAPI 3.0 are currently supported for creating an Integration Model. A Swagger 2.0 document is converted to an OpenAPI 3 document on import. All OpenAPI 3.0 documents must conform to the OpenAPI v3.0 Specification.

Importing an Integration Model

To create an Integration Model:

1. Login to the Platform and navigate to Admin Essentials.
2. Click the Import icon in the top toolbar to display the Import dialog.
3. Select Integration Model from the dropdown. The Import modal will display.
4. Upload a Swagger or OpenAPI File by drag-and-drop, or use the Click to Browse link to find and select the file you want to upload.

Once the file is uploaded, the Name of the Integration Model will pre-populate from the specification file, along with a description. You can change the description, as needed, to provide specific information for your import and to better communicate what this integration is used for within your platform.

Figure 1: Import Integration Model File

Validating an Imported Integration Model

When you upload a Swagger 2.0 or OpenAPI 3.0 specification file, you can run validation on it using the Validate (✓) button. The OpenAPI specification file must be obtained from the targeted integration. For example, gitlab, amazon, and jenkins provide OpenAPI specifications that properly describe their APIs. Admin Essentials can ingest these files and enable integration with these technologies within IAP.

Figure 2: Import Specification File

Once you click the Import button, and upon successful import, the Integration Model will be added to the collection list in the left sidebar.

When you select the Integration Model from the collection list you will be redirected to the Integration Model Details page.

Figure 3: Integration Model Details

Known Limitations

Described below are known limitations with regard to creating an Integration Model, along with the steps involved in editing after the Integration Model has been imported.

Servers

Currently a single server endpoint is supported for Integrations. If the OpenAPI document has more than one server listed in its servers object, the first server will be selected for use. This endpoint can be updated in the service configuration after the Integration is created.

Example Template for Single Server Endpoint

Any server URL using the OpenAPI path template expressions will have the default value for variables applied. Below is an example of a configuration using multiple servers and URLs using path template expressions.

"servers": [
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-2",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    },
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-1",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    }
]

 
The resulting URL used in the service configuration will be the following:

https://s3.us-east-2.amazonaws.com/

This URL result was determined by taking the first server listed in the array and applying the default variable values to the template URL. Again, this URL can be edited in the service configuration after the Integration is created.

Updating Integration Models

It is currently impossible to edit an integration model after it has been imported into Itential Platform. Instead, the integration model must be deleted and replaced. To do this:

1. Delete all integrations associated with the model.
2. Delete the integration model.
3. Import an updated version of the integration model.
4. Recreate all integrations associated with the model.
5. Recreate any workflow tasks that reference prior integration versions, ensuring that each now references an updated version instead. This must be done on a per-workflow, task-by-task basis.

Integration Models With Dynamic API Key Retrieval

The OpenAPI specification used by Itential Platform now supports specification extensions via x-itential-parameters. Specifically for this feature, Integration Models with an apiKey security schema now support dynamic retrieval via the custom extension x-itential-dynamic-retrieval.

An example integration model with the x-itential-dynamic retrieval extension is presented below.

Notice that x-itential-parameters are defined in the securitySchemes object, and the specific request the parameter is used in is defined by "x-itential-use-in": ["key"].

{
  ...
  "components": {
    "securitySchemes": {
      "apiKeySchemeName": {
        "type": "apiKey",
        "in": "header",
        "name": "my_auth",
        "x-itential-dynamic-retrieval": {
          "method": "POST",
          "url": "https://some.api.com/api/v2/key",
          "responsePointer": "/credentials/key"
        },
        "x-itential-parameters": [
          {
            "name": "password",
            "in": "query",
            "x-itential-use-in": [
              "key"
            ],
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}

In this example, the x-itential-dynamic-retrieval extension allows an integration instance to obtain an apiKey by issuing an HTTP call, performing a CRUD operation (specified by method) to a url, and then querying the response via JSON Pointer.

The expected reponse from calling POST to https://some.api.com/api/v2/key yields an object that looks like this:

{
  "credentials": {
    "key": "the api key value"
  }
}

The responsePointer will query /credentials/key and return the actual API key to use for authentication.

Wth this feature, the Integration instance will attempt to retrieve a new API key in the following scenarios:

• Before executing a task if the Integration has no stored API key value.
• After receiving an HTTP 401 response from an API call. In this scenario, the Integration will automatically retry the call one time (1x) after retrieving a new API key.