Table of Contents
Calix Integration: Overview
Updated
by Kristen Fiddes
Read Time: 15 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.
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.
Permissions
As always, the first step in any integration is ensuring the relevant users can access it. Using Calix requires several key permissions for applicable roles. Please take a moment to review these new permissions and ensure that the relevant roles have them added before proceeding with any walkthrough steps.
Navigate to Settings → Security → Roles and either choose to edit an existing Role or create a new Role. With the next page populated, locate the permissions reflected in the screenshot below and enable whichever ones are applicable to that Role.
These permissions allow a user to control the connection between your Sonar instance, and Calix SMx. Additional permissions are required to control connectivity between SMx and customer accounts:
- Account Calix Service Details
- Field Mapping
- Service Mapping
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:
- 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. - 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 a serial number. These fields are interchangeable in Sonar when adding an item. - 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. - 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.
- 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
- 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.
- 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
- Navigate to Settings → Networking → Calix and click on “Create Calix Integration”:
- Complete the required fields across all 5 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 validated to be compatible with V21 and V22, and we are in the process of completing official validation with V23. If you are currently using V23, you can select "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 and Policy Maps 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 services can be applied here. Alongside the service chosen, underneath "Calix Service Template Name", you will then select the Service Template Name from the available list. This list comes directly from SMx, as long as your integration credentials are correct.
The fields here are required.
Once the Service Template Name is selected, the Calix Policy Map Name can also be selected. The Policy Map Name field is optional, and allows for more precise control over your network.
To identify your existing service templates in SMx, navigate to Templates > Service > AXOS Systems.Page 4
This page allows you to map account types to their corresponding Delinquency Service Template and Policy Map that you've configured in SMx
These fields are optional, but the service template must be added before the Policy Map.
To identify your existing service templates in SMx, navigate to Templates > Service > AXOS Systems.Page 5
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.The Calix set up makes use of Service Templates and Policy Mapping across both Service Mapping and Delinquency Mapping. These fields will provide options based on your SMx configuration, but can also be filled out manually.
If the field is filled out manually and does not correspond to an entry in SMx, the mapping won't work until those values are created. - 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 Johathan Doe, a new subscriber entry would be created in SMx. However, if we add "John Doe" 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:
- A Calix-associated service must be assigned to an account (as determined under “Service Mapping” in the integration modal).
- An inventory item is assigned to the serviceable address of an account, complete with Serial Number and, if applicable, Profile ID.
- 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.
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:
- A Calix-associated service must be assigned to an account (as determined under "Service Mapping" in the integration modal).
- An inventory item is assigned to the serviceable address of an account, complete with Serial Number and, if applicable, Profile ID.
- 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:
- Removing the Calix-associated service from an account
- 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.
- 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 4"). 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 can 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.
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.
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 can see any alarms by navigating to Settings → Networking → Calix → Logs.
Each Device Alarm is created in your instance as an 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.
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 |
Provisioning accounts with Calix
To provision an account in Sonar with Calix, you simply need to add the inventory item and service associated with the Calix integration to the customer account.
- Adding inventory to the account can be done by going to the Network & Inventory → Inventory items → Assign item. This opens a modal which provides you with a checkbox that will filter services to only list inventory mapped to a Calix integration.
- Adding the account service can be done by going to the Billing tab → Services & Packages -> Add Service. This opens a modal which provides you with a checkbox that will filter services to only list services mapped to a Calix integration.
Provisioning Details
Once the inventory item and service is added, it will prompt a Calix Provisioning modal, where values can be changed from default settings.
- Global VLAN field gives you a dropdown box where you can choose from all the Global VLANs setup within your SMx.
- If you decide to override the default settings, it is important to note that you will need to check the override box within SMX next to the Global VLAN setting. If left unchecked, the provisioning override you select here in this modal will cause the provisioning to fail.
- C-VLAN field is set up for manual input of numbers only. If text is added, then the Provision button will fade out and won't allow for the provisions to be saved.
- Service Port field provides a dropdown box with the specific Service ports associated with the inventory model assigned to the account.
- If the inventory item is not assigned to the account at this time, this field will not provide a dropdown with the associated ports available.
Trying to close the modal gives you a confirmation pop-up to confirm you want to skip provisioning.
Adding or changing the inventory item after provisioning has been mapped, will pop up the Calix Provisioning modal, but it cannot be saved since there's already one provision mapped. You will be presented with an error message if you select Provision at this time.
You need to close the modal and use the manual add or edit options if changes are needed.
Manually Adding or Editing Provisioning Details
If you need to add your provisioning details to the account service manually, due to skipping the provisioning initially, you can do so by clicking the Show Provisioning Details button on the service assigned to the account.
This will provide a dropdown section that allows you the ability to select the Add Provisioning Details button. Clicking this option opens the Calix Provisioning modal.
If provisioning has already been added to the service, and you have to make adjustments, select the Edit button to provide you with the Calix Provisioning modal, make the necessary changes, then click Save. Or select the dropdown arrow adjacent to the edit button and delete the current provisioning details from the service. You can then select the Add Provisioning Details button and manually add the necessary provision settings.
