Table of Contents

How to Connect Preseem to your Sonar System

Mitchell Paul-Soumis Updated by Mitchell Paul-Soumis

Read Time: 2 mins

Preseem can query Sonar to pull information about accounts, plans and network sites, including APs, into Preseem. This enables Preseem to measure QoE metrics for each site and customer, and in the future, to apply its Active Queue Management algorithms to maximize the QoE of customers attached to a congested site.

What You Need

To setup the Preseem-Sonar integration:

  1. Provide Sonar with your Preseem API Key, and enable the integration
    1. This will allow Preseem to deliver information back to Sonar
  2. Provide Preseem with a Read-Only user account from your Sonar instance
    1. This allows Preseem to query Sonar for information, commonly used to determine upload and download limits based on the data service assigned to the account

If you would like to provide Preseem with a Read-Only user, you'll need the following:

  1. The hostname of your Sonar instance
  2. The Personal Access Token of a Sonar user

The user needs to have access to Accounts, Inventory, IPAM, Network, and System in the Sonar environment. We recommend creating a new read-only user account for this specific purpose; instructions for this are provided below.

Connecting the API Integration

The simplest method of connecting Preseem to your Sonar instance is by using the API key provided to you upon signup and configuration of your Preseem account and hardware. Next, log in to your Sonar instance and:

  1. Click on Settings
  2. Click on Integrations
  3. Click on Preseem
  4. Check the box for "Enabled"
  5. Enter in the API Key
  6. Click on Save
If you enter the API key and hit save before enabling it, the API key will be hidden, making it nearly impossible to tell whether an API key has been entered previously.

Providing a Read-Only User

Creating the Read-Only role

Before creating a new account, we'll want to make sure that we have a role with the necessary permissions which will allow Preseem to monitor the network. In Sonar, new roles can be created in two ways:

  1. Through the application GUI, which allows you to view and toggle a series of buttons
  2. Through the GraphQL API

This article will provide instructions for both methods.

Through the User Interface
  1. Access the Settings menu
  2. Click on Security
  3. Click on Roles
  4. Click on Create Role

Next, you need to select which permissions will be required for this role. For Preseem, we'll be creating a role with basic read permissions for Accounts, Inventory, Network, and Serviceable Addresses.

The permissions listed below are designed for Preseem specifically, and you may need additional permissions if building a read-only account for a different purpose.

Module Name

Permission to Enable

Inventory

View all inventory

Accounts

View all account transactions

View accounts and related entities

Account Group

View account groups

Account Status

View account statuses

Account Type

View account types

Address

View serviceable addresses

Address List

View all address lists

Custom Field

View all custom fields

DHCP Server

View all DHCP servers

Inline Device

View all inline devices

IP Assignment

View all IP assignments

Netflow Endpoint

View all Netflow endpoints

Network Site

View all network sites

Preseem

Update Preseem integration

RADIUS Account

View all RADIUS accounts

RADIUS Group

View all RADIUS groups

RADIUS Server

View all RADIUS servers

Service

View Services

Uninventoried MAC Address

View all uninventoried MAC addresses

If you are going to write usage data to Sonar from Preseem, you will need to enable the following Permissions as well:

Module Name

Permission to Enable

Data Usage

Create data usage entries

Data Usage History

Create data usage entries

Update a data usage history entry

Through the GraphQL API

This example makes use of the GraphiQL page accessible within your instance by going to "[instance URL]/graphiql". To make the process easier, we'll be handling it in two parts - the mutation, and the query variables.

If you'd like more information on how to use the GraphiQL interface, take a look at our guide here | How To Use GraphiQL to Understand the Sonar API

Mutation

mutation ($PreseemReadOnly: CreateRoleMutationInput) {
  createRole(input: $PreseemReadOnly) {
    id
    name
  }
}

Query Variables:

{
  "PreseemReadOnly": {
	"name": "Preseem Read Only",
	"applied_permissions": [
		"READ_ALL_INVENTORY",
		"READ_ACCOUNT",
		"READ_ACCOUNT_GROUP",
		"READ_ACCOUNT_STATUS",
		"READ_ACCOUNT_TRANSACTIONS",
                "READ_ACCOUNT_TYPE",
		"READ_SERVICEABLE_ADDRESS",
		"READ_ADDRESS_LIST",
                "READ_CUSTOM_FIELD",
		"READ_DHCP_SERVER",
		"READ_INLINE_DEVICE",
		"READ_IP_ASSIGNMENT",
		"READ_NETFLOW_ENDPOINT",
                "READ_NETWORK_SITE",
		"UPDATE_PRESEEM",
		"READ_RADIUS_ACCOUNT",
		"READ_RADIUS_SERVER",
		"READ_RADIUS_GROUP",
		"READ_SERVICE",
		"READ_UNINVENTORIED_MAC_ADDRESS"
		]
	}
}

If you would like to add the following permissions to the above Query Variable, under applied permissions:

"CREATE_DATA_USAGE",
"READ_DATA_USAGE_HISTORY",
"UPDATE_DATA_USAGE_HISTORY",

Creating the User

Now that we've created the Role, we'll be creating the user who we'll be using to provide access to Preseem. To create a new user:

  1. Click on Settings
  2. Click on Security
  3. Click on Users
  4. Click on Create User

Here's what an example user making use of the Role we created in the previous step would look like:

Creating the User Access Token

Once you have this read-only user configured, log into the account after completing the new user setup sent to the selected email address.

  1. Access the account's profile page
  2. Select the drop down next to Update Info
  3. Select "Create Personal Access token", as pictured below:

Next give the Personal Access token a descriptive name, and note down the token information on the next page.

The token information is only shown once, so make sure to note it down and make backups in case it's needed in the future

Once that's done, provide the token to Preseem in order to link your Preseem Web App with Sonar.

How did we do?

The Sonar Field Tech App

Tower Coverage Integration: Overview

Contact