Managing Integrations

An Integration is a connectivity between Itential and another system (similar to an Adapter). Moreover, it is an instantiation of an Integration Model whereby the Integration uses specific properties from the Model to connect with specific systems. From Admin Essentials, the user interactions for creating and configuring Integrations occur primarily through the dialog views for Integrations and Integration Models, respectively. Please note that available views, features, and interactions in the UI can be limited based on user permissions.

Creating Integrations Using Integration Models

To create an integration, click the plus (+) sign in the top-left toolbar of Admin Essentials to open the Create dialog. Alternately, from the Integration Model details view, you can click the + Integration button.

Select the appropriate Integration Model and click the Save button. You will be redirected to another dialog where you select the appropriate Integration Model to create and configure your Integration.

Figure 1: Create Integration

Figure 2: New Integration from Integration Model

Configuring Integration Properties

From the details view, if your integration has properties to edit, they will be displayed here in a form under the Configuration tab. If not, properties can be configured and edited in the Advanced View (if the user has been granted permission through the generic Integrations - updateIntegration method). The Advanced View editor is enabled (displayed) by using the toggle switch in the upper-right corner.

Figure 3: Integration Properties

From the Advanced view, the More button (stacked dots icon) next to the toggle switch can be used to clone or delete an integration if the user has been granted permission. Authorization to clone an integration is set with the Integrations - createIntegration permission method. To delete, the Integrations - deleteIntegration method is used.

Figure 4: Advanced Configuration View

SSL Configuration for Integrations

Itential has created two SSL configuration properties for Integrations: enabled and rejectUnauthorized. These properties are used when making integration requests to a service even if it has an invalid TLS certificate.

Property Schema

"tls":{
   "enabled":false,
   "rejectUnauthorized":false
}

The schema allows an integration instance to have configurable TLS properties to enable/disable the rejectUnauthorized property. This will allow users to bypass HTTPS TLS certificate checks.

Integration Logging

Log Levels are controlled by configurations within Admin Essentials. Increasing the size of the log level under the Logging tab will impact all of Itential Platform, not just Integrations.

Moreover, if the Syslog properties are not configured in the Advanced View of the Integration, the user will be unable to change that property in the Logging tab.

Integration Responses

Whenever an integration makes a call, and that call fails to connect to an external system, the information that's necessary for troubleshooting the failed integration task is now viewable by Itential Platform users, including the:

• Method and action (GET, POST, PATCH, etc)

• URL (protocol, host, basepath, path)

• Response object (status code, body)

• Debugging information

This feature enhancement applies to both on-premises and cloud Itential Platform users to ensure they receive the diagnostic information that's needed for troubleshooting when an integration call fails.

Output Errors

When an Integration task is not successful in its call to an external system, an output error is returned along with useful information to help troubleshoot the error that is presented.

• When the Integration task fails because it does not have the proper information to make the API call, it will output the error as a string, with a message to indicate why it could not make the API call.

• When the Integration task fails because the API call was processed by the target server and returned a failure, it will output the error as an object with fields in its response body.

Response Body

Itential has standardized the response body of an Integration task with additional information to help understand why an output error was returned.

Example: Success Response Body

A Successful sample response body is presented below.

{
  "ok": true,
  "method": "GET",
  "url": "http://localhost:8088/pet/7119",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "connection": "close",
    "content-type": "application/json",
    "date": [
      "Fri",
      "05 May 2023 17:48:43 GMT"
    ],
    "transfer-encoding": "chunked",
    "x-powered-by": "Express"
  },
  "body": {
    "id": 7119,
    "tags": [],
    "status": "available",
    "name": "Lotus",
    "photoUrls": [
      "https://patchpuppy.com/wp-content/uploads/2022/06/WhatIsanAmericanBlackLab.jpg.webp"
    ]
  }
}

Example: Error Response Body

A sample Error response body is presented below.

{
  "ok": false,
  "url": "https://petstore.swagger.io/api/v3/store/invenxxxtory",
  "status": 404,
  "statusText": "Not Found",
  "headers": {
    "access-control-allow-headers": [
      "Content-Type",
      "api_key",
      "Authorization"
    ],
    "access-control-allow-methods": [
      "GET",
      "POST",
      "DELETE",
      "PUT"
    ],
    "access-control-allow-origin": "*",
    "cache-control": "must-revalidate,no-cache,no-store",
    "connection": "keep-alive",
    "content-length": "309",
    "content-type": "text/html; charset=ISO-8859-1",
    "date": [
      "Wed",
      "26 Feb 2025 14:02:35 GMT"
    ],
    "server": "Jetty(9.2.9.v20150224)"
  },
  "text": "<html>\n<head>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"/>\n<title>Error 404 Not Found</title>\n</head>\n<body><h2>HTTP ERROR 404</h2>\n<p>Problem accessing /api/v3/store/invenxxxtory. Reason:\n<pre>    Not Found</pre></p><hr><i><small>Powered by Jetty://</small></i><hr/>\n\n</body>\n</html>\n",
  "parseError": {
    "name": "YAMLException",
    "reason": "end of the stream or a document separator is expected",
    "mark": {
      "name": null,
      "buffer": "<html>\n<head>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"/>\n<title>Error 404 Not Found</title>\n</head>\n<body><h2>HTTP ERROR 404</h2>\n<p>Problem accessing /api/v3/store/invenxxxtory. Reason:\n<pre>    Not Found</pre></p><hr><i><small>Powered by Jetty://</small></i><hr/>\n\n</body>\n</html>\n",
      "position": 211,
      "line": 6,
      "column": 55,
      "snippet": " 4 |  ... nd</title>\n 5 |  ... \n 6 |  ... </h2>\n 7 |  ... i/v3/store/invenxxxtory. Reason:\n-----------------------------------------^\n 8 |  ... </p><hr><i><small>Powered by Jetty://</small></i><hr/>\n 9 |  ... "
    },
    "message": "end of the stream or a document separator is expected (7:56)\n\n 4 |  ... nd</title>\n 5 |  ... \n 6 |  ... </h2>\n 7 |  ... i/v3/store/invenxxxtory. Reason:\n-----------------------------------------^\n 8 |  ... </p><hr><i><small>Powered by Jetty://</small></i><hr/>\n 9 |  ... "
  },
  "method": "GET"
}