Manage integrations

An integration is a connectivity between Itential and another system, similar to an adapter. 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. Available views, features, and interactions in the UI can be limited based on user permissions.

Create 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. Alternatively, from the Integration Model details view, you can click the + Integration button.

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

Configure integration properties

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

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 you have been granted permission. Authorization to clone an integration is set with the Integrations - createIntegration permission method. To delete, the Integrations - deleteIntegration method is used.

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

1
"tls":{
2
   "enabled":false,
3
   "rejectUnauthorized":false
4
}

The schema allows an integration instance to have configurable TLS properties to enable or disable the rejectUnauthorized property, allowing you to bypass HTTPS TLS certificate checks.

Integration logging

Integration logging settings are managed individually for each service through Admin Essentials. To update the log level of an integration, open the integration’s instance details page in Admin Essentials and navigate to the Logging tab.

Changes to the log settings of an integration take place immediately and do not require a restart.

If you want to configure logging to an external Syslog system, the Syslog connection properties must first be configured in the integration’s Properties tab using the Advanced View (JSON editor). Once configured, you can adjust the Syslog logging level in the Logging tab.

For related reading, see Logging in Itential Platform, Itential Developers: Log Class, and Integration Models.

Integration responses

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

• Method and action (GET, POST, PATCH, etc.)
• URL (protocol, host, basepath, path)
• Response object (status code, body)
• Debugging information

This feature applies to both on-premises and cloud Itential Platform users.

Output errors

When an integration task is unsuccessful in its call to an external system, an output error is returned along with useful troubleshooting information.

• 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 indicating why the API call could not be made.
• 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

1
{
2
  "ok": true,
3
  "method": "GET",
4
  "url": "http://localhost:8088/pet/7119",
5
  "status": 200,
6
  "statusText": "OK",
7
  "headers": {
8
    "connection": "close",
9
    "content-type": "application/json",
10
    "date": [
11
      "Fri",
12
      "05 May 2023 17:48:43 GMT"
13
    ],
14
    "transfer-encoding": "chunked",
15
    "x-powered-by": "Express"
16
  },
17
  "body": {
18
    "id": 7119,
19
    "tags": [],
20
    "status": "available",
21
    "name": "Lotus",
22
    "photoUrls": [
23
      "https://patchpuppy.com/wp-content/uploads/2022/06/WhatIsanAmericanBlackLab.jpg.webp"
24
    ]
25
  }
26
}

Example: error response body

1
{
2
  "ok": false,
3
  "url": "https://petstore.swagger.io/api/v3/store/invenxxxtory",
4
  "status": 404,
5
  "statusText": "Not Found",
6
  "headers": {
7
    "access-control-allow-headers": [
8
      "Content-Type",
9
      "api_key",
10
      "Authorization"
11
    ],
12
    "access-control-allow-methods": [
13
      "GET",
14
      "POST",
15
      "DELETE",
16
      "PUT"
17
    ],
18
    "access-control-allow-origin": "*",
19
    "cache-control": "must-revalidate,no-cache,no-store",
20
    "connection": "keep-alive",
21
    "content-length": "309",
22
    "content-type": "text/html; charset=ISO-8859-1",
23
    "date": [
24
      "Wed",
25
      "26 Feb 2025 14:02:35 GMT"
26
    ],
27
    "server": "Jetty(9.2.9.v20150224)"
28
  },
29
  "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",
30
  "parseError": {
31
    "name": "YAMLException",
32
    "reason": "end of the stream or a document separator is expected",
33
    "mark": {
34
      "name": null,
35
      "buffer": "...",
36
      "position": 211,
37
      "line": 6,
38
      "column": 55
39
    },
40
    "message": "end of the stream or a document separator is expected (7:56)"
41
  },
42
  "method": "GET"
43
}

If you are still unable to determine the error reason, contact Itential’s Product Support Team for additional troubleshooting help.