Advanced Recording Rules
Please note: this is legacy documentation. Please check out https://docs.miarec.com/all/ for the most up-to-date documentation and user guides.
Introduction
MiaRec supports very powerful recording filters, which allow to:
- specify which calls to record and which to ignore depending on call parameters (caller/callee ip-address, mac-address, telephone number etc.)
- change a default file naming for calls (for example, phones can be united into groups by their IP-addresses and every group is stored inside its own directory)
Recording filters are specified inside section [Filters::OnCallStart] in MiaRec.ini configuration file.
Example:
[Filters::OnCallStart]
filter1 condition = caller-number = '100' OR callee-number = '100'
filter1 action = record
filter2 condition = caller-number = '200' OR callee-number = '200'
filter2 action = record
filter3 condition = caller-number = '300' OR callee-number = '300'
filter3 action = record
default_action = ignore
In this example, only those calls will be recorded, which are made from/to phones 100, 200 or 300.
All other calls will be ignored (see default_action = ignore).
Note, starting from version 5.0 MiaRec supports configuring per-user recording rules via the web interface. These per-user rules are executed after recording filters in the INI file. Recording filters from the INI file are always executed first. If one of the filter's conditions matches, then per-user rules are not executed. This allows to configure some advanced global ignore rules, like "ignore all internal calls":
[Filters::OnCallStart]
# Ignore all internal calls, where both caller and called phone numbers are 3 digits.
filter_internal_calls_action = ignore
filter_internal_calls_condition = caller-number LIKE '___' AND callee-number LIKE '___'
Syntax of filters
Syntax of filters is following:
<unique-name-of-filter>condition = CONDITION
<unique-name-of-filter>action = [ record | ignore ]
<unique-name-of-filter>filename = FILENAME-FORMAT
Each filter has a unique name and consists of three lines: action, condition , and filename. The last line (filename) is optional.
Name of filter
Each recording filter should have unique name. For example:
[Filters::OnCallStart]
filter1_condition = caller-number = 12345
filter1_action = record
filter2_condition = caller-ip = 10.0.0.0/24
filter2_action = record
filter2_filename = C:\Calls\Network2\%{setup-time#%Y%m%d%H%M%S}.mp3
my new filter condition = caller-ip = 10.0.5.0/24
my new filter action = ignore
In this example three filters are specified with the following names:
- filter1_
- filter2_
- my new filter
Filter name may contain letters, digits, underscore and space characters.
Condition of filter
condition is a logical expression. Example:
filter1 condition = caller-ip = 192.168.0.1
filter2 condition = caller-ip >= 192.168.0.10 AND caller-ip <= 192.168.0.20
filter3 condition = caller-number LIKE '011%'
filter4 condition = caller-ip = 10.0.0.5 AND NOT (callee-ip = 10.0.0.1 OR callee-ip = 10.0.0.2)
Read Syntax of filter condition for details.
The action of filter
action specifies what to do with a call. The following actions are supported:
Action | Description |
---|---|
record |
Record the call, which matches that filter's condition. If a filename line exists, then the call will be recorded with a specified name, otherwise, the default file name will be used. |
ignore | Ignore a call (do not record it). The audio file for that call will not be stored on disk and normally such a call will not be visible inside the MiaRec web interface. But, optionally, it is possible to show ignored calls inside MiaRec web-interface (see SaveCDRsForIgnoredCalls). |
Filename
The filename specifies a file name format for calls, which match the filter's condition. It is optional. If it is omitted, then a default file name format is used as specified in section [Recording] parameter FileNameFormat. The syntax of this field is the same.
Default action
Note, starting from version 5.2 a default action is configured inside web interfaces. Settings for default action inside the INI file are ignored during normal system operation. Although they are used when the MiaRec recorder functions without a database.
For calls, which do not match any of the recording filters, a default action is performed. Default action may be recorded or ignored. Optionally, a default file name format (default_filename) can be specified.
Example:
[Filters::OnCallStart]
filter1_condition = caller-number = '123456' OR callee-number = '123456'
filter1_action = record
default_action = ignore
In above example only phone with number '123456' will be recorded. All other calls will be ignored (see default_action = ignore).
Optionally, you can specify default_filename. This parameter will override the one, which is specified inside FileNameFormat in section [Recording].
Example:
[Filters::OnCallStart]
filter1_condition = caller-number = '123' OR callee-number = '123'
filter1_action = record
filter1_filename = C:\Phone123\%{setup-time#%Y%m%d%H%M%S}.mp3
default_action = record
default_filename = C:\OtherPhones\%{setup-time#%Y%m%d%H%M%S}.mp3
In this example, calls with number 123 will be stored inside directory C:\Phone123\.
All other calls will be stored inside directory C:\OtherPhones\.
Note, if a default action is omitted, then it has an implicit value record.
Order of filters
The order of filters is important when a call may match multiple filters. In this case, the first matched filter is used.
For example, we have the following filters:
[Filters::OnCallStart]
filter1_action = record
filter1_condition = caller-ip = '192.168.0.0/24'
filter2_action = ignore
filter2_condition = caller-port = 5060
And our call has caller IP equal to 192.168.0.5 and caller IP equal to 5060.
Such a call will match a condition of both filters, but the action of the first one will be performed (a record).
If you change the order of filters inside the INI file, like:
[Filters::OnCallStart]
filter2_action = ignore
filter2_condition = caller-port = 5060
filter1_action = record
filter1_condition = caller-ip = '192.168.0.0/24'
Then the mentioned call will be ignored because the first matched filter has action ignored.
Troubleshooting
When recording filters are not working as you expected, then use the following recommendations:
- Look at Windows Event Log (Control Panel -> Administration -> Event Viewer). If the syntax of the recording filter is incorrect, MiaRec will write an error message to Windows Event Log.
- Change SaveCDRsForIgnoredCalls parameter inside MiaRec.ini to 1. Normally, ignored calls are not visible inside MiaRec calls history. When SaveCDRsForIgnoredCalls = 1, the ignored calls will be shown inside MiaRec with a special icon and message "Ignored by filters". This will allow you to see if the problem is in your filters. Read details here: SaveCDRsForIgnoredCalls.
- Verify that recording filters have phone numbers/names in the same format as they appear inside the MiaRec web interface. Sometimes you may expect that your phones have extension 2XX (for example), but, in reality, they are 92XX (with an additional prefix). MiaRec extracts phone numbers from VoIP signaling messages, which are sent by your phones. You should create recording filters with exactly the same phone numbers as they are visible to MiaRec.
Post-Recording Filters
MiaRec supports post-recording filters. In a contrast to regular recording filters, which are executed when a call is started, the port-recording filters are executed when the call is completed. Post-recording filters allow doing post-processing of a call. For example, delete automatically calls, which are shorter than 5 seconds. Or move completed calls to another location (to a network drive). Post-recording filters are configured inside section [Filters::OnCallStop] in MiaRec.ini configuration file.
Example of post-recording filters:
[Filters::OnCallStop]
filter1_codition = duration < 5
filter1_action = delete
default_action = rename
default_filename = \\my-storage\Calls\%{filename}
In this example, short calls (shorter than 5 seconds) are removed automatically. The remaining calls are moved to the network storage directory \\my-storage\Calls. The syntax of port-recording filters is similar to regular recording filters (see Recording filters). This page describes only the differences between regular filters and port-recording filters.
The action of post-recording filters
Post-recording filters support the following actions:
Action | Description |
---|---|
rename | Rename or move to other location the audio file after call is completed. |
delete | Delete a call after it is completed. |
record | Store a call as normal. Do not do any modification of a call after it is completed. |
Call parameters
Post-recording filters support all call parameters, which are supported in regular recording filters (see Syntax of filter condition), plus additional parameters, listed in the following table:
Call parameter | Description |
---|---|
alerting-time |
Date/time when phone started ringing. Format: YYYY-mm-DD HH:MM:SS Where:
Example: alerging-time = 2007-06-10 13:45:51 |
connect-time |
Date/time when call was answered. Format: YYYY-mm-DD HH:MM:SS |
disconnect-time |
Date/time when call was disconnected. Format: YYYY-mm-DD HH:MM:SS |
duration |
Duration of voice part of a call in seconds. This is a difference between connect-time and disconnect-time. Examples: duration < 5 duration >= 30 |
total-duration |
Total duration of a call in seconds. This is a difference between setup time and disconnect time. Examples: total-duration < 5 |
call-state |
Phase (state) of the call. It is a numeric value, one of:
Example: call-state = 7 |
Example of post-recording filters
[Filters::OnCallStart]
filter1_condition = caller-number = '123456' OR callee-number = '123456'
filter1_action = record
filter1_filename = C:\MyCalls\%{setup-time#%Y%m%d%H%M%S}.mp3
default_action = ignore
[Filters::OnCallStop]
default_action = rename
default_filename = D:\MyRecordings\%{filename}
Above example demonstrates both regular recording filters (section [Filters::OnCallStart]) and post-recording filters (section [Filters::OnCallStop]):
- Phone with number '123456' will be recorded. This is defined in the following lines:
filter1_condition = caller-number = '123456' OR callee-number = '123456'
filter1_action = record - Audio files for this phone will be stored initially inside directory C:\MyCalls\. See:
filter1_filename = C:\MyCalls\%{setup-time#%Y%m%d%H%M%S}.mp3
- All other calls will be ignored. See:
[Filters::OnCallStart]
default_action = ignore - When calls are completed, audio files will be moved to directory D:\MyRecordings\. See:
[Filters::OnCallStop]
default_action = rename
default_filename = D:\MyRecordings\%{filename}
Syntax Of Recording Filter Condition
Syntax
Condition of recording filter has following syntax:
<filter-name> condition = [ NOT ] EXPRESSION [ AND | OR ] [ ( ] EXPRESSION [ ) ] ...
Where, EXPRESSION is:
CALL-PARAMETER [ = | > | >= | < | <= | <> | != | LIKE | RLIKE ] [ VALUE | CALL-PARAMETER ]
- CALL-PARAMETER is a call parameter, like caller-IP, caller-number, duration etc.
- VALUE is a literal value, to which a call parameter is compared, for example, 1234, "John Smith" etc.
- =, >, >=, <, <=, <>, !=, LIKE and RLIKE are comparison operators.
Examples of recording filter condition:
filter1 condition = caller-ip = 192.168.0.1
filter2 condition = caller-number = 1234 OR caller-number = 5678
filter3 condition = caller-ip = 10.0.0.0/24 AND NOT callee-ip = 192.168.1.2
filter4 condition = (caller-number = 100 OR caller-number = 200) AND callee-number <> 300
filter5 condition = caller-number LIKE '011%'
filter6 condition = caller-number RLIKE '^011(22|34).*$'
Call parameters
The following table lists all supported call parameters.
Call parameter | Description |
---|---|
caller-ip callee-ip |
IP-address of caller/callee Formats:
where:
Examples: caller-ip = 192.168.0.1 caller-ip > 10.0.1.5 AND caller-ip < 10.0.1.20 callee-ip = 10.0.2.0/255.255.255.0 callee-ip = 10.0.2.0/24 |
caller-port callee-port |
IP port Examples: caller-port = 5060 caller-port = 1720 OR callee-port = 1720 |
caller-mac callee-mac |
MAC-address. Format: XX-XX-XX-XX-XX-XX Examples: caller-mac = 01-02-34-56-AF-F5 |
caller-number callee-number |
Phone number Examples: caller-number = 123456 caller-number = '+100' OR callee-number = '+100' caller-number LIKE '011%' |
caller-name callee-name |
Name of phone. The value of this parameter depends on the VoIP signaling protocol (SIP, H.323, Skinny, etc.). Examples: caller-name = "John Smith" caller-name = "Marry" OR callee-name "Marry" |
caller-id callee-id |
Id of phone. The value of this parameter depends on the VoIP signaling protocol (SIP, H.323, Skinny, etc.). Examples: caller-id = user1@sip.example.com caller-id = Phone41 OR callee-id = Phone41 |
agent-id agent-name |
Id and Name of Agent. These parameters are available only when Avaya TSAPI integration is enabled. Examples: agent-id = 50001 agent-name = 'John Smith' |
transfer-from-number transfer-from-name transfer-from-id |
Number, name, and id of phone, from which the call was transferred. The value of this parameter depends on the VoIP signaling protocol (SIP, H.323, Skinny, etc.). Examples: transfer-from-number = 123456 transfer-from-name = 'John Smith' |
transfer-to-number transfer-to-name transfer-to-id |
Number, name and id of phone, to which the call was transferred. The value of this parameter depends on the VoIP, signaling protocol (SIP, H.323, Skinny etc.). Examples: transfer-to-number = 12456 transfer-to-name = 'John Smith' |
setup-time |
Date/time when call was started Format: YYYY-mm-DD HH:MM:SS Where:
Example: setup-time = 2007-06-10 13:45:51 |
VoIP-protocol |
VoIP protocol of the call. It is a numeric value, one of:
Example: voip-protocol <> 0 |
sip-header-invite |
Value of specific SIP header inside INVITE message. The name of header is specified after hash (#) symbol. Examples: sip-header-invite#User-Agent LIKE "Asterisk%" |
Call parameters can be compared to literal values or to other call parameters, like:
caller-ip = 10.0.0.1
caller-port = callee-port
Literal values
Literal values are contacts, which are compared to call parameters.
Example:
caller-number = '123456789'
In above example a literal value '123456789' is compared to call parameter caller-number.
If a literal value contains space characters, then it should be enclosed into single (') or double (") quotes. For example:
caller-number = 123456789 <-- OK
caller-number = '123456789' <-- OK
caller-name = "John Smith" <-- OK
caller-name = John Smith <-- Not valid
If a literal value itself contains a quote character, for example, d’Arnaud, then use the following rules:
-
If a literal value contains either a single or double quote character, but not both at the same time, then enclose the value into different quotes, like:
caller-name = "d'Arnaud"
caller-name = 'Using double quotes charcter (")' -
If a literal value contains both single and double quote characters, precede them with a special escape character ‘\’, like:
caller-name = 'd\'Arnaud'
caller-name = "Using double quotes charcter (\")" -
If a literal value contains the escape character '\', you must double it, like:
caller-name = "Sample \\ name"
Comparison Operators (=, >, < etc.)
The following table lists all supported comparison operators.
Operator | Description | Examples |
---|---|---|
= == |
Equal to |
caller-ip = 192.168.0.1 callee-port == 5060 |
<> != |
Not equal to |
caller-ip <> 10.0.0.1 callee-port != 5060
|
> |
Greater than |
caller-ip > 10.0.0.10 |
< |
Less than |
caller-port < 3000 |
>= |
Greaten than or equal to |
caller-ip >= 192.168.0.1 |
<= |
Less than or equal to |
caller-ip <= 192.168.0.50 |
LIKE |
Simple pattern matching |
caller-ip LIKE '192.168.0.%' |
NOT LIKE |
Negation of simple pattern matching |
caller-number NOT LIKE '011%' |
RLIKE |
Pattern matching using regular expressions (REGEX) |
caller-number RLIKE '^011(22|34).*$' |
NOT RLIKE |
Negation of Pattern matching using regular expressions (REGEX) |
caller-ip NOT RLIKE '^192\.168\.(0|1)\..*$' |
Logical Operators (AND, OR, NOT)
Complex expressions can be created with the help of logical operators (AND, OR, NOT etc).
Operator | Description | Examples |
---|---|---|
AND && |
Logical AND |
caller-ip=192.168.0.1 AND caller-port=5060 caller-ip=10.0.0.1 && callee-ip=10.0.0.20 |
NOT ! |
Negates value |
NOT (caller-port > 1024 AND caller-port < 6000) ! (caller-port < 1024 OR caller-port > 6000) |
OR || |
Logical OR |
caller-ip=10.0.0.1 OR callee-ip=10.0.0.1 caller-ip=10.0.0.1 || callee-ip=10.0.0.1 |
Parentheses "(" and ")" are supported inside expressions, like:
caller-ip=192.168.0.1 AND ( callee-ip = 10.0.0.1/24 OR callee-ip = 80.25.23.10 )
Simple pattern matching (LIKE)
Pattern matching comparison supports the following wildcard characters:
Character | Description |
---|---|
% |
Matches any number of characters, even zero characters Examples:
|
_ |
Matches exactly one character Examples:
|
To test for literal instances of a wildcard character, precede it by the escape character '\'.
String | Description |
---|---|
\% |
Matches exactly one '%' character
|
\_ |
Matches exactly one '_' character
|
\\ |
Matches exactly one '\' character
|
Regular expressions pattern matching (RLIKE)
A regular expression is a powerful way of specifying a pattern for a complex search.
Examples:
callee-number RLIKE '^011(22|34).*$'
... will match any call, which was made to phone number starting either with 01122 or 01134
caller-ip NOT RLIKE '^192\.168\.(0|1)\..*$'
... will match any call, which was originated from IP 192.168.0.* or 192.168.1.*
MiaRec uses Henry Spencer's implementation of regular expressions, which is aimed at conformance with POSIX 1003.2.
Metacharacters
A regular expression for the RLIKE operator may use any of the following metacharacters and constructs:
Metacharacter | Description |
---|---|
. |
Matches any single character. For example:
|
[ ] |
A bracket expression. Matches a single character that is contained within the brackets. For example:
A '-' character between two other characters forms a range that matches all characters from the first character to the second. For example:
These forms can be mixed:
To include a literal '-' character, it must be written first or last, for example, [abc-], [-abc]. To include a literal ] character, it must immediately follow the opening bracket [, for example, []abc]. |
[^ ] |
Matches a single character that is not contained within the brackets. For example:
As above, literal characters and ranges can be mixed, like [^abcx-z] |
* |
Matches the preceding element zero or more times. For example:
|
( )* |
Matches zero of more instances of the characters sequence, specified inside parentheses. For example:
|
+ |
Matches the preceding element one or more times. For example:
|
? |
Matches the preceding element zero or one time. For example:
|
| |
The choice (aka alternation or set union) operator matches either the expression before or the expression after the operator. For example:
|
{n} |
Matches the preceding element exactly n times. For example:
|
{m, n} |
Matches the preceding element at least m and not more than n times. For example:
|
{m, } |
Matches the preceding element at least m times. For example:
|
^ |
Matches the beginning of a string. For example:
|
$ |
Matches the end of a string. For example:
|
\ |
Backslash (\) character is used for escaping metacharacters. For example:
|
POSIX character classes
The POSIX standard defines some classes or categories as shown in the following table
POSIX character class | ASCII equivalent | Description |
---|---|---|
[:alnum:] | [A-Za-z0-9] | Alphanumeric characters |
[:alpha:] | [A-Za-z] | Alphabetic characters |
[:blank:] | [ \t] | Space and tab |
[:cntrl:] | [\x00-\x1F\x7F] | Control characters |
[:digit:] | [0-9] | Digits |
[:graph:] | [\x21-\x7E] | Visible characters |
[:lower:] | [a-z] | Lowercase letters |
[:print:] | [\x20-\x7E] | Visible characters and spaces |
[:punct:] | [][!"#$%&'()*+,./:;<=>?@\^_`{|}~-] | Punctuation characters |
[:space:] | [ \t\r\n\v\f] | Whitespace characters |
[:upper:] | [A-Z] | Uppercase letters |
[:xdigit:] | [A-Fa-f0-9] | Hexadecimal digits |
POSIX character classes can only be used within bracket expressions ([ ]). For example:
[[:upper:]ab]
... will match the uppercase letters and lowercase "a" and "b".
REGEX Tester utility
Writing a correct REGEX expression may be a challenging task. We recommend using a special program REGEX Tester for testing RLIKE expressions for any syntax errors.
Download it from our website and start on your computer. Type your regular expression and a tested string into a program and click the "Test" button. Inside the "Result" field you will see either TRUE or FALSE. TRUE means that the tested string matches the expression. FALSE means that the tested string doesn't match the expression. In the case of syntax error in a regular expression, you will see a corresponding error instead of TRUE/FALSE.