Kazoo Provisioner (Open Source)

 

Configure LCR on Kazoo, with Resource Selectors

 

Resource Selectors

About Resource Selectors

Resource selectors is a new way to route Offnet-calls. Old way used regex rules and "flags" for select proper resources (gateways). With new "resource selectors" you have several small modules, which can be organized in "chain" (rules).

Schema

Schema for resource selector document

Key	Description	Type	Default	Required	Support Level
name	Selector name	string()		true
resource	Resource ID	string()		true
selector	Selector data	string()		true
start_time	Start time (Gregorian seconds)	integer()		false
stop_time	Stop time (Gregorian seconds)	integer()		false
value	Extra selector data	string()		false

Fetch

GET /v2/resource_selectors/rules

curl -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    http://{SERVER}:8000/v2/resource_selectors/rules

{
  "data": {
    "rules": [
      {
        "get_resources": {}
      },
      {
        "filter_list": {
          "value_a": "request:Flags",
          "value_b": "resource:flags",
          "action": "keep"
        }
      },
      {
        "filter_regex": {
          "value_a": "number",
          "value_b": "resource:rules",
          "action": "keep",
          "mode": "empty_fail"
        }
      },
      {
        "filter_regex": {
          "value_a": "cid_number",
          "value_b": "resource:cid_rules",
          "action": "keep",
          "mode": "empty_ok"
        }
      },
      {
        "order": {
          "value": "resource:weight_cost",
          "direction": "ascend"
        }
      }
    ],
    "id": "resource_selector_rules"
  },
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Update rules

POST /v2/resource_selectors/rules

curl -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data": {"rules": [
        {"get_resources":{}},
        {"filter_list": {"value_a": "request:Flags", "value_b": "resource:flags", "action": "keep"}}
    ]}}'
    http://{SERVER}:8000/v2/resource_selectors/rules

{
  "data": {
    "rules": [
      {
        "get_resources": {}
      },
      {
        "filter_list": {
          "value_a": "request:Flags",
          "value_b": "resource:flags",
          "action": "keep"
        }
      },
    ],
    "id": "resource_selector_rules"
  },
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Database selectors

Database selectors - selectors stored in special database. Name of this database account/XX/XX/XXXXXXXXXXXXXXXXXXXXXXXXXXXX-selectors, where XXX...XXX - Account ID. System-wide selectors database use Master Account ID.

Each selector is separate document:

{
   "_id": "00066509d2648ede97e30635aa5ba097",
   "_rev": "1-5c13654b7a5521778791e6657789bb56",
   "pvt_type": "resource_selector",
   "name": "prefix",
   "selector": "7495",
   "resource": "RES-4",
   "value": "0.37"
}

• name - all selectors with same name used for filtering/sorting resources
• selector - this value used for filtering/sorting
• resource - Resource ID
• value - additional value, which can be used for sorting

List selectors

List selectors names

GET /v2/accounts/{ACCOUNT_ID}/resource_selectors/name

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/resource_selectors/name

{
  "data": [
    {
      "lcr2": 12
    },
    {
      "lcr": 36039
    }
  ],
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Here we see 2 selectors, lcr with 12 documents and lcr2 with 36039 documents.

GET /v2/accounts/{ACCOUNT_ID}/resource_selectors/name/{SELECTOR_NAME}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/resource_selectors/name/lcr2

{
  "data": [
    {
      "RES-4": 1
    },
    {
      "RES-3": 8
    },
    {
      "RES-2": 3
    }
  ],
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

List resources

GET /v2/accounts/{ACCOUNT_ID}/resource_selectors/resource

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/resource_selectors/resource

{
  "data": [
    {
      "RES-4": 36040
    },
    {
      "RES-3": 8
    },
    {
      "RES-2": 3
    }
  ],
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

In this example we see resources RES-2 with 3 documents, RES-3 with 8 documents and RES-4 with 1 document.

GET /v2/accounts/{ACCOUNT_ID}/resource_selectors/resource/{RESOURCE_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/resource_selectors/resource/RES-4

{
  "data": [
    {
      "lcr2": 1
    },
    {
      "lcr": 36039
    }
  ],
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Show selectors

GET /v2/accounts/{ACCOUNT_ID}/resource_selectors/resource/{RESOURCE_ID}/name/{SELECTOR_NAME}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/resource_selectors/resource/RES-4/name/lcr

{
  "data": [
    {
      "74956785833": "0.20"
    },
    {
      "74999055927": "0.30"
    },
    ...
    "74991234",
    "74951234",
    ...
    {
      "7495": "0.40"
    },
    {
      "7499": "0.40"
    }
  ],
  "revision": "{REVISION_ID}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Here we see selectors for resource RES-4 with selector name lcr. Resulted list can be simple list of strings or list of objects, its depending if there additional value or not.

Manage selectors

Manage (import/delete) resource selectors made via kazoo tasks (CSV file).

Category resource_selectors, action import or delete.

CSV columns:

• mandatory
  • name
  • selector
  • resource
• optional
  • stat_time
  • stop_time
  • value

Stepswitch Resource Selectors

Stepswitch Resource Selectors (SRS) - new flexible way to route outbound offnet calls to carriers (resources). SRS controlled by chain of small modules. Output one module is the input of other module (similar to "pipes" in Unix-shell). Input and output of each module is list of resources. Each module make some actions with this list like adding new resources, filtering resource, reordering resources, etc...

List of modules with addition parameters (controlling behavior of modules) called "rules". This rules saved at Account-DB in document resource_selectors_rules. Rules in Master Account DB acting as "system" rules and applied to resources in "offnet" DB.

You can use module several times with different parameters.

Rules

Rules is array of JSON objects. Key of object is the name of module. Value is another object contains parameters for module.

Example:

{
  "rules": [
    {
      "get_resources": {}
    },
    {
      "filter_list": {
        "value_a": "request:Flags",
        "value_b": "resource:flags",
        "action": "keep",
        "mode": "ne_subset_or_exact"
      }
    },
    {
      "filter_regex": {
        "value_a": "number",
        "value_b": "resource:rules",
        "action": "keep",
        "mode": "empty_fail"
      }
    },
    {
      "filter_regex": {
        "value_a": "cid_number",
        "value_b": "resource:cid_rules",
        "action": "keep",
        "mode": "empty_ok"
      }
    },
    {
      "order": {
        "value": "resource:weight_cost",
        "direction": "ascend"
      }
    }
  ]
}

Modules

get_resources (kz_srs_get_resources)

This module ignore any input and simply load resources from DB.

Module doesn't have any parameters. Resources loaded from "Offnet" DB or from Account DB (if Offnet-Request have Hunt-Account-Id).

Filter modules

This modules filter resources with some criterion.

All filter modules have similar parameters:

Name	Description
value_a	Value, which will be used for filtering (phone number)
value_b	Rules for testing (list of regexps for phone number)
action	What to do when value_a matched rules in value_b, keep or drop
mode	Filter specific parameter

value_a and value_b can be:

• number - dialed phone number in e164 format
• cid_number - Caller-ID number
• service_plans - list of service plans in form "plan-id:account-id" (account-id is account which created this service plan, usually it is master or reseller account). Example ["2fa2e806f0ba8c00796a27788861be78:37c8ecfc3cbddc3a5d7e83634ae8241d", "ff9462f98263fd203e776282cabf7d65:37c8ecfc3cbddc3a5d7e83634ae8241d"]
• resource:{RESOURCE_FIELD} - value of the resource field like flags, weight, etc... (resource:flags, resource:weight_cost)
• request:{REQUEST_FIELD} - value of field in Offnet-Request (request:Flags)
• database:{SELECTOR_NAME} - value got from database (this selectors managed via cb_resource_selectors module)

filter_prefix (kz_srs_filter_prefix)

value_a should be a string, value_b should be a list of prefixes. For example value_a is number (dialed number "+74951234567") and value_b is database:prefix_list_1 which returns list of rows:

selector	resource
7	Res-1
7	Res-6
7495	Res-1
7495	Res-3
7499	Res-2
749912	Res-3
749512	Res-5
749512345	Res-1

On module input we get resources: Res-1, Res-2, Res-3, Res-4, Res-5, Res-6 After applying filter we get result:

resource	matched prefix
Res-1	749512345
Res-3	7495
Res-5	749512
Res-6	7

Module output will be: Res-1, Res-3, Res-5 and Res-6

filter_regex (kz_srs_filter_regex)

This module filter resources based on list of regex rules (usually it's rules/cid_rules from resource).

mode parameter for this module:

• empty_fail: if list of rules is empty, then it equal to fail match (default behavior)
• empty_ok: if list of rules is empty then it equal to match, this behavior useful for Caller-ID check. You allow any Caller-ID on most of your resources, but several resources have strict rules. For this kind of resources you write rules, all other leave with empty cid_rules field.

filter_list (kz_srs_filter_list)

This filter can be used for select resources based on "flags" assigned to resource and account/user/device.

Lists in value_a and value_b sorted and deduplicated (["flag1", "flag3", "flag2", "flag3", "flag1"] becomes ["flag1", "flag2", flag3"]). Values from values_a searched/matched with values from value_b.

Default rule:

{
  "filter_list": {
    "value_a": "request:Flags",
    "value_b": "resource:flags",
    "action": "keep",
    "mode": "ne_subset_or_exact"
  }
}

Here we got list of flags from "Flags" field in Offnet-Request, and compare it with field "flags" in each resource.

mode parameter:

• exact: exact matching of lists in value_a and value_b, for example 2 empty lists matched, ["flag1", "flag2", "flag3"] and ["flag3", "flag1", "flag2"] matched too.
• subset: value_a must be subset of value_b, ["flag2", "flag3"] will match ["flag5", "flag3", "flag2"], empty list in value_a match any list (empty too) in value_b.
• ne_subset: similar to "subset", but empty list in value_a always fails
• ne_subset_or_exact: similar to "subset", but empty list in value_a match only with empty list in value_b
• intersect: match if any element in value_a exist in value_b, empty vaule_a and/or value_b will fail to match
• disjoint: inverse of "intersect" mode

order (kz_srs_order)

This module sort resources by some field/criteria.

Default rule:

{
  "order": {
    "value": "resource:weight_cost",
    "direction": "ascend"
  }
}

Value can be field from resource or selector from database, direction can be "ascend" or "descend".