Customers are defined in customers/customers.xml file.
<?xml version="1.0" encoding="utf-8"?>
<customers>
<customer id="vitelity">
<name>
Vitelity Communications, LLC
</name>
<assets url="http://www.vitelity.com/" img="vitelity.png"/>
<description>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
</description>
</customer>
</customers>
Each customer is defined as a sub element of the <customers> root element. Customer is identified by a unique id which is used in the template definition to bind a customer to a specific template. The following table describes the customer definition format.
| Element | Sub element | Attributes | Description |
| customer | id |
Customer unique identifier. example: vitelity Must be URL friendly (alphanumeric characters, dashes and underscore only) |
|
| name | Customer name for display purpose | ||
| assets |
url |
Customer web site URL | |
|
img |
Customer logo image | ||
| description | Customer description paragraph. |
Products are defined in products/products.xml file.
<products>
<product id="vega100">
<name>
Vega100: E1/T1 Digital Gateway
</name>
<assets url="http://sangoma.com/products/voip_gateways/vega_appliance_series/vega100.html " img="vega100.jpg"/>
<description>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
</description>
</product>
</products>
Each product is defined as a sub element of the <products> root element. Product is identified by a unique id which is used in the template definition to bind a product to a specific template. The following table describes the product definition format.
| Element | Sub element | Attributes | Description |
| product | id |
Product unique identifier. example: vega100 Must be URL friendly (alphanumeric characters, dashes and underscore only) |
|
| name | Product name for display purpose | ||
| assets |
url |
Product web site URL | |
|
img |
Product logo image | ||
| description | Product description paragraph. |
Templates are defined in individual files in the templates directory, see example.
<?xml version="1.0" encoding="utf-8"?>
<template>
<!--
Template general information
Identify template by id (carrier name), appliance model, submodel...
-->
<general>
<id customer="vitelity" product="vega100" configuration="23chan-dhcp"/>
<description>
VITELITY - VEGA 100 - 23 channels DHCP Configuration Template
</description>
</general>
<!--
Template configuration parameters description:
field = Token name containing user input when process target (enclosed by
$$ ex: field=test -> $$test$$)
label = Label displayed in the form
type = Form input type (text, date, dropdown...)
rules = Contains validation rules to apply to field before proceeding to
target creation (rules are either built-in or generic with parameters).
Multiple rules separated by |.
Parameter can contain help section and incase of enumeration the
key/value pairs to use.
-->
<parameters>
<parameter field="public-ip-address" label="Public IP address" type="text" rules="required|valid_ip_or_fqdn"/>
<parameter field="username" label="SIP User Name" type="text" rules="required"/>
<parameter field="password" label="Password" type="text" rules="required"/>
<parameter field="sip-proxy" label="SIP Proxy" type="text" rules="required|valid_ip_or_fqdn"/>
</parameters>
<!--
Definition of target 'jobs', can be one or multiple
Job types:
file - Create a file
type = output and/or validation format: txt, xml...
name = output file name or template name
data section = Unparsed text containg the actual file content template
Fields defined in 'parameters' section are embedded in the content
(enclosed by $$) and will be replace by user input (see ex line 72)
-->
<targets>
<file type="txt" name="vitelity-vega100-23chan-dhcp.txt">
<data>
<![CDATA[
;writing file ...
;PUT completed
;
; Script generated using
; PUT MEM:0x820c82cc;length=0x00026666,buffer=0x820c82cc
;<all>
; CONFIGVERSION:$$sacs_template_name$$:$$sacs_generate_date$$
;
... All Configuration file
]]>
</data>
</file>
</targets>
</template>
A template is divided in 3 sections:
The general section contains template unique identification. Unique identifier is composed of customer id + product id and a configuration identifier.
| Element | Attributes | Description | Possible Values |
| id | |||
| customer | Customer id (as defined in customers.xml) | ||
| product | Product id (as defined in products.xml) | ||
| configuration |
Configuration identifier Must be URL friendly (alphanumeric characters, dashes and underscore only) |
||
| description | Template description paragraph. |
The parameters section contains the list of parameters the user must/should fill to produce a configuration. Those parameters definition are used to generate the web form presented to the user for a specific template.
A parameter field is the token replaced in the template data to produce specific user configuration. To avoid name collision $$ tokens are added as prefix and suffix to the parameter field name.
Example:
field='ip-address' -> Token searched/replaced in data content is $$ip-address$$
| Element | Sub-Element | Attributes | Description | Possible Values |
| parameter | ||||
| field | Field name (or token). Every occurrence of this token in the data template section will be replaced by user input value. | MUST be URL friendly | ||
| label | Field form label. | |||
| type | Field input type. |
|
||
| rules |
List of validation rules to apply on user input. multiple rules are separated by | Ex: required|valid_ip = Field is mandatory and must contains a valid IPv4 address. |
|
||
| default | (Optional) Default field value. | |||
| code |
Only for generated field type. PHP code to execute. Other field can be referenced in the code using their $$ modified name. Example: code="substr('$$username$$', 0, 3);" Extracts the first 3 letter of username field. |
|||
| description | (Optional) Field description, used as contextual help. | |||
| options |
Only for dropdown field type, list the available options. Use following sub-element format: <option value="the value" label="the label"/> |
The targets section contains one or more target to be build upon successful user input validation.
If more than one target is defined in the targets section, artifact produced will be an archive (zip) containing all produced targets.
| Element | Sub Element | Attributes | Description | Possible Values |
| file | ||||
| type | Type of file to produce. |
|
||
| name | File name to produce | |||
| data | Template data enclosed in an CDATA (unparsed) XML element. Content of data element is used to produce file target, all fields (tokens) are replaced in the content before producing output. |
In addition to template parameters, some internal fields can be defined in the data section and will be replaced at generation time, the following table lists the internal fields.
| Field | Description |
| $$sacs_template_name$$ |
Replaced by the template identification name: <customer-id>-<product-id>-<configuration-id> Ex: vitelity-vega100-23ch-dhcp
|
| $$sacs_generate_date$$ |
Replaced by date time of generation: DD/MM/YYYY HH:MM:SS |
[[include:TOC]]