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 formatcid_number
- Caller-ID numberservice_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 viacb_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 emptycid_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 invalue_a
andvalue_b
, for example 2 empty lists matched,["flag1", "flag2", "flag3"]
and["flag3", "flag1", "flag2"]
matched too.- subset:
value_a
must be subset ofvalue_b
,["flag2", "flag3"]
will match["flag5", "flag3", "flag2"]
, empty list invalue_a
match any list (empty too) invalue_b
. ne_subset
: similar to"subset"
, but empty list invalue_a
always failsne_subset_or_exact
: similar to"subset"
, but empty list invalue_a
match only with empty list invalue_b
intersect
: match if any element invalue_a
exist invalue_b
, emptyvaule_a
and/orvalue_b
will fail to matchdisjoint
: 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"
.