Top

Ruleset Replacement Expressions

Ruleset replacement expressions are used when the value of a parameter, a command or an action is not known in advance, i.e. the value depends on the result of the SIP message processing.

A Ruleset replacement expression is a string that represents a SIP processing status. Replacement expressions always start with the dollar (“$”) sign followed by an identifier. When the Ruleset uses a replacement expression, the replacement expression is replaced by the value of the SIP processing status representing the replacement expression.

For example,
  • $aU uses the User part of the P-Asserted-Identity header
  • $th uses the Host part of the To header
  • sip:$aU@$th, used as the parameter of the Set R-URI action, uses the P-Asserted-Identity and To headers of the incoming request and puts them into the Request URI of the outgoing request.
Note: Special characters should be backslash-escaped, for example, as follows: \ → \\ or $ → \$
Note: It is important to know that if a mediation action (Section SIP Mediation) changes the content of a SIP message, the replacement expression will refer to the value after modification. E.g., if you apply the rule action “SetFrom(sip:new@from.com)”, $fu will return new@from.com!

Top

Ruleset Replacement Expression Exhaustive List

Macro Replacements Description
$r Request-URI (R-URI). The expression refers to current Request-URI which may be changed during the course of request processing
$r. Complete R-URI header
$ru user@host[:port] part of R-URI
$rU User part of the R-URI
$rd R-URI domain (host:port)
$rh Host part of the R-URI
$rp Port number of the R-URI
$rP R-URI Parameters
$f From header
$f. Complete From header field
$fu user@host[:port] part of the From URI
$fU User part of the From URI
$fd From URI domain (host:port)
$fh Host part of the From URI
$fp Port number of the From URI
$fn Display name of the From header field
$fP Parameters of the From header field. Does not include the parameters of the URI.
$ft The tag of the From header field
$fH The name of the From header field, exactly as it is stated in the SIP request.
$t To header
$t. Complete To header
$tu user@host[:port] part of the To URI
$tU User part of the To URI
$td To URI domain (host:port)
$th Host part of the To URI
$tp Port number of the To URI
$tn Display name of the To header field
$tP Parameters of the To header field. Does not include the parameters of the URI.
$tt The tag of the To header
$tH The name of the To header, exactly as it is stated in the SIP request.
$a P-Asserted-Identity (PAI)
$a. Complete PAI header.
$au user@host[:port] part of the PAI URI
$aU User part of the PAI URI
$ad PAI URI Domain (host:port).
$ah Host part of the PAI URI
$ap Port number of the PAI URI
$aP Parameters of the PAI header field. Does not include the parameters of the URI.
$at The tag of the PAI
$aH The name of the PAI header field, exactly as it is stated in the SIP request.
$p P-Preferred-Identity (PPI)
$p. Complete PPI header field.
$pu user@host[:port] part of the PPI URI.
$pU User part of the PPI URI.
$pd PPI URI Domain (host:port).
$ph Host part of the PPI URI.
$pp Port number of the PPI URI.
$pP Parameters of the PPI header field. Does not include the parameters of the URI.
$pt The tag of the PPI header field.
$pH The name of the PPI header, exactly as it is stated in the SIP request.
$c Call-ID
$ci Call-ID of the SIP request
$s Source party
$si Source IP address of the inbound SIP request
$sp Source port number of the inbound SIP request
$d Expected destination party
$di Destination IP address of the outbound SIP request. This replacement expression is only available in outbound rules.
$dp Destination port number of the outbound SIP request. This replacement expression is only available in outbound rules.
$R Interface of the inbound SIP request
$Ri IP address of the Signaling Interface on which the inbound SIP request was received
$Rp Port number of the Signaling Interface on which the inbound SIP request was received
$Rf ID of the Signaling Interface on which the inbound SIP request was received
$Rn Name of the Signaling Interface on which the inbound SIP request was received
$RI The configured address of the SignalingInterface.PublicIpAddr parameter on which the inbound SIP request was received
$H Arbitrary Headers.

The replacement expressions in this group mention the name of an arbitrary header between parentheses. The core headers (From, To, Call-ID, Via, Route, Record-Route, Contact) cannot be replaced.

Example: $H(Server) will be replaced by the value of the Server header field.

$H(headername) Value of the 'headername' header
$HU(headername) User part of the URI in the 'headername' header.
$Hd(headername) URI Domain (host:port) of the 'headername' header.
$Hu(headername) user@host[:port] part of the URI in the 'headername' header.
$Hh(headername) Host part of the URI in the 'headername' header.
$Hp(headername) Port number of the URI in the 'headername' header.
$Hn(headername) Display name of the 'headername' header.
$HP(headername) Parameters of the 'headername' header field. Does not include the parameters of the URI.
$HH(headername) Header headername (as URI) headers
$m Request method
$m The method of the request.
$V Call parameter
$V(gui.varname) Value of the 'varname' call parameter.
$B Cnum and Rnum
$B(cnum.rnum) Value of the regular expression backreference.
  • Rnum is the index of the rule condition containing the regular expression, starting at 1.
  • Cnum is the index of the subexpression within the regular expression, starting at 1.
$U Register cache
$Ua Originating AoR from the registration cache. This replacement expression can only be used after the execution of a‘Restore contact from registrar’ or a ‘Retarget R-URI from cache’ action.
$UA Originating alias from the registration cache. This replacement expression can only be used after the execution of a ‘Restore contact from registrar’ or a ‘Retarget R-URI from cache’ action.
$_ Operations on Values
$_u(value) Changes the value to uppercase.
$_l(value) Changes the value to lowercase.
$_s(value) Size of the value.
$_5(value) MD5 sum of the value.
$_r(value) Random number from 0 to 'value' - 1. Example: $_r(5) gives 0, 1, 2, 3 or 4.
$# URL-encoded
$#(value) Encodes the value into a URL format with appropriate escaping for characters outside the ASCII character set.
$attr Global Attributes
$attr(version) Version number of the DGW firmware. The returned value matches with the %version% macro in DGW firmware.
$attr(profile) Profile identification of the DGW firmware. The returned value matches with the %profile% macro in DGW firmware.
$attr(serial) Serial number of the Mediatrix unit. The returned value matches with the %serial% macro in DGW firmware.
$attr(mac) MAC address of the Mediatrix unit. The returned value matches with the %mac% macro in DGW firmware.
$attr(product) Product name of the Mediatrix unit. The returned value matches with the %product% macro in DGW firmware.
$attr(productseries) Product series name of the Mediatrix unit. The returned value matches with the %productseries% macro in DGW firmware.

Top

DGW Documentation

Mediatrix devices are supplied with an exhaustive set of documentation.

Mediatrix user documentation is available on the Media5 Documentation Portal.

Several types of documents were created to clearly present the information you are looking for. Our documentation includes:
  • Release notes: Generated at each GA release, this document includes the known and solved issues of the software. It also outlines the changes and the new features the release includes.
  • Configuration notes: These documents are created to facilitate the configuration of a specific use case. They address a configuration aspect we consider that most users will need to perform. However, in some cases, a configuration note is created after receiving a question from a customer. They provide standard step-by-step procedures detailing the values of the parameters to use. They provide a means of validation and present some conceptual information. The configuration notes are specifically created to guide the user through an aspect of the configuration.
  • Technical bulletins: These documents are created to facilitate the configuration of a specific technical action, such as performing a firmware upgrade.
  • Hardware installation guide: They provide the detailed procedure on how to safely and adequately install the unit. It provides information on card installation, cable connections, and how to access for the first time the Management interface.
  • User guide: The user guide explains how to customise to your needs the configuration of the unit. Although this document is task oriented, it provides conceptual information to help the user understand the purpose and impact of each task. The User Guide will provide information such as where and how TR-069 can be configured in the Management Interface, how to set firewalls, or how to use the CLI to configure parameters that are not available in the Management Interface.
  • Reference guide: This exhaustive document has been created for advanced users. It includes a description of all the parameters used by all the services of the Mediatrix units. You will find, for example, scripts to configure a specific parameter, notification messages sent by a service, or an action description used to create Rulesets. This document includes reference information such as a dictionary, and it does not include any step-by-step procedures.

Top

Copyright Notice

Copyright © 2022 Media5 Corporation.

This document contains information that is proprietary to Media5 Corporation.

Media5 Corporation reserves all rights to this document as well as to the Intellectual Property of the document and the technology and know-how that it includes and represents.

This publication cannot be reproduced, neither in whole nor in part, in any form whatsoever, without written prior approval by Media5 Corporation.

Media5 Corporation reserves the right to revise this publication and make changes at any time and without the obligation to notify any person and/or entity of such revisions and/or changes.