dialplan_admin.xml

<!-- Module User's Guide -->

<chapter>
	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
	This module implements generic string translations based on matching and
	replacement rules. It can be used to manipulate R-URI or a PV and to
	translated to a new format/value.
	</para>
	</section>

	<section>
	<title>How it works</title>
	<para>
	At startup, the module will load all transformation rules from one or more
	dialplan-compatible tables. The data of each table will be stored in a
	<emphasis>partition</emphasis> (data source), which is defined by the
	"db_url" and "table_name" properties.  Every table row will be stored in
	memory as a translation rule. Each rule will describe how the matching
	should be made, how the input value should be modified and which attributes
	should be set for the matching transformation.
	</para>
	<para>
	A dialplan rule can be of two types:
	<itemizedlist>
	<listitem>
	<para>
		<emphasis>"String matching" rule</emphasis> - performs a
		string equality test against the input string. The case of the
		characters can be ignored by enabling bit 1 of the rule's "match_flags"
		bitmask column
		(i.e. set the column value to 1 or 0, for insensitive or sensitive)
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>"Regex matching" rule</emphasis> - uses Perl
		Compatible Regular Expressions, and will attempt to match the rule's
		expression against an input string. The regex
		maching can be done in a caseless manner by enabling bit 1 of the
		rule's "match_flags" bitmask column
		(i.e. set the column value to 1 or 0, for insensitive or sensitive)
	</para>
	</listitem>
	</itemizedlist>
	</para>
	<para>
	The module provides the <emphasis>dp_translate()</emphasis> script function,
	which expects an input <emphasis role='bold'>string</emphasis> value that
	will be matched, at worst, against all rules of a partition.
	</para>
	<para>
	Internally, the module groups a partition's rules into two sets, "string" and "regex".
	The matching logic will attempt to find the first match within each of
	these two sets of rules. Each set will be iterated in
	<emphasis role='bold'>ascending</emphasis> order of priority. If an input
	string happens to match a rule in each of the two sets, the rule with the
	smallest priority will be chosen. Furthermore, should these two matching
	rules also have equal priorities, the one with the smallest "id" field
	(the unique key) will be chosen. 
	</para>
	<para>
	Once a single rule is decided upon, 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.
	</para>
	</section>

	<section>
	<title>Usage cases</title>
	<para>
	The module can be used to implement dialplans - to do auto completion of
	the dialed numbers (e.g. national to international), to convert generic
	numbers to specific numbers (e.g. for emergency numbers).
	</para>
	<para>
	Also the module can be used for detecting ranges or sets of numbers mapped
	on a service/case - the "attributes" string column can be used here to
	store extra information about the service/case.
	</para>
	<para>
	Non-SIP string translation can also be implemented - like converting country
	names from all possible formats to a canonical format:
	(UK, England, United Kingdom) -> GB.
	</para>
	<para>
	Any other string-based translation or detection for whatever other purposes.
	</para>
	</section>

	<section>
		<title>Database structure and usage</title>
		<para>
		Depending what kind of operation (translation, matching, etc) you want
		to do with the module, you need to populate the appropriate DB records.
		</para>
		<para>
		The definition of the tables used by the dialplan module can be found
		at <ulink url="https://opensips.org/db-schema.html#AEN1501">&osipsdbdocslink;#AEN1501</ulink>
		</para>
		<section>
		<title>What to place in table</title>

		<section>
		<title>String translation (regexp detection, subst translation)</title>
			<para>
			Recognize a number block in all forms (international, national)
			and convert it to a canonical format (E.164)
			</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>match_op</emphasis> = 1 (regexp)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_exp</emphasis> = "^(0040|\+40|0|40)21[0-9]+" ;
				regular expression that will be used to match with this rule (if
				the rule should be applied for the input string)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_flags</emphasis> = 0 (0 - case sensitive,
				1 - case insensitive matching)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>subst_exp</emphasis> = "^(0040|\+40|0|40)(.+)" ;
				regular expression used to do the transformation (first part
				of the subst operation)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>repl_exp</emphasis> = "40\2" ; second part of the
				subst (output) - linked to the subst_exp field; when both
				defined, they work as a subst()
			</para>
			</listitem>
			</itemizedlist>
		</section>

		<section>
		<title>String translation (regexp detection, replacement)</title>
			<para>
			Recognize the name of a country (multiple languages) and convert
			it to a single, fixed value
			</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>match_op</emphasis> = 1 (regexp)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_exp</emphasis> = "^((Germany)|(Germania)|(Deutschland)|(DE))" ;
				regular expression that will be used to match with this rule (if
				the rule should be applied for the input string)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_flags</emphasis> = 0 (0 - case sensitive,
				1 - case insensitive matching)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>subst_exp</emphasis> = NULL ;
				when translation is actually a replacement, this field must
				be NULL.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>repl_exp</emphasis> = "DE" ; static string to
				replace the input - whenever this rule will match, it will
				return this string as output.
			</para>
			</listitem>
			</itemizedlist>
		</section>

		<section>
		<title>Number detection (regexp detection, no replacement)</title>
			<para>
			Recognize a block of numbers as belong to a single service and
			signalize this via an attribute.
			</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>match_op</emphasis> = 1 (regexp)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_exp</emphasis> = "^021456[0-9]{5}" ;
				regular expression that will be used to match with this rule (if
				the rule should be applied for the input string)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_flags</emphasis> = 0 (0 - case sensitive,
				1 - case insensitive matching)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>subst_exp</emphasis> = NULL ;
				no translation
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>repl_exp</emphasis> = NULL ;
				no translation
				</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>attrs</emphasis> = "serviceX" ;
				whatever string you will get into OpenSIPS script and it will
				provide you more information (totally custom)
				</para>
			</listitem>
			</itemizedlist>
		</section>

		<section>
		<title>String conversion (equal detection, replacement)</title>
			<para>
			Recognize a fixed string/number and replace it with something fixed.
			</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>match_op</emphasis> = 0 (equal)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_exp</emphasis> = "SIP server" ;
				string to be matched
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_flags</emphasis> = 0 (0 - case sensitive,
				1 - case insensitive matching)
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>subst_exp</emphasis> = NULL ;
				no subst translation
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>repl_exp</emphasis> = "OpenSIPS" ;
				output string
				</para>
			</listitem>
			</itemizedlist>
		</section>

		</section>

	</section>



	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>


	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before
		running &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libpcre-dev - the development libraries of <ulink url="http://www.pcre.org/">PCRE</ulink></emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>

	<section id="param_partition" xreflabel="partition">
		<title><varname>partition</varname> (string)</title>
		<para>
		Specify a new dialplan partition (data source).  This parameter may
		be set multiple times.  Each partition may have a specific "db_url" and
		"table_name".  If not specified, these values will be inherited from
		<xref linkend="param_db_url"/>, db_default_url or
		<xref linkend="param_table_name"/>, respectively.  The name of
		the default partition is 'default'.
		</para>
		<para>
		Note: OpenSIPS will validate each partition, so make sure to add any
		required entries in the "version" table of each database defined
		through the 'db_url' property.
		</para>

		<example>
		<title> Defining the <varname>'pstn'</varname> partition</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "partition", "
	pstn:
		table_name = dialplan;
		db_url = mysql://opensips:opensipsrw@127.0.0.1/opensips")
...
		</programlisting>
		</example>

		<example>
		<title> Define the 'pstn' partition and make it the 'default' partition, so we avoid loading the 'dialplan' table</title>
		<programlisting format="linespecific">
...
db_default_url = "mysql://opensips:opensipsrw@localhost/opensips"

loadmodule "dialplan.so"
modparam("dialplan", "partition", "
	pstn:
		table_name = dialplan_pstn")
modparam("dialplan", "partition", "default: pstn")
...
		</programlisting>
		</example>
	</section>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		The default DB connection of the module, overriding the global
		'db_default_url' setting.  Once specified, partitions which are missing
		the 'db_url' property will inherit their URL from this value.
		</para>
		<para>
		<emphasis>
			Default value is NULL (not set).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "db_url", "mysql://user:passwd@localhost/db")
...
		</programlisting>
		</example>
	</section>

	<section id="param_table_name" xreflabel="table_name">
		<title><varname>table_name</varname> (string)</title>
		<para>
		The default name of the table from which to load translation rules.
		Partitions which are missing the 'table_name' property will inherit
		their table name from this value.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dialplan</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>table_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "table_name", "my_table")
...
		</programlisting>
		</example>
	</section>

	<section id="param_dpid_col" xreflabel="dpid_col">
		<title><varname>dpid_col</varname> (string)</title>
		<para>
		The column name to store the dialplan ID group.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dpid</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>dpid_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "dpid_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_pr_col" xreflabel="pr_col">
		<title><varname>pr_col</varname> (string)</title>
		<para>
		The column name to store the priority of the corresponding rule from
		the table row. Smaller priority values have higher precedence.
		</para>
		<para>
		<emphasis>
			Default value is <quote>pr</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pr_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "pr_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_match_op_col" xreflabel="match_op_col">
		<title><varname>match_op_col</varname> (string)</title>
		<para>
		The column name to store the type of matching of the rule.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_op</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>match_op_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_op_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_match_exp_col" xreflabel="match_exp_col">
		<title><varname>match_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule match expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>match_exp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_match_flags_col" xreflabel="match_flags_col">
		<title><varname>match_flags_col</varname> (string)</title>
		<para>
		The column name to store various matching flags. Currently
		0 - case sensitive matching, 1 - case insensitive matching.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_flags</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>match_flags_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_flags_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_subst_exp_col" xreflabel="subst_exp_col">
		<title><varname>subst_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule's substitution expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>subst_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>subs_exp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "subst_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

		<section id="param_repl_exp_col" xreflabel="repl_exp_col">
		<title><varname>repl_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule's replacement expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>repl_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>repl_exp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "repl_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section id="param_timerec_col" xreflabel="timerec_col">
		<title><varname>timerec_col</varname> (integer)</title>
		<para>
		The column name that indicates an additional time recurrence check 
		within the rule (column values are RFC 2445-compatible strings).  The
		value format is identical to the input of the
		<ulink url='cfgutils#func_check_time_rec'>check_time_rec()</ulink>
		function of the <emphasis>cfgutils</emphasis> module, including the
		optional use of logical operators linking multiple such strings into a
		larger expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>timerec</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>timerec_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "timerec_col", "month_match")
...
		</programlisting>
		</example>
	</section>

	<section id="param_disabled_col" xreflabel="disabled_col">
		<title><varname>disabled_col</varname> (integer)</title>
		<para>
		The column name that indicates if the dialplan rule is disabled.
		</para>
		<para>
		<emphasis>
			Default value is <quote>disabled</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>disabled_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "disabled_col", "disabled_column")
...
		</programlisting>
		</example>
	</section>

	<section id="param_attrs_col" xreflabel="attrs_col">
		<title><varname>attrs_col</varname> (string)</title>
		<para>
		The column name to store rule-specific attributes.
		</para>
		<para>
		<emphasis>
			Default value is <quote>attrs</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>attrs_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "attrs_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>

	<section id="func_dp_translate" xreflabel="dp_translate()">
	<title>
		<function moreinfo="none">dp_translate(id, input, [out_var], [attrs_var], [partition])</function>
	</title>
	<para>
	Will try to translate the src string into dest string according to
	the translation rules with dialplan ID equal to id.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	<listitem>
		<para>
		<emphasis>id</emphasis> (int) - the dialplan id to be used for matching rules
		</para>
	</listitem>

	<listitem>
		<para>
		<emphasis>input</emphasis> (string) - input string to be used for rule matching
		and for computing the output string.
		</para>
	</listitem>

	<listitem>
		<para>
		<emphasis>out_var</emphasis> (var, optional) - variable to be populated/written with 
		the output string (if provided by the translation rule).
		</para>
	</listitem>

	<listitem>
		<para>
		<emphasis>attrs_var</emphasis> (var, optional) - variable to be populated/written 
		with the atribute string, if provided by the translation rule.
	</para>
	</listitem>

	<listitem>
		<para>
		<emphasis>partition</emphasis> (string, optional) - the name of the partition
		(set of data) to be used for locating the DP ID.
	</para>
	</listitem>
	</itemizedlist>
	<para>
	This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, LOCAL_ROUTE,
	BRANCH_ROUTE, STARTUP_ROUTE, TIMER_ROUTE and EVENT_ROUTE.
	</para>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
dp_translate(240, $ru, $var(out));
xlog("translated into '$var(out)' \n");
...
	</programlisting>
	</example>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
$avp(src) = $ruri.user;
dp_translate($var(x), $avp(src), $var(y), $var(attrs));
xlog("translated to var $var(y) with attributes: '$var(attrs)'\n");
...
	</programlisting>
	</example>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
$var(id) = 10;
dp_translate($var(id), $avp(in), , $avp(attrs), "example_partition");
xlog("matched with attributes '$avp(attrs) against example_partition'\n");
...
	</programlisting>
	</example>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
dp_translate(10, $var(in), , , $var(part));
xlog("'$var(in)' matched against partition '$var(part)'\n")
...
	</programlisting>
	</example>

	</section>

	</section>


	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>

		<section id="mi_dp_reload" xreflabel="dp_reload">
			<title><function moreinfo="none">dp_reload</function></title>
			<para>
			It will update the translation rules, loading the database info.
			</para>
		<para>
		Name: <emphasis>dp_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>1</emphasis></para>
			<itemizedlist>
				<listitem>
				<para><emphasis>partition</emphasis> (optional) - Partition
					to be reloaded.  If not specified, all partitions will be
					reloaded.</para>
				</listitem>
			</itemizedlist>
		<para>
		MI DATAGRAM Command Format:
		</para>
		<programlisting  format="linespecific">
		opensips-cli -x mi dp_reload
		</programlisting>
		</section>

	<section id="mi_dp_translate" xreflabel="dp_translate">
			<title><function moreinfo="none">dp_translate</function></title>
			<para>
			It will apply a translation rule identified by a dialplan
				id on an input string.
			</para>
		<para>
		Name: <emphasis>dp_translate</emphasis>
		</para>
		<para>Parameters: <emphasis>3</emphasis></para>
			<itemizedlist>
			<listitem>
			<para><emphasis>dpid</emphasis> - the dpid of the rule set used for
			match the input string</para>
			</listitem>
			<listitem>
			<para><emphasis>input</emphasis> - the input string</para>
			</listitem>
			<listitem>
			<para><emphasis>partition</emphasis> - (optional) the name of the 
			partition when the dpid is located</para>
			</listitem>
			</itemizedlist>
		<para>
		MI DATAGRAM Command Format:
		</para>
		<programlisting  format="linespecific">
        opensips-cli -x mi dp_translate 10 +40123456789
		</programlisting>
		</section>

	<section id="mi_dp_show_partiton" xreflabel="dp_show_partiton">
		<title><function moreinfo="none">dp_show_partiton</function></title>
		<para>
			Display partition(s) details.
		</para>
		<para>
		Name: <emphasis>dp_show_partiton</emphasis>
		</para>
		<para>Parameters: <emphasis>2</emphasis></para>
			<itemizedlist>
				<listitem>
				<para><emphasis>partition</emphasis> (optional) - The 
				partition name. If no partition is specified, all known 
				partitions will be listed.</para>
				</listitem>
			</itemizedlist>
 		<para>
		MI DATAGRAM Command Format:
		</para>
		<programlisting  format="linespecific">
        opensips-cli -x mi dp_translate default
		</programlisting>
		</section>
	</section>

	<section>
		<title>Installation</title>
		<para>
		The modules requires one table in OpenSIPS database: dialplan.The SQL
		syntax to create them can be found in dialplan-create.sql
		script in the database directories in the opensips/scripts folder.
		You can also find the complete database documentation on the
		project webpage, &osipsdbdocslink;.
		</para>
	</section>



</chapter>