dialplan Module

Andreea-Ancuta Onofrei

   Voice Sistem SRL

Edited by

Andreea-Ancuta Onofrei

Juha Heinanen

Olle E. Johansson

Luis Martin

   Copyright © 2007-2008 Voice Sistem SRL

   Copyright © 2008-2010 Juha Heinanen

   Copyright © 2014 Olle E. Johansson, Edvina AB
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. How it works
        3. Dialplan use cases
        4. Dependencies

              4.1. Kamailio Modules
              4.2. External Libraries or Applications

        5. Parameters

              5.1. db_url (string)
              5.2. table_name (string)
              5.3. dpid_col (string)
              5.4. pr_col (string)
              5.5. match_op_col (string)
              5.6. match_exp_col (string)
              5.7. match_len_col (string)
              5.8. subst_exp_col (string)
              5.9. repl_exp_col (string)
              5.10. attrs_col (string)
              5.11. attrs_pvar (string)
              5.12. fetch_rows (int)
              5.13. match_dynamic (int)
              5.14. append_branch (int)
              5.15. reload_delta (int)

        6. Functions

              6.1. dp_replace(dpid, inval, outvar)
              6.2. dp_match(dpid, inval)
              6.3. dp_translate(id, [src[/dest]])
              6.4. dp_reload()

        7. RPC Commands

              7.1. dialplan.dump
              7.2. dialplan.reload
              7.3. dialplan.translate

        8. Installation

   2. Developer's Guide

   List of Examples

   1.1. Set db_url parameter
   1.2. Set table_name parameter
   1.3. Set dpid_col parameter
   1.4. Set pr_col parameter
   1.5. Set match_op_col parameter
   1.6. Set match_exp_col parameter
   1.7. Set pr_col parameter
   1.8. Set pr_col parameter
   1.9. Set repl_exp_col parameter
   1.10. Set attrs_col parameter
   1.11. Set attrs_pvar parameter
   1.12. Set fetch_rows parameter
   1.13. Set match_dynamic parameter
   1.14. Set append_branch parameter
   1.15. Set reload_delta parameter
   1.16. dp_replace usage
   1.17. dp_match usage
   1.18. dp_translate usage
   1.19. dp_translate usage
   1.20. Example of rules

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. How it works
   3. Dialplan use cases
   4. Dependencies

        4.1. Kamailio Modules
        4.2. External Libraries or Applications

   5. Parameters

        5.1. db_url (string)
        5.2. table_name (string)
        5.3. dpid_col (string)
        5.4. pr_col (string)
        5.5. match_op_col (string)
        5.6. match_exp_col (string)
        5.7. match_len_col (string)
        5.8. subst_exp_col (string)
        5.9. repl_exp_col (string)
        5.10. attrs_col (string)
        5.11. attrs_pvar (string)
        5.12. fetch_rows (int)
        5.13. match_dynamic (int)
        5.14. append_branch (int)
        5.15. reload_delta (int)

   6. Functions

        6.1. dp_replace(dpid, inval, outvar)
        6.2. dp_match(dpid, inval)
        6.3. dp_translate(id, [src[/dest]])
        6.4. dp_reload()

   7. RPC Commands

        7.1. dialplan.dump
        7.2. dialplan.reload
        7.3. dialplan.translate

   8. Installation

1. Overview

   This module implements generic string translations based on matching
   and replacement rules. It can be used to manipulate the request URI or
   a PV and to translate it to a new format/value. Dialplan can also be
   used to match a given URI and retrieve a set of attributes based on the
   match. It is a very flexible module that can be used to handle call
   routing, prefix rewrites and much more.

2. How it works

   At startup the module will load a set of matching and transformation
   rules from a database. Rules are grouped into dialplans. Every database
   row will be stored in memory as a dialplan rule. Each rule will
   describe how the matching will be made, how the input value will be
   modified and which attributes that will be set for the matching
   transformation.

   The module expects an input value which will be matched against a rule
   by using regular expressions (see 'man pcresyntax' for syntax), string
   or fnmatch (see 'man fnmatch') matching. Overlapping matching
   expressions can be controlled via priorities. One priority can have
   multiple dialplan entries. Priorities need not be numbered with
   consecutive numbers. The next higher priority will be used after trying
   to match all entries in one priority.

   Once a rule is matched, the defined transformation (if any) is applied
   and the result is returned as output value. Also, if any string
   attribute is associated to the rule, this will be returned to the
   script along with the output value. This can be used to identify the
   used rule.

   The first matching rule will be processed.

3. Dialplan use cases

   The module can be used to implement multiple dialplans - to do
   auto-completion of dialed numbers (like national to international), to
   convert generic numbers to specific numbers (like for emergency
   numbers).

   The module can also be used for detecting a range or sets of numbers
   mapped on a service/case - the attribute string can be used to store
   extra information about the service/case.

   Non-SIP string translation can be implemented - like converting country
   names from all possible formats to a canonical format: (UK, England,
   United Kingdom) -> GB.

   Any other string-base translation or detection for whatever other
   purposes.

4. Dependencies

   4.1. Kamailio Modules
   4.2. External Libraries or Applications

4.1. Kamailio Modules

   The following modules must be loaded before this module:
     * A database module

4.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libpcre - the libraries of PCRE.

5. Parameters

   5.1. db_url (string)
   5.2. table_name (string)
   5.3. dpid_col (string)
   5.4. pr_col (string)
   5.5. match_op_col (string)
   5.6. match_exp_col (string)
   5.7. match_len_col (string)
   5.8. subst_exp_col (string)
   5.9. repl_exp_col (string)
   5.10. attrs_col (string)
   5.11. attrs_pvar (string)
   5.12. fetch_rows (int)
   5.13. match_dynamic (int)
   5.14. append_branch (int)
   5.15. reload_delta (int)

5.1. db_url (string)

   The translation rules will be loaded using this database URL.

   Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.

   Example 1.1. Set db_url parameter
...
modparam("dialplan", "db_url", "mysql://user:passwd@localhost/db")
...

5.2. table_name (string)

   The name of the database table used to load the translation rules.

   Default value is “dialplan”.

   Example 1.2. Set table_name parameter
...
modparam("dialplan", "table_name", "my_table")
...

5.3. dpid_col (string)

   The column name used to store the dialplan group ID.

   Default value is “dpid”.

   Example 1.3. Set dpid_col parameter
...
modparam("dialplan", "dpid_col", "column_name")
...

5.4. pr_col (string)

   The column name used to store the priority of the corresponding rule
   from the database row.

   Default value is “pr”.

   Example 1.4. Set pr_col parameter
...
modparam("dialplan", "pr_col", "column_name")
...

5.5. match_op_col (string)

   The column name used to store the type of matching of the rule.

   Default value is “match_op”.

   Example 1.5. Set match_op_col parameter
...
modparam("dialplan", "match_op_col", "column_name")
...

5.6. match_exp_col (string)

   The column name to store the rule match expression.

   Default value is “match_exp”.

   Example 1.6. Set match_exp_col parameter
...
modparam("dialplan", "match_exp_col", "column_name")
...

5.7. match_len_col (string)

   The column name to store the length of a string matching the match
   expression.

   Default value is “match_len”.

   Example 1.7. Set pr_col parameter
...
modparam("dialplan", "match_len_col", "column_name")
...

5.8. subst_exp_col (string)

   The column name to store the rule's substitution expression.

   Default value is “subst_exp”.

   Example 1.8. Set pr_col parameter
...
modparam("dialplan", "subst_exp_col", "column_name")
...

5.9. repl_exp_col (string)

   The column name to store the rule's replacement expression.

   Default value is “repl_exp”.

   Example 1.9. Set repl_exp_col parameter
...
modparam("dialplan", "repl_exp_col", "column_name")
...

5.10. attrs_col (string)

   The column name to store the rule's attributes to be set after match
   (see attrs_pvar )

   Default value is “attrs”.

   Example 1.10. Set attrs_col parameter
...
modparam("dialplan", "attrs_col", "column_name")
...

5.11. attrs_pvar (string)

   The pseudovariable used to store the rule's attributes, after
   translation (when dp_translate() succeeds). This parameter can be an
   “AVP” or a script variable (“$var()”)..

   Default value is “NULL”.

   Example 1.11. Set attrs_pvar parameter
...
modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
...

5.12. fetch_rows (int)

   The number of rows to be fetched at once from database

   Default value is “1000”.

   Example 1.12. Set fetch_rows parameter
...
modparam("dialplan", "fetch_rows", 4000)
...

5.13. match_dynamic (int)

   If set to 1, the match and substitution expressions can include script
   variables and their values are evaluated at runtime.

   During the loading process, the values that contain variables are no
   longer pre-compiled to PCRE structure in memory, because the values
   change at runtime, thus expect slightly slower performances. Values
   without script variables are pre-compiled even if this parameter is
   enabled.

   Default value is “0” (disabled).

   Example 1.13. Set match_dynamic parameter
...
modparam("dialplan", "match_dynamic", 1)
...

5.14. append_branch (int)

   If set to 1, the module appends a new outgoing branch when request URI
   (r-uri) or its user part are changed by dp_translate() or dp_replace()
   inside a failure_route block. Set it to 0 if the branch should not be
   added.

   Default value is “1”.

   Example 1.14. Set append_branch parameter
...
modparam("dialplan", "append_branch", 0)
...

5.15. reload_delta (int)

   The number of seconds that have to be waited before executing a new
   reload of dialplan rules. By default there is a rate limiting of
   maximum one reload in five seconds.

   If set to 0, no rate limit is configured. Note carefully: use this
   configuration only in tests environments because executing two dialplan
   reloads at the same time can cause to kamailio to crash.

   Default value is “5”.

   Example 1.15. Set reload_delta parameter
...
modparam("dialplan", "reload_delta", 1)
...

6. Functions

   6.1. dp_replace(dpid, inval, outvar)
   6.2. dp_match(dpid, inval)
   6.3. dp_translate(id, [src[/dest]])
   6.4. dp_reload()

6.1.  dp_replace(dpid, inval, outvar)

   The function translates the input value 'inval' using the rules with
   dialplan id 'dpid', storing the value in the variable 'outvar'. If the
   rule that was applied has attributes, they are stored in the variable
   provided via the module parameter 'attrs_pvar'.

   The behavior is same as dp_translate("dpid", "inval/outvar"), but the
   parameters have a more flexible format.

   Meaning of the parameters is as follows:
     * dpid - the dialplan id to match the rules and apply the
       transformations. It can be a static string or a config variable
       holding an integer value.
     * inval - input value. It can be a static or a dynamic string. The
       dynamic string can contain config variables, combined or not with
       static strings, that are evaluated at runtime.
     * outvar - output variable name. The value resulted after applying
       the matching rule is stored in this variable. The name must refer
       to a writable variable.

   This function can be used from ANY_ROUTE.

   Example 1.16. dp_replace usage
...
dp_replace("240", "$rU", "$var(newru)");
xlog("'$rU' was translated to '$var(newru)'\n");
dp_replace("240", "+49$rU", "$var(newval)");
...

6.2.  dp_match(dpid, inval)

   The function matches the input value 'inval' using the rules with
   dialplan id 'dpid'. If the rule that was applied has attributes, they
   are stored in the variable provided via the module parameter
   'attrs_pvar'.

   The behavior is same as dp_translate("dpid", "inval"), but the
   parameters have a more flexible format.

   Meaning of the parameters is as follows:
     * dpid - the dialplan id to match the rules and apply the
       transformations. It can be a static string or a config variable
       holding an integer value.
     * inval - input value. It can be a static or a dynamic string. The
       dynamic string can contain config variables, combined or not with
       static strings, that are evaluated at runtime.

   This function can be used from ANY_ROUTE.

   Example 1.17. dp_match usage
...
dp_match("240", "+49$rU");
xlog("the attributes associated with '+49$rU' are '$var(attrs)'\n");
...

6.3.  dp_translate(id, [src[/dest]])

   Will try to translate “src” into “dest” according to the translation
   rules in the dialplan identified by “id” . If src/dest is missing the
   default parameter “ruri.user/ruri.user” will be used, thus translating
   the request URI user part. If only “dest” is missing, only matching and
   storing of the matching rule's attributes is done.

   Returns 1, if translation succeeded, -1 in case of some error occurred,
   and -2 if dialplan with ID equal to id does not exist.

   Meaning of the parameters is as follows:
     * id -the dialplan id of the possible matching rules. This parameter
       can have the following types:
          + integer- the dialplan id is statically assigned
          + avp var - the dialplan id is the value of an existing avp
            variable
          + script var - the dialplan id is the value of an existing
            script variable.
     * src/dest - input and output of the function.
       Input parameter src can be any pseudo variable. Output parameter
       dest can be:
          + R-URI
            - the string is the r-uri or r-uri user part
          + avp var
            - At input the function will get the input string from an
            existing avp variable. At output the function will add an avp
            with the value of the output string.
          + script var
            - At input the function will get the input string from an
            existing script variable. At output the function will set a
            script variable with the value of the output string.

   This function can be used from ANY_ROUTE.

   Example 1.18. dp_translate usage
...
dp_translate("240", "$ruri.user/$avp(s:dest)");
xlog("translated to var $avp(s:dest) \n");
...

   Example 1.19. dp_translate usage
...
$avp(s:src) = $ruri.user;
dp_translate("$var(x)", "$avp(s:src)/$var(y)");
xlog("translated to var $var(y) \n");
...

6.4.  dp_reload()

   Reload the translation rules from the database. Note that there is a
   rate limiting defined by 'reload_delta' parameter. By default is
   allowed maximum one reload in five seconds.

   Name: dp_reload

   Parameters: none

   This function can be used from ANY_ROUTE.

7. RPC Commands

   7.1. dialplan.dump
   7.2. dialplan.reload
   7.3. dialplan.translate

7.1. dialplan.dump

   Dumps the content of one dialplan ID

   Name: dialplan.dump

   Parameters: Dialplan ID

   Example:
                kamctl rpc dialplan.dump 100

7.2. dialplan.reload

   Perform a reload of the translation rules from the database. Note that
   there is a rate limiting defined by 'reload_delta' parameter. By
   default is allowed maximum one reload in five seconds.

   Name: dialplan.reload

   Parameters: none

   Example:
                kamctl rpc dialplan.reload

7.3. dialplan.translate

   Will apply a translation rule identified by a dialplan id and an input
   string.

   Name: dialplan.translate

   Parameters: 2
     * Dial plan ID (number)
     * Input string (string) - it can be prefixed with 's:' to avoid
       auto-conversion when the command is executed with CLI apps such as
       kamctl.

   Example:
                kamctl rpc dialplan.translate 1 "abcdxyz"
                kamctl rpc dialplan.translate 1 s:123456789

8. Installation

   This module requires one table in Kamailio database: dialplan. The SQL
   syntax to create them can be found in dialplan-create.sql script in the
   database directories in the kamailio/scripts folder. You can also find
   the complete database documentation on the project webpage,
   https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

   Some sample records from a dialplan table are presented in the next
   figure.

   Example 1.20. Example of rules
...
dpid: 1
pr: 1
match_op: 1
match_exp: ^0[1-9][0-9]+$
match_len: 0
subst_exp: ^0([1-9][0-9]+)$
repl_exp: 0049\1
attrs: de
...
dpid: 1
pr: 2
match_op: 1
match_exp: ^0[1-9][0-9]+$
match_len: 0
subst_exp: ^0(.+)$
repl_exp: $var(prefix)\1
attrs: xyz
...

   Note that you can use config variables in the replacement expression
   (repl_exp) field. However, not all of config variables are safe to use
   there - specifically the variables that have in their name other
   variables (variables with dynamic name). References to SIP message,
   private variables ($var(...)) and AVPs with static name are among those
   that are safe to use in replacement expressions.

   The match_op field specify matching operator, valid values:
     * 0 - string comparison;
     * 1 - regular expression matching (pcre);
     * 2 - fnmatch (shell-like pattern) matching.

Chapter 2. Developer's Guide

   The module does not provide any API to use in other Kamailio modules.
