Table of Contents

Calix Integration: Overview

Kristen Fiddes Updated by Kristen Fiddes

Read Time: 9 mins

Calix offers a range of solutions to meet your networking needs; however, this article specifically focuses on the integration of an SMx server with your Sonar instance. Utilizing this feature allows you to map data from your instance through to SMx and vice versa. Below, we'll walk you through preparing your instance for the integration and how to configure it, along with individual features you can take advantage of and how best to use them.

Not all Calix ONTs —such as RG versions U4 and U6x— are compatible with this integration, though this may change in the future.

Setting Up the Integration in Sonar

The process to configure the Calix integration is best started with creating the associated inventory items (and their corresponding fields) and the services you intend to use with your Fiber customers. Both of these fields will come up during the final integration modal; however, the services can be returned to and edited at a later time.

Creating Inventory Models

For every ONT you plan to use, you must create its own corresponding Inventory Model. It is recommended that the “Model Name” chosen matches the Profile ID found in SMx; this can be found by logging into your SMx server and navigating to Profiles > Common > ONT. However, if another name is to be used instead, then the Profile ID field of the model should then be set to “Required”. We'll touch on this below.

With the Inventory Model created for your ONT, you can then add the following model fields with the same attributes reflected below:

  1. The Profile ID field.
    In most cases, this field will be left blank, as it'll already be defined by the model name. If the model name does not already match the Profile ID and this field is filled, it will override the model name; in this event, it must match whatever is reflected in the SMx server.
  2. The Serial Number field.
    This field should be set to “Required”. The number inputted should match the hardware serial number of the ONT, e.g., CLCX00003892.
    Some models of Calix ONTs will have an FSAN instead of serial number. These fields are interchangeable in Sonar when adding an item.
  3. The ONT ID field.
    Pre-provisioned ONTs in SMx are mapped from the inventory information in Sonar using the data input into the ONT ID Field. If left blank, Sonar will generate an ONT ID and create a new pre-provisioned ONT in SMx. If the ONT is already defined in the SMx server, entering the ONT ID in Sonar allows Sonar to identify an existing ONT entry in SMx.
  4. The MAC Address field is optional, but recommended.
    If a MAC Address is added to an inventory item, the IP assignment will be applied to the MAC Address. Without the MAC Address field present, the IP will instead be assigned to the inventory item.

Creating Services

As SMx is the management resource for the Calix ONT devices, the actions processed in it are responsible for the speeds and services pushed through to a Calix ONT. Part of the integration process is creating a link between the service template in SMx and a service within Sonar; this allows staff without access to SMx to provision package changes. To set this up, you should already have an existing service template attached to a specific policy map (which details the speeds a customer will be capable of via their ONT) in SMx.

When defining service templates in SMx, each template must map to a unique Policy Map for proper implementation.
  1. Navigate to Settings > Billing > Services and begin to build data service.
    How to create a data service is detailed in our Building a Data Service article | click here
  2. In the populated modal, ensure that the fields for "Download speed in kilobits per second" and "Upload speed in kilobits per second" match what is detailed via the policy map in SMx. While SMx is the management system for ONT speeds, it is helpful to have the correct speeds reflected in your Sonar instance for your staff to reference accurately.
  3. Before creating the new service, ensure that the name is reflective of it being for Fiber customers only (if you offer a range of Internet solutions).

Configuring Your Calix Integration

  1. Navigate to Settings > Networking > Calix and click on "Create Calix Integration":
  2. Complete the required fields across all 4 pages, as detailed below:
    Page 1
    The first page you'll interact with is the "Overview" portion of the integration.

    In most cases, "Use Default Organization ID" will be enabled which uses the ID "Calix". If your Organization ID is different, you are able to toggle this off and a new field will populate where you can input the correct ID.
    If you do toggle this off, duplicate entries may appear in SMx for any ONTs synchronized under the new ID.

    Below "SMX Version", you will select the SMx version you're using. This integration is compatible with V21 and V22.

    The "SMx Endpoint" will be the hostname or IP address of your SMx server. If you're using the default port (18443), adding it to the end of the input is optional (mysmx.org and mysmx.org:18443 are the same). If you have a custom port, add it to the end of the hostname/IP address, for example:
    192.0.2.5:8443
    mysmx.org:8443.

    Finally, the "Username" and "Password" is whatever login you use to access SMx.
    Page 2
    This page is dedicated to the inventory models that will be used alongside your Fiber Network.

    Using the "+Inventory Model Integration" button will populate a new section where you can select the applicable inventory model and attach the already-configured fields of that model.
    Page 3
    This page defines which service templates from SMx will be used with Sonar.

    Underneath the "Service Mapping" header, you can select the Sonar Service previously created for your Fiber customers; only data or voice services can be applied here. Alongside the service chosen, underneath "Calix Service Template Name", you will then input the name of the service template found in SMx.
    The fields here are required.

    Underneath "Delinquency Services", you will input the service template name corresponding with the delinquency template set up within SMx.
    The fields here are optional.

    To identify your existing service templates in SMx, navigate to Templates > Service > AXOS Systems.
    Page 4
    The final page of the Calix Integration includes optional toggles:


    Enable ONT Synchronization is what determines if Sonar can communicate with the Calix SMx server. Without this enabled, the sync will not take place, which also means automatic provisioning will not be possible.

    Alarms Create Logs allows you to toggle whether you want SMx server alarms to populate in Sonar. If this is not enabled, the alarms will only be visible by accessing SMx.

    Alarms Change Device Status, when enabled, allows devices in Sonar to be updated dependent on their status in SMx. So, if the OLT is unable to reach an ONT, it would reflect this in Sonar too.

    Alarms Update IP Assignment acts similarly to the option above, any changes reflected in SMx are pushed through to Sonar if this field is enabled. With this enabled, any IP assignments updated in SMx will automatically populate in Sonar, though a prerequisite here is that the Supernet and Subnet must already be created within IPAM first. If a MAC address field exists, it will assign the IP to the MAC address. Otherwise, it is assigned to the Inventory Item directly.
  3. Once the modal has been completed, you will see a new line item reflected underneath "Integrations". From here, you will click on "Validate Credentials" and if there are no errors with the credentials provided, you will see a successful message in the upper left of your screen.

Following a successful integration, a custom field titled "Calix SMx subscriber ID" will automatically populate on every account in your instance. If you are integrating an SMx with existing subscribers, this field can be used to prevent duplicate subscriber entries. Whatever is listed in the "Account" column in SMx simply has to match with what you're entering into the custom field on a customer's account in Sonar.

For example, if we were to activate an account in Sonar for Brycen Cole, a new subscriber entry would be created in SMx. However, if we add "sonar_account_167" to the "Calix SMx subscriber ID" custom field, then the integration would know to map this subscriber in SMx to the account in Sonar.

Full Synchronization

When initially configuring the integration, you're able to prompt a full synchronization, which will transfer data from Sonar to SMx for any accounts that meet the following conditions:

  1. A Calix-associated service must be assigned to an account (as determined under "Service Mapping" in the integration modal).
  2. An inventory item is assigned to the serviceable address of an account, complete with Serial Number and, if applicable, Profile ID.
  3. The account must be in an active status.

To begin this process, click on the downward-facing arrow alongside "Validate Credentials" and click on "Synchronize". Once selected, it will begin to sync immediately, which can be reflected by the date and time updating below "Sync Started At". The data in SMx will update in real-time as the synchronization processes. Full Synchronization is capable of transferring approximately 1,000 accounts per hour, though network conditions may affect this throughput.

"Enable ONT Synchronization" must be enabled before beginning a Full Synchronization.

Using the Integration with Sonar

Automatic Provisioning

Automatic Provisioning functions using the same attributes needed for Full Synchronization. "Enable ONT Synchronization" must be enabled, and accounts must meet the following criteria to be automatically mapped between Sonar and SMx:

  1. A Calix-associated service must be assigned to an account (as determined under "Service Mapping" in the integration modal).
  2. An inventory item is assigned to the serviceable address of an account, complete with Serial Number and, if applicable, Profile ID.
  3. The account must be in an active status.

Deactivating Service to an ONT

It is possible to deactivate services to an ONT using one of three actions:

  1. Removing the Calix-associated service from an account
  2. Unassigning the ONT from the customer's serviceable address

The aforementioned two options will only remove services from the ONT in SMx. The customer account in Sonar will remain active following these two actions and can continue to accrue fees depending on other services on file.

  1. Deactivating the customer's account

Delinquency

In the event a customer is delinquent, it is possible to automatically have their service switched via SMx; this was briefly touched on during Configuring your Calix Integration (see the fold titled "Page 3"). This option can be left blank if you do not wish to change the service they subscribe to, but in the event you would like to take advantage of this automation, please see below.

SMx allows you to create numerous service templates, and up to three of them can be utilized within Sonar to outline how delinquent traffic should be handled. During the Calix Integration process, you are able to differentiate between Residential, Commercial and, Government account types. However, the same service template can be used for each account type if that is your preference. The most important part here is ensuring that the names outlined during this integration process match exactly to what is reflected in SMx.

It's important to note that the steps outlined above act differently than the delinquency parameters outlined in your instance's billing defaults. The act of an account in Sonar moving into a delinquent status along with late fees etc. remains handled by Sonar. This means that any Fiber customers who would otherwise fall into a delinquent address list will be unaffected by slowed speeds unless the "Delinquent Services" of your Calix Integration is utilized.

Alternatively, it is possible to route your Fiber traffic through a MikroTik router and use this as an inline device in Sonar, though we do not recommend this method.
The act of an account moving into a delinquent status in Sonar is detailed in our Delinquency Billing Best Practices | click here

Device Alarms

Device Alarms in SMx alert you to any issues within the Fiber circuit, whether it be originating at the OLT or at the customer's ONT. With this integration, ONT alarms can be reflected within your Sonar instance as well by enabling "Alarms Create Logs" in the integration modal. With this checked, you are able to see any alarms by navigating to Settings > Networking > Calix > Logs.

Each Device Alarm is created in your instance as its own individual line item, which includes the date and time the alarm was triggered. To view more information on the specifics of the alarm, you would click on "View Changes". Similarly, if changes are made to the Calix Integration, a line item would show here also, along with the name of the user who implemented those changes.

Device Status

Continuing on from this, if you want alarms to update the status of a device (from "Good" to "Down" etc.), then "Alarms Change Device Status" must be checked during the integration as well. Along with this option checked, you will need to create a monitoring template with ICMP enabled for each device that you want to use this feature with.

The process to create a monitoring template is outlined in our Building a Monitoring Template | click here

Alarm and Service Affecting in SMx

Device Status in Sonar

Critical and service affecting

Down

Major and service affecting

Down

Minor and service affecting

Down

Warning and standing

Warning

Clear and not service affecting

Good

How did we do?

Webhooks in Sonar: Basic PHP Example

Contact