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

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:

5.3. dpid_col (string)

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)
...

6. Functions

6.1.
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 an script variable
with the value of the output string.

7.2. 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

Input String

Example:

kamcmd dialplan.translate 1 "abcdxyz"

8. Installation

The modules 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.

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.