Provisioning Tags

Attributes

The system keeps a number of variables that can be accessed when processing a provisioning template. In general, attributes can be set in the URL after the ? characters. For example, a URL http://192.168.1.2/prov/template.xml?model=xyz1.0would set the attribute modelto the value xyz1.0. In addition to that, the system sets the following variables:

ip : This variable contains the IP address where the provisioning request was coming from. mac : The MAC address of the devices that is currently provisioned. If the MAC address could not be found, this parameter is empty. content-type : If the encoding is XML, this attribute is set to text/xml; otherwise it is set totext/plain. macauth: If the password that was provisioned with the MAC address was used, this attribute is set to true, otherwise it is set to false. This makes it possible to render output only if the device was previously provisioned. match: This attribute contains the characters that were matched with the character ? in the filename match. filename: This attribute contains the name of file that was matched in the HTTP or TFTP request, without a leading /. body : In case of a HTTP request this contains the body of the request. For a GET request, this is usually empty. resource: This attribute contains the unchanged file name, including possible leading / characters. host : This attribute contains the Hostof the HTTP request. user-agent : This attribute contains the User-Agentof the HTTP request. elif model : This attribute cross refrence the version of the phone has and what it can upgrade to if it's on that firmware, here's an example output:
(# We are on version {get version} {if version == ""}

No version available

{elif version < "96.86"}

We are on this version

{elif version < "95.86.54"}

We are on that version

{else}

We are on whatever version

{fi}

General Tags

{open-curly} : and {close-curly} : This tag just inserts an opening ({) or closing curly bracket (}).

Controlling Output

When rendering content, the system keeps a flag that controls weather output is generated or not. This is useful when content should be visible only in certain situations. For example, firmware path content can be rendered depending on the phone model.

{if expression}, {elif expression}, {else}, {fi} can be used to control rendering of output, depending on the expression (see below). If statements can be nested. {if_parm parameter value} : and {fi_parm parameter value}: These tags are used to suspend or resume output. If the parameter is equal to the value, the output is suspended (if_parm) or resumed (if_parm). The value is trimmed before proecssing. There is no difference between checking if the attribute is empty or not present. {ifn_parm parameter value}: and {fin_parm parameter value}: These tags work like the if_parmand fi_parm ; however the the output is suspended or resumed if the attribute is not equal to the value. {if_gt parameter value}: and {fi_gt parameter value} : These tags work similar to the previous comparision operators, but instead of testing for equality, they compare if the value if greater than the attribute. The comparision is based on string-comparison, not numberical comparison. {if_button button value}: and {fi_button} : This tag is used to help rendering buttons. The output is suspended or resumed when the button profile for the current user and the provided button is not present or it set to the provided value. This way the system can skip generating buttons when the user has not set them. Resuming the output does not require any arguments. {ifn_button button value}: and {fin_button} : These tags work like if_buttonand fi_button , however with inverted logic.

Looping and Accounts

The PBX generally attempts to provision multiple extensions in a template. Because most devices can do this in a similar fashion for each account, it makes sense to iterate through the accounts without having to copy & paste the code multiple times.

{use-account extension} : Switches to user extension. This tag makes it possibe to use the data for the specificed account. If the extension does not exist, the current user is set to no avail. {loop-start start end} : Loops through the available accounts. The numbering starts with start, or 1. If the end is specified, the PBX will count up to (but not including) the end. This makes it possible to limit the number of accounts that are being generated. {loop-end} : Marks the end of the text that should be repeated. {lc}: Insert the current iteration count. This makes it possible to render the current account number. {mac}: This tag inserts the MAC address what was used to generate the file. If there was not MAC address, this tag will not insert any text. {mac-hash reset} : This tag inserts a automatically generated password that is associated with the MAC. If reset is set to true, it clears the timer how long the device can be provisions, effectively locking down the pairing process. {ip-adr}: This tag insers the IP address of the PBX. This can be a IPv4 or IPv6 address, depending on the request and from where the provisioning request came. {sip-udp-port}, {sip-tcp-port} : and {sip-tls-port} : This tag inserts the SIP port number for the UDP, TCP or TLS transport layer. {sip-port transport} : This is like {sip-udp-port} , {sip-tcp-port} : and {sip-tls-port}, however the transport layer is provided as argument. {http-url path} and {https-url path} : This tag generates a path to the PBX web server. If the path parameter is provided, it will use the path; otherwise it will use the path prov. For example the text {https-url}/phone_settings-{mac}.xmlcould be used to generate a secure path to a provisioning template with the name https://192.168.1.2/prov/phone_settings-0123456789AB.xml. {http-resource}: Not used any more. {http-port}and {https-port} : This tag inserts the HTTP/HTTPS port of the system. {ldap-port} and {ldaps-port} : This tag inserts the LDAP/LDAPS port of the system. {attribute attribute} : Inserts the value of the attribute. {attribute-match attribute expression}: Performs a extended regular expression match on the attribute. {ere destination-attribute source-attribute extended-reguar-expression}: This tag performs an extended regular expression match on the source attribute and stores the result in the destinaton attribute.

Tags for the Current User

{account}: The account name of the current user. {mwicallback}: The number that should be dialed to retrieve a voicemail message, typically 8plus the account number. {domain}: The name of the domain for the current user. {domain-alias}: The domain-alias name of the domain for the current user. {id} : The database ID for the current user. {webhash} : The MD5 hash over the username and the password of the current user. {password}: or {sip-pass}: The SIP password for the current user. {web-pass}: The HTTP password for the current user. {pin}: The PIN code for the current user. {admin-user}: The administrator account name for the current domain. {admin-pass}: The administrator password for the current domain. {admin-pin}: The administrator PIN for the current domain. {display-name}: The display (real) name of the extension. {starcode name}: Inserts a star code of the domain. The name must be the name of the star code as it is stored in the database. {dialplan vendor}: Inserts a dial plan from the dialplans.xml file, if the plan was selected (e.g. dial plan for 4 digit extensions). {parameter name} : This tag inserts a parameter into the text. The name of the parameter identfies the entry to look for. The parameter is different from the parameters 1..3 that can be set as a user parameter (see below). {parameter1},{parameter2} and {parameter3}: Inserts the general purpose parameter for the current user. {lines} : Inserts the number of lines for the current user. {language} : Insert the language tag for the extension, e.g.en for English or frfor French. {lng item} : Insert an item from the web page dictionary. Those items are in the form filename#tag, they are rendered in the language of the extension. {emergency-numbers} : Inserts the emergency numbers of the current domain as they were entered in the web interface. {enum table field default match1=value1 ...}: Insert a field value from a table. The table can be extensionfor all extension settings or domain for domain settings. The field value is compared against the list of possible matches. If there is a match, the system inserts the value of the match. If there is no match, it inserts the default value.

Outbound Proxy

It is important that the phone can find the PBX using the SIP protocol. On the Vodia PBX this is done through the outbound proxy parameters.

{outbound-proxy transports} : Inserts a outbound proxy SIP URI for the current user. The transports parameter lists the default transport layer for this device followed by available transports, e.g. tls:udp/tcp/tls. {outbound-ip} : Inserts the IP address. {outbound-port default} : Inserts the port number. The default parameter lists the default transport layer for this device. {outbound-layer default enum1=value1} : Inserts the transport layer in the enumeration. If there was no match, insert the default value. {outbound-transport}: Insert the outbound proxy transport layer, in lower case ("udp", "tcp" or "tls"). {outbound-TRANSPORT} : Insert the outbound proxy transport layer, in upper case ("UDP", "TCP" or "TLS"). {outbound-secure default secure not-secure}: If the outbound proxy is using a secure transport layer (default being the default parameter), insert the secure field, otherwise insert the not-secure value.

Multicast Paging

The system can generate the settings for multicast paging as they are set up in the paging accounts.

{multicast-adrport group}: Insert the address and the port for the multicast group, e.g.224.1.2.3:4567. {multicast-adr group}: Insert the address for the multicast group, e.g.224.1.2.3. {multicast-port group}: Insert the port for the multicast group, e.g.4567. {multicast-size group} : Insert the packet size for multicast. This size is a global setting of the system, typically 20. {multicast-name group}: Insert the name for the multicast group as it appears in the paging account, e.g. Paging Group 1. Some devices are able to display that name when a paging message is being played back. {multicast-number group} : Insert the number for the multicast group as it appears in the paging account, e.g.78. Some devices are able to display that number when a paging message is being played back.

Button Provisioning

{blf button} : Insert the button for the current user and model. For BLF types, this inserts the parameter that was provided for the button. For other button types, there is no content being generated. {blf-label button}: Insert the label for the BLF button. {blf-prefix button}: Insert the prefix for the BLF button. This is for Yealink where before the number is dialed, the prefix is added. {blf-type button} : Insert type of the BLF like monitor, speed dial, pickup or monitor, speed dial or monitor only. {button-enum button default type=value}: This goes through the list of type=value pairs. If there is a type match, it will insert the value there. If there was no match found, it will insert the default value. This is useful to map the Vodia button type into phone-specific button types. {yealink-button-type button}: Insert the Yealink button type for the button number button. The button type selected on the PBX like BLF or speed dial etc. is translated to the Yealink button type code for that button type. {grandstream-button-type button}: Insert the Grandstream button type for the button number button. The button type selected on the PBX like BLF or speed dial etc. is translated to the Grandstream button type code for that button type. {grandstream-button-account button}: Insert the associated account of the button number button for Grandstream. It is used by Grandstream where it's buttons have an account associated with it, so the PBX fills this up with the account for the button. {button button}: Insert a button for the current user that has the button number button. This format was used to provision snom phones and should not be used any more. {button-label button}: Insert the label of the button number button. {button-param button}: Insert the paramter of the button number button. {speed-label button}: Insert first and last name from the address book with the speed dial number matching the button number button. It is used for Polycom. {speed-number button}: Insert number from the address book with the speed dial number matching the button number button. It is used for Polycom. {global var}: Inserts a variable from the global settings of the system. {certificate}: This tag renders the certificate that is being used for the current domain in base64 format. This can be used to establish a secure TLS connection between the server and the client, if the client allows a provisioning of the certificate. {image name encoding}: This tag renders an image of the user with the path name img/name. Currently only base64encoding is supported. {filehash filename}: This tag calculates the MD5 hash of the provided filename and renders the result on the output. This can be used to create a "fingerprint" of a file, so that the client can easily make a decision when a resource needs to be reloaded.

Time and Timezone

The system can generate the description that is needed for the devices to generate the correct day and time. Most devices today allow an enumeration of the time zone names so that zones that do not have a pattern (e.g. Israel, Iran) can have the proper time set up; this is preferrable to a pattern.

{tz ...}: This tag is used to generate timezone-dependent configuration data. There are several options possible:

• ntp-adr: Insert the address of the NTP server. This can be the system itself with its built-in NTP server or an external NTP server.
• enum default-zone zones...: Enumerates time zones. The enumeration is in the form name=value, where name is te name of the time zone on the PBX and value the value on how it should be rendered on the device. If the time zone was not found, the system will use the default time zone.
• gmt-offset: The GMT offset in seconds.
• gmt-offset4: The GMT offset in 15-minute intervals.
• gmt-hourminute: The GMT offset in the format H:MM.
• gmt-string: The GMT offset in the form GMT+HH:MM or GMT-HH:MM, used e.g. in Sipura devices.
• utc-string: The GMT offset in the form UTC, UTC+H:MM, GMT-H:MM, UTC+H or GMT-H.
• gmt-hour-m3: The GMT offset for snom M3 devices.
• dst-fixed: If the start day for DST is a fixed day, this tag will insert 1, otherwise 0.
• dst-offset: The number of seconds for the DST (usually 3600 seconds).
• dst-start-month: The start month for DST.
• dst-start-day: The start day for DST (when this is a fixed day, otherwise empty).
• dst-start-day0: The start day for DST (when this is a fixed day, otherwise 0).
• dst-start-dayp: The start day for DST in weeks (used in Polycom devices).
• dst-start-hour: The time when the DST starts in hours.
• dst-start-secs: The time when the DST starts in seconds.
• dst-start-time: The time when the DST starts in HH:MM.
• dst-start-wday: The day of the week when DST starts (1 = Sunday).
• dst-start-last: If DST starts at the last week of the month this will be 1, else 0.
• dst-start-week: The week of the month when DST starts.
• dst-stop-month: The end month for DST.
• dst-stop-day: The end day for DST (when this is a fixed day, otherwise empty).
• dst-stop-day0: The end day for DST (when this is a fixed day, otherwise 0).
• dst-stop-dayp: The end day for DST in weeks (used in Polycom devices).
• dst-stop-hour: The time when the DST ends in hours.
• dst-stop-secs: The time when the DST ends in seconds.
• dst-stop-time: The time when the DST ends in HH:MM.
• dst-stop-wday: The day of the week when DST ends (1 = Sunday).
• dst-stop-last: If DST ends at the last week of the month this will be 1, else 0.
• dst-stop-week: The week of the month when DST ends.
• dst-snom: The DST format for snom phones (e.g. 3600 22.03 03:00:00 22.09 04:00:00).
• dst-spa: The DST format for Cisco SPA devices (e.g. start=4/2/7/2:0:0;end=10/-2/7/2:0:0;save=1).
• dst-yealink-time-zone: The time zone information for Yealink phones (e.g. +7:30).
• dst-yealink-time-type: If the start day is fixed 0, otherwise 1.
• dst-yealink-start-time: The start day for Yealink phones (e.g. 3/5/7/2).
• dst-yealink-stop-time: The end day for Yealink phones (e.g. 10/5/7/2).
• dst-yealink-offset: The DST offset in minutes.
• dst-enable value: If DST is enabled, value or 1. If DST is not enabled, 0.
• gmt-hour offset: The GMT offset in hours plus the offset in the argument.
• parameter: Other parameters can be referenced from the timezone.xml file.

{ddmmyyhhmm}: This tag inserts the current day, month, year, hour and minute. This can be used to set the clock of the devices that is currently being provisioned or to keep a timestamp in the file.

Addressbook

The address book should be provisioned only if there is no support for other mechanisms that query the system, for example LDAP. Otherwise updates of the address book on the system will only have effect when the device is re-provisioned. Address book content is generated in a loop, similar to the generating of the account data.

{adrbook-start start end}: This tag marks the beginning of the address book loop. The start and end parameters tell the system where to start and where to end. If the parameters are not present, the system will assume 1 and 999. {adrbook-end}: This tag marks the end of the loop. {adrbook-name}: This tag inserts the name of the current address book entry, consisting of the first name and the last name, seperated by space if needed. {adrbook-first-name}: This tag inserts the first name of current the address book entry. {adrbook-last-name}: This tag inserts the last name of current the address book entry. {adrbook-number}: This tag inserts the number of current the address book entry. {adrbook-speed}: This tag inserts the speed dial number of current the address book entry.

Expressions

The value of an expression is calculated according to the following rules:

• If there are || operators, the result is set to trueif either of the sub-expressions is true.
• If there are && operators, the result is set to trueif all of the sub-expressions are true.
• To compare values, the system supports the operators ==, !=, >, <, >= and <=. If both values are IP-Addresses, the comparison is done according to the normalized values. If both values are numbers, the comparison is done according to the integer value of the values. If both values are version numbers (seperated by dots), the comparison is done starting with the first number in the version. Otherwise the comparision is done using the lowercase string value.

Arguments are evaluated in the following sequence:

• Literals are in quotes and represent themselves.
• Arguments may reference elements of the argument list, for example the model number.
• Arguments may also reference parameters set on extension, domain or system level.
• The argument active is true if there is at least one user associated with the current template.
• The argument versionrefers to the current version of the PBX, e.g. 67.0.6.
• The argument provisional is true if the MAC address was not (yet) assigned to an extension.
• The argument pairing is true if the MAC is currently open for provisioning.
• The argument valid_certificateis true when the domain of the extension has valid certificate. This is the case when the HTTP representation of the domain is httpsand not http. See the settings for the "Redirect to HTTPS" and "Use DNS names" for more details.
• If the argument matches certain global variables, the value of the variable is returned. Currently those variables are provision_http, tls_rc4, tftp_write, backup_server, app_banner_def, app_banner_fax, app_banner_vm, app_bgimages, max_ring_duration, max_call_duration, max_rec_duration, nat_tcp2, nat_udp and password_policy.