17.6 Integrators

17.6.1 Creating an Integrator Instance

An Integrator is a configured instance of an Integrator plug-in. There can be one or more Integrator instances with different parameters or settings using an Integrator plug-in.

The specific steps to configure an Integrator instance depend on the type of Integrator, and those steps are described in detail in documents that come with the Integrators. Documentation for installed plug-ins can be viewed by selecting an Integrator in the Integrator Manager and clicking Help.

17.6.2 Editing an Integrator Instance

  1. Click Tools > Integrator Manager. The Integrator Manager window displays.

  2. Select an Integrator from the left panel. Edit the Integrator instance information by using the Basic Information, Connection Settings, and the Integrator Properties tab.

  3. Click Save after you edit the information.

17.6.3 Deleting an Integrator Instance

An Integrator instance cannot be deleted if it is currently associated with an action. To delete an Integrator instance, you must first delete or modify any actions that are associated with it.

  1. Click Tools > Integrator Manager. The Integrator Manager window displays.

  2. Select an Integrator from the left panel, then click the Delete icon to delete an Integrator instance.

17.6.4 Integrator Connection Status

  1. Click Tools > Integrator Manager. The Integrator Manager window displays.

  2. Click the Refresh health of all Integrators button. The Integrator Connection Status window displays.

    The server performs a test of the Integrators in the actual service where the Integrators are used when actions are executed.

  3. Click OK.

17.6.5 Viewing Integrator Health Details

  1. Click Tools > Integrator Manager. The Integrator Manager window displays.

  2. Select an Integrator from the left pane.

  3. Click See Details. The Refresh Health Information window displays.

    The Health screen displays the Refresh Health State, Time of last occurrence, its method calls, and the related events of the selected Integrator configuration.

    • Integrator API Calls: Indicates the status of count and time of both the connection and the method calls used from the API of the selected Integrator. For more information on JavaScript plug-ins, see Section 17.1, Action Manager.

      • Call Success Count: Displays the count for the number of times the connection was established successfully and the methods were called successfully from the API. Time of Last Occurrence displays the time when the connection and the method call were successful.

      • Call Failure (but Connection Success) Count: Displays the count for the number of times the connection was established successfully but the methods call failed. Time of Last Occurrence displays the last time when the connection was successful and the method call failed.

      • Connection Failure Count: Displays the count for the number of times the connection failed. Time of Last Occurrence displays the last time when the connection and method call failed.

      NOTE:The most recent time among Connection Success and Call Success Count, Connection Success and Call Failure Count, and Connection Failure and Call Failure Count is reflected in the overall health status for the configured Integrator.

    • Integrator Health Details: The health details are displayed in Integrator Health Details pane. It provides information about the success of the API methods called in the JavaScript action files associated with the Integrator. It provides information specific to the methods called:

      • Method Name: Name of the API method used in the JavaScript.

        Success Count: Number of times the API method executed successfully.

        Time of Last Successful Call: The time at which the method was last successfully executed.

        Average Successful Run Time: Average time to make a successful method call.

        Error Count: Number of times the API method failed.

        Time of Last Error Call: The time at which the method call failed.

        Average Error Run Time: Average time to make a failed method call.

      NOTE:The most recent time among Time of Last Successful Call and Time of Last Error Call is reflected in the overall health status of the method.

17.6.6 Integrator Events Query

When an Integrator faces connection failures, it generates internal audit events. If you want to query these events, you can use an integrator events query to automatically create a filter for the selected Integrator and process a query.

  1. Click Tools > Integrator Manager. The Integrator Manager window displays.

  2. Click See Details. The Refresh Health Information window displays.

  3. Click the Integrator Events button. The Query window displays.

    All the events related to the configured Integrator automatically display in the Query window. You can filter the displayed events by using the filter criteria. For more information, see Section 3.9.3, Historical Event Query.

17.6.7 Using Integrators from Actions

Some actions might require an Integrator in order to make a connection to an external system. You can write or customize JavaScript code that connects to an external system by using the Integrator and executes methods appropriate for the external system. Because all the connection and other configuration information is already configured as part of the Integrator, the code only needs to perform a task on the system with which it integrates.

When writing code that needs to access an Integrator, you must determine how to locate a specific Integrator. You can locate an Integrator in the following ways:

  • Look up an Integrator by its name

  • Look up an Integrator by its ID.

  • Look up a set of Integrators by their service category

  • Retrieve a set of Integrators that have a specific property name or value

  • Retrieve all Integrators and iterate through them to find the required one based on custom logic

After you retrieve the Integrator, you can access the API for the external system to make programmatic calls to achieve the required integration.