How to track connector errors and outages using a location-based workflow.

Sam Peirce
Sam Peirce Administrator admin
edited November 2021 in Best Practices

Keeping track of your connector errors is vital to successful management of data in Oomnitza. While checking connector status manually is a valid option, our APIs and Workflow engine allow you to track and automate notifications based on connector statuses.

Before we get started, this is a fairly complex method of using Oomnitza's Workflow engine, so if you have any questions or need assistance settings this up, don't hesitate to ask here or reach out to your customer success manager or to [email protected]

Oomnitza Connector APIs

Oomnitza has two APIs that allow for reporting on connector status, as detailed below:

Connector Logs:
Provides a summary of each connector run (for a given connector) including number of updates, errors, added objects, and skipped objects.

URL: https://{instance}.oomnitza.com/api/v3/connector_run_logs/{connector-id}

Payload:
[
    {
        "portion_id": 15821,
        "portion_correlation_id": "6013cbd4-1060-4c1b-8729-fd4b600e0ac6",
        "start_time": 1631231882.0,
        "end_time": 1631231882.0,
        "connector": "google test child",
        "is_media_storage_service": false,
        "status": "Completed with errors",
        "deployment": "cloud",
        "ipv4_address": "127.0.0.1",
        "added_records_count": 0,
        "updated_records_count": 0,
        "skipped_records_count": 0,
        "error_logs_count": 1
    }
]


Connector Error Details:
Provides a more detailed view of each connector run, including specific details on each error

URL: https://{instance}.oomnitza.com/api/v3/connector_run_logs/connectors/{portion_id}

Payload:
{
    "connector": "Jamf Test",
    "deployment": "cloud",
    "start_time": 1629942003,
    "end_time": 1629942003,
    "status": "Completed with errors",
    "ipv4_address": "127.0.0.1",
    "objects":
    {
        "failed": 2
    },
    "logs":
    {
        "failed":
        [
            "Failed to process the mapping value: {{[email protected]}}. The error is: unexpected char '@' at 9",
            "Failed to process the mapping value: {{[email protected]}}. The error is: unexpected char '@' at 9"
        ]
    },
    "file_attachment": null
}

By utilizing these workflows, we can pull information on our connector runs into other areas of the software to take advantage of Oomnitza's workflow engine. This in turn, can be used alongside conditional thresholds, notifications, updates, and other functions to send complex alerts to Oomnitza's diverse means of connecting with external systems.

The Basic Template

A standard workflow for tracking includes the following steps:

  1. We run the connector for a single location on a regular schedule that lines up with connector runs.
  2. Using the Connector Logs API detailed above, we retrieve information on the status of the connector
  3. (Not Shown) We add any kind of desired thresholds, transformations, or branching paths to determine how and when alerts are send.
  4. We notify users of the connector status.

We'll break down each step below.

Preconditions

First, we'll need a place to store this information. We recommend creating a Location specific for storing connector information, and create the following custom fields to store connector information:

When creating the location, it's also beneficial to have a field that stores the Connector ID. With the connector ID stored as part of the Location, you can set up separate locations for each connector you wish to monitor, and automatically populate the connector ID when generating the API call, as seen below.

The Begin Block

The begin block should run on a schedule for a single location where you plan to manage connectors from, or from a small set of locations configured for individual connectors. The timing of the run should be set to run approximately 2-3 hours after the expected connector run, to ensure completion of the connector sync. This will vary based on the amount of data being passed over by the connector.

The API Block

Information

The API block is the key to retrieving data from the connectors. Connector data can be retrieved through an HTTP GET request to the following endpoint (using Oomnitza credentials):

https://{{instance_name}}.oomnitza.com/api/v3/connector_run_logs/{{connector_id}}?limit=1

Using the following variables:

instance_name: The name of your Oomnitza instance, such as company.oomnitza.com.

connector_id: The ID of the connector you wish to retrieve data from. This can be retrieved by navigating to your connector and examining the URL, which should look like this:

https://instance.oomnitza.com/settings/connectors?id=14&type=assets

Note the section that reads "connectors?id=14". The connector ID is the number that follows the equals sign.

Authorization

This workflow can be run with an Oomnitza API token with read access to settings. This credential should be added to the Oomnitza Vault.

Response

The following mappings will allow you to retrieve, status, start time, and counts of errors, skips, updates, and additions from the most recent connector run.

{{response.0.status}}
{{(0+response.0.start_time)|int}}
{{response.0.error_logs_count}}
{{response.0.skipped_records_count}}
{{response.0.updated_records_count}}
{{response.0.added_records_count}}

Filtering and Notifications

Once we've retrieved connector information, we can determine when and how it gets sent. This can be done in a variety of ways. I've listed a few below, but there's plenty of room for creativity:

  • No filtering added, and notifications can be sent every time the workflow checks the connector status.
  • A conditional threshold looks at the number of errors and sends them if they exceed a certain number.
  • A conditional threshold check the status and sends an alert if it's anything other than "Complete"
  • A conditional threshold examines the start date and sends an alert if an unexpectedly large amount of time has past since the last start date.
  • A conditional threshold can look if an unusually low number of devices have been updated and send an alert.

Additionally, Oomnitza's flexibility to send notifications allows the notifications of errors or disruptions to be sent via email, via slack, or as a ticket in the ticketing system of your choice.

Conclusion

I hope everyone finds this helpful. Again, this is a fairly complex method of using Oomnitza's Workflow engine, so if you have any questions or need assistance settings this up, don't hesitate to ask here or reach out to your customer success manager or to [email protected]

Comments

  • jcm
    jcm Member

    Hi Sam,

    We're interested in implementing this feature!

  • Sam Peirce
    Sam Peirce Administrator admin

    Hey @jcm! I'm glad to hear that you're interested. Let's take some time to set it up on our upcoming call.

  • jcm
    jcm Member

    Hi Sam,

    Thank you for the quick response!

    -JCM