15. Templates

Various forms of templates are available. These include templates that add additional, custom fields to the IPplan display pages (different templates can be added to the customer, subnet and ip address record pages), and templates that then munipulate the data contained in the IPplan databases to generate output for various registrars. All of these templates are fully administrator customizable with display fields added to customer and subnet pages automatically available in output templates used to generate registrar updates.

15.1. Customer, Subnet, DNS and IP address templates

The administrator can define a custom template in IPplan to allow the addition of as many custom fields to the customer, subnet, DNS forward zones and ip address record pages as the administrator wishes. This functionality allows flexibility in the way data is added to the database. Some uses for these templates include tracking asset information or WAN circuit information, the management of DHCP address space, dealing with additional and ever changing registrar requirements.

As mentioned there are different template files for the customer, subnet, DNS and IP address pages. The template for each of these pages has a different name:

Customer pages - custtemplate.xml

Subnet pages - basetemplate.xml

DNS forward zones - fwdzonetemplate.xml

IP address pages - iptemplate.xml

IP address pages (network address) - iptemplate-network.xml

A sample template called iptemplate.xml.sample can be found in the /ipplan/templates/display directory.

If a template called called iptemplate-network.xml exists, then this template will be used for network addresses (the first address of the subnet). This is useful to define subnet wide information like VLAN id's, telco line numbers, router configurations etc. If the iptemplate-network.xml does not exist, then the iptemplate.xml template will be used for network addresses.

The above templates are generic and act across all customers, and thus all fields are the same for all customers. Unique templates can be created per customer by adding the customer id to the template name. To obtain the customer id (a number), use the Admin/Maintenance function within IPplan. To create a unique IP address template for customer id 25, place a template file called iptemplate-25.xml in the /ipplan/templates/display directory. This template will override the default template for customer 25 only.

15.1.1. Format of Customer, Subnet and IP address template files

The templates are well formed XML files with a .xml extension and should be stored in the /ipplan/templates/display directory. You should use the xmllint tool to test the XML file before using it with IPplan - no errors should be returned.

The standard iptemplate.xml file adds a free form text field to all the ip address record pages and has this definition:

<?xml version="1.0" ?>
<TEMPLATE>
    <FIELD>
     <DEFINITION NAME="info" DESCRIP="Additional information" TYPE="T" MAXLENGTH="10000" SIZE="80" ROWS="10" REGEX="" ERRMSG="Invalid field: Additional information" />
    </FIELD>
</TEMPLATE>

A field definition to add a select drop down list:

    <FIELD>
     <DEFINITION NAME="select" TYPE="S" DESCRIP="This is select list with two options" DEFAULT="2">
       <SELECT OPTION="Option 1" VAL="1" />
       <SELECT OPTION="Option 2" VAL="2" />
     </DEFINITION>
    </FIELD>

The template file must be surrounded with <TEMPLATE> statements. Note that XML tags are case sensitive and must match as per the example. Each field is contained in a <FIELD></FIELD> statement. Each field must have exactly one <DEFINITION> line. Any line with an error will be silently ignore! The following are valid for a definition:

NAME

This is the field name used internally to track the names of the variables. Can contain letters and numbers only - no spaces or anything else.

DESCRIP

This is the description that will be displayed above the field.

TYPE

This is the type of the field. C for a character field and T for a memo or multi-line field, S for a select drop down list.

DEFAULT

The default value for the field the first time the field is completed.

MAXLENGTH

This is the maximum number of characters a field can consist of.

SIZE

This is the display length of the field on the screen - if SIZE is less than MAXLENGTH, the field will scroll. SIZE may not be more than MAXLENGTH.

ROWS

This is the number of rows to display on the screen - only valid for text or multi-line fields.

REGEX

This is a regular expression to test validity of the entered information. To test a field, use ^ and $ to signify the start and end of the field, so something like

^[a-zA-Z0-9]$

ensures that the field only contains numbers and letters. See http://regexlib.com/ for more on regular expressions.

Regular expressions are PERL compatible and use a / character as the delimiter, thus if you want to match on a /, you will need to escape the /. So to match a letter, / and a number, this is the expression

^[a-zA-Z\/0-9]$

Regular expression | can be used for multiple matches. Thus the following will match a field or a blank entry

^[a-zA-Z\/0-9]$|^$

ERRMSG

This is the error message that is displayed if the regular expression match fails.

Default template:

The default template contains one field which is the "Additional information" field of older versions of IPplan. If you do not want this field, change the template or delete the template entirely.

Template rules:

If you delete the template all fields will vanish and cannot be accessed. IP records that have been completed with fields from a template will not be lost, but records that do not have template fields cannot have template fields added until the template is either restored or similar fields are added.

Note

Deleting fields from a template results in existing fields in the database with template data using a default field definition. The data is not lost. It is not a good idea to modify or change the template on a production system. Plan the template fields carefully before implementing.

15.2. Registrar templates

Templates for sending information to registrars should be well formed XML stylesheets. See the existing templates in the /ipplan/templates directory for examples. Currently only the

<xsl:value-of select="variable"/>

tag is understood and all other XML tags are stripped, thus only variable substitution is done. This is to prevent requiring the XSLT php library to be compiled in. In future XML stylesheets will be supported in full.

There are a number of special variables available during the registrar output process which are defined in the config.php file:

source      -> the REGISTRY config setting
maint       -> the MAINTAINERID config setting
regid       -> the REGID config setting
password    -> the REGPASS config setting
date        -> todays date in UTC format

in addition to the standard customer page variables:

ntsnum      -> starting of IP address range
ntenum      -> end of IP address range
ntname      -> network name as defined in the
               subnet description field
DNS:
hname1      -> DNS hostname 1
ipaddr1     -> Primary DNS server
hname2      -> DNS hostname 2
ipaddr2     -> Secondary DNS server
hname3      -> DNS hostname 3
ipaddr3     -> Third DNS server
   .
   .
   .
hname10     -> DNS hostname 10
ipaddr10    -> Thenth DNS server

Contact:
org         -> Organization
street      -> Street
city        -> City
state       -> State
zipcode     -> Zip code/Postal code
country     -> Two letter country code

Technical contact:
nichandl    -> Nickname/handle
lname       -> Lastname
fname       -> Firstname
mname       -> Middle name
torg        -> Organization
tstreet     -> Street
tcity       -> City
tstate      -> State
tzipcode    -> Zip code/Postal code
tcntry      -> Two letter country code
phne        -> Phone number
mbox        -> Email address

Plus any variables defined in a customer template (custtemplate.xml) and also the subnet template (basetemplate.xml) as described above will also be available. The names of the variables will be the same as defined in the customer template.

Thus the following basetemplate.xml file:

<?xml version="1.0" ?>
<TEMPLATE>
    <FIELD>
     <DEFINITION NAME="remarks" DESCRIP="Remarks" TYPE="C" MAXLENGTH="100" SIZE="100" ROWS="1" REGEX="" ERRMSG="RIPE remarks" />
    </FIELD>
</TEMPLATE>

will provide the following additional variable to the registrar template

remarks        -> Remarks field for subnet

Note

If there are duplicate variable names defined, the variables in the basetemplate.xml file, then the custtemplate.xml file appearing in the "Additional information" section of the customer and subnet administration pages will have precedence over any standard variables.