

Mvno

Adding new MVNOs to Tower of Power#

In Tower of Power, multiple MVNOs are supported, each having their own supported Carriers and set of features. They also have their own Kazoo Cluster. For now, Kazoo Clusters have a 1-to-1 relationship to MVNOs, meaning that a Cluster has only one MVNO, and an MVNO has only one Cluster. In the database, however, Clusters and MVNOs each have their own document, linking to each other.

This documentation explains how to add a new MVNO to the database. For information on how to add a new Cluster, please checkout the Cluster documentation.

Note: For Tower of Power to be able to work, there must be at least one Cluster/MVNO pair in the database, typically our own (2600hz).

Creating the MVNO database#

If you are freshly deploying TOP v2 on a new server, the MVNO database will first have to be created.

Note: If the database mvnos-top already exists, you can skip this step.

First, create a new database with the following name: mvnos-top.

Next, you will need to create the design document allowing to list MVNOs by their Cluster ID:

{
    "_id": "_design/mvnos",
    "language": "javascript",
    "views": {
        "list_by_cluster": {
            "map": "function(doc) { emit(doc.cluster_id, {'id':doc._id, 'cluster_id': doc.cluster_id, 'carriers': Object.keys(doc.carriers) })}"
        }
    }
}

Adding the MVNO document#

Now that the database has been created, you can simply add your MVNO document to it. A MVNO document should contain the following fields:

{
    "_id": "2600hz",
    "cluster_id": "8a901bea1d3297ef7d4c8d34809472c2",
    "carriers": {
        "sprint": {
            "application_id": "2013071001",
            "application_user_id": "2600hz",
            "consumer_id": "2600hz",
            "authentication": {
                "pem_file": "2600hz.sprint.pem",
                "cer_file": "2600hz.sprint.cer"
            },
            "features": {
                "mms": "260PMVM",
                "mo_sms_blocking": "260MOBLK",
                "parental_controls": "260WAPC",
                "lte": "260LTESOC",
                "wimax": "260DMSOC",
                "voice_blocking": "260VBLK",
                "outgoing_call_blocking": "260BAOC",
                "incoming_call_blocking": "260BAIC",
                "sip": "260WMISOC",
                "voice_authentication_bypass": "260WHLIST",
                "home_office_link_no_answer": "260HOLNA",
                "home_office_link_busy": "260HOLB",
                "ccf_busy_no_answer": "260CCF",
                "sms_blocking": "260SMSBLK",
                "mt_sms_blocking": "260MTBLK",
                "international": "260INTCL",
                "caller_id_blocking": "260CLBLK",
                "hotline": "260HLSOC",
                "tethering": "260PAM",
                "throttle_64": "A166DC",
                "throttle_128": "A188DC",
                "throttle_256": "A122DC",
                "throttle_512": "A125DC",
                "block_data": "260DISNAI"
            },
            "defaults": {
                "features": ["sip", "mms", "international", "lte"],
                "plan": "260PLAN21"
            },
            "porting": {
                "staleness_threshold": 7
            }
        }
    },
    "usage_files": {
        "sprint": [
            "/opt/sprint_data_usage/ipdr/",
            "/opt/sprint_data_usage/lte/"
        ]
    },
    "pvt_type": "mvno_config"
}

The _id field should be the a unique key representing the MVNO's name, not a randomly generated UUID. This ID will be referenced in the Cluster document.
The cluster_id field should be the actual Cluster's ID, also used as the Cluster document's ID.
The carriers field should be an map of carrier objects (currently containing only "sprint"). Each carrier will have their own required fields. Above are the actual fields/values required for "sprint" for the "2600hz" MVNO. See the Sprint-specific data section for more details.
The usage_files is optional, and only needed if we are handling the data usage for this MVNO (currently only ourself). If specified, it should contain a object where the keys are the carrier and the values are an array of paths for where the usage files to be parsed are on the server.
The pvt_type field must be set to "mvno_config".

Note: Even though the MVNO document's structure has changed from TOP v1, the document ID and the sprint section should be mostly identical and can be copied over, except for the authentication section that must be manually added (see below).

Sprint-specific Data#

Sprint is currently our only carrier, and everything that is under carriers.sprint is Sprint specific data. Below are the list of properties and their equivalent in the v1 mvno document.

application_id: Formerly the field id, this is used as a header for every Sprint API request.
application_user_id: Formerly non-existant, this is also used as a header for every Sprint API request. It should be set to the MVNO's ID for our currently existing MVNOs (i.e. "2600hz" and "grid").
consumer_id: Formerly consumer_id, although it was not present for the 2600hz MVNO, where the MVNO's ID ("2600hz") was used instead.
authentication: Formerly non-existant, the authentication section has been added in order to identify the authentication attachements required for Sprint. See below for more details.
features: Formerly features, this hasn't changed and can be safely copied over. However, they may eventually be subject to change as the keys should be normalized in the future.

As shown above, Sprint requires two authentication files attached to this document: a .cer file and a .pem file. These two files were already present in v1, so you can simply download them from there and re-upload them in this new document. You then need to put the name if the attachments in the properties carriers.sprint.authentication.pem_file and carriers.sprint.authentication.cer_file.

Note: Since there may be other carriers requiring such attachments in the future, it is advised to give those files a carrier-specific name such as 2600hz.sprint.cer instead of just 2600hz.cer as it was in v1.

Adding the MVNO's Cluster#

As mentioned before, each MVNO must be linked to a Kazoo Cluster, via the cluster_id field specified above. If you haven't done it yet, please head over to the Cluster documentation to learn how to add a new Kazoo Cluster.