如何创建 3CX 自定义模板

介绍

使用 HTTP 来部署话机对于 IT 来说非常实用,大部分分机的通用设置都可以自动部署。对于 IT 来说只需要创建分机,再将话机的 MAC 地址添加进去就可以。3CX 已经将市面上大多数话机的模板添加到系统中了,但是也会有公司使用 3CX 不支持的话机。那么本篇文章将介绍如何为你们的话机创建模板。

当分机创建完成后,在以下目录会以分机的 MAC 创建一个配置文件:

%allusersprofile%/3cxpbx/Instance1/Data/Http/Templates/phones

接着将话机配置为重启后通过 3CX HTTP 服务器下载配置文件。话机在启动过程中无需用户采取任何措施。

配置流程

当我们创建了一个分级后,要在 “General” 标签中填入以下信息:

  • 分机(例 100)
  • 姓 (例 John)
  • 名 (例 Doe)
  • ID (例 100)
  • 密码 (例 100)

如果我们在 “话机配置” 标签被配置了,Web 服务将在以下文件夹中查找话机模板:

%allusersprofile%/3cxpbx/Instance1/Data/Http/Templates/phones

在 “话机配置” 标签,我们需要输入:

  • 话机的 MAC 地址 (例 000413246672)
  • 话机的型号 (例 Snom 320)
  • 话机使用的 3CX 的接口 (例 10.172.0.2)
  • 你也可以为分机配置 BLF 按键

点击 “完成” 后,3CX 管理控制台会根据我们输入的信息生成配置文件。用户确认详细信息并单击 “完成” 后,详细信息将传递到 XML 模板,并且3CX 解释器会解析以下变量:

  • 分机号 = %%extension_number%%
  • 姓 = %%extension_first_name%%
  • 名 = %%extension_last_name%%
  • ID = %%extension_auth_id%%
  • 密码 = %%extension_auth_pw%%
  • 话机 MAC 地址 = %%mac_address%%
  • 话机型号 = <description>Snom 320 SIP Phone</description>
  • 3CX 接口的 IP = %%pbx_ip%%

如何创建模板

3CX 这边使用的话机模板是通用的格式 – XML,其中包含一些必需的元素和一些可选的元素。

我们以 Snom 320 软件版本 8.x 为例创建一个模板。

请注意,3CX 系统随附的模板文件会更长,包含更多功能,但是原理都是一样的。

基础框架

这是 3CX 模板的基础框架,相当于编程中的 “Hello World!”。

<?xml version=”1.0″?>
<doc xmlns:tcx=”https://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>
<model>MyPhone Model 111</model>​
</models>
​</header>
<data>
<device>
<type>phone</type>
​<deviceconfig filename=“cfg%%mac_address%%“>
<![CDATA[Hello World!]]>
​</deviceconfig>
</device>
</data>
</doc>

其中 <![CDATA[starting tag and a ]]> 中包含的是话机的模板,使用两个双括号是为了防止转义,这是 HTML 解析机制要求的。

配置文件应该以 .ph.xml 后缀结尾,例如 mysnom.ph.xml,将该文件保存在话机模板文件夹中。

models 标签

  • <models> 标签包含了该模板下的话机配置页面中的下拉菜单中所显示的话机型号。
  • 只能有一个 <models> 标签
  • 在 <models> 标签中只能存在一种类型的标签 – <model>
  • 在 <models> 标签中,至少要有一个 <model> 标签
  • <model> 标签中必须要有话机的型号,该型号会显示在分机的话机配置页中的话机设备下拉菜单中
  • <model> 中的型号不得与其他模板中的已经存在的型号冲突

deviceconfig 标签

  • 每个 <deviceconfig> 标签将包含会在配置文件夹,为每个分机生成的配置文件。
  • 必须要有 <deviceconfig> 标签
  • 每个 <deviceconfig> 标签都需要指定 “filename” 属性。在 “filename” 属性中必须指定在配置文件中生成的配置文件的文件名
  • “filename” 属性的值会需要使用 3CX 指定的参数,这些变量将在配置文件夹中创建文件之前替换为文件名。请注意,创建的文件将覆盖配置文件夹中具有相同名称的所有先前创建的文件,因此需要特别注意,尤其是在使用具有静态值的 “filaname” 属性时。

下面以变化的 “filename” 演示:

<deviceconfig filename=“%%mac_address%%.cfg”>
…
</deviceconfig>

下面是静态的不变的 “filename” 演示:

<deviceconfig filename=“cfg_file”>
…
</deviceconfig>
  • <deviceconfig> 标签中包含内容都会在配置文件生成时被创建
  • <deviceconfig> 标签的内容可能包含特定于3CX的变量,当在配置文件夹中创建文件时,这些变量将替换在文件内容内
  • <deviceconfig> 标记的内容可以封装在 <![CDATA [起始标记和]]> 结束标记内,以避免通常需要转义的字符(例如“ <”和“&”)出现问题。建议使用此方法以简化操作。

通用 3CX 变量

3CX 的变量都是以 “%%” 开头的。下面是在 <deviceconfig> 中可以被使用的变量。

  • %%rebootip%% – IP 话机的 IP 地址。改参数只建议在话机被分配了静态 IP 或者在 DHCP 服务器中分配了 IP 的情况下使用。如果话机时不时获取到不同的 IP 地址(在未分配保留地址的 DHCP 环境中),%%rebootip%% 可能会指向不存在的 IP 地址。
  • %%mac_address%% – 话机配置界面输入的 MAC 地址,常用于生成 filename。
  • %%pbx_ip%% – 3CX 系统的 IP 地址。常用于话机注册。
  • %%pbx_http_port%% – http 端口以及 root 文件夹。通常用于告诉电话从哪个HTTP URL 检索其配置文件
  • %%extension_number%% – 在分机 “General” 页面设置的分机号。
  • %%extension_auth_id%% – 在分机 “General” 页面中的验证 ID。用于注册。
  • %%extension_auth_pw%% – 在分机 General 页面的密码。用于分机注册。
  • %%extension_first_name%% – 分机 General 页面设置的名。
  • %%extension_last_name%% – 分机 General 页面设置的名。
  • %%vm_number%% – 3CX 语音邮箱的号码。
  • %%blf1%% … %%blf16%% – 分机设置中配置的第 1 个 BLF 到第 16 个 BLF 按键。

为 Snom 320 创建一个模板

本示例将说明如何使用上面指定的 “模板” 作为起点,并将其构建为一个简单但实用的电话模板。

可从 Snom Wiki 站点获得用于设置 Snom 配置文件的文档。

创建基础模板

在本示例中,我们将模板命名为 “MySnom 320″,基础模板如下:

<?xml version=”1.0″?> 
<doc xmlns:tcx=”https://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models> 
<model>MySnom 320</model> 
</models>
</header>
<data>
<device>
<type>phone</type>  
<deviceconfig filename=”cfg%%mac_address%%“>
<![CDATA[Hello World!]]> 
</deviceconfig>
</device>
</data>
</doc> 

确认 “filename” 属性

Snom 话机允许您使用任意文件名来检索其配置设置。因此,在这种情况下,我们可以选择任意文件名组合

为确保每部电话检索自己的个性化设置,我们应在文件名中包括一些唯一标识电话的变量。电话的 MAC 地址是此的理想选择,因此,基线模板内的 “filename” 的值对此很合适。因此,例如,如果电话的MAC地址为 “001122334455”,并且已在扩展的 “话机配置” 选项卡的 “MAC地址” 字段中正确设置了此值,则 3CX 管理控制台将在配置内创建文件夹中,名为 “cfg001122334455” 的文件-替换了 %% mac_address%% 变量之后。

配置 <deviceconfig> 标签

话机要成功注册并拨打电话,需要以下信息:

  • 分机号
  • 分机验证 ID
  • 分机验证密码
  • PBX 的 IP 地址

就本示例而言,我们还将添加一个可选设置,即用户的名字和姓氏显示在话机的 LCD 上。

示例

我们在 3CX 中的分机信息如下:

  • 分机号 – 113
  • 分机验证 ID – id_113
  • 分机验证密码 – pw_113
  • PBX IP 地址 – 10.0.0.11
  • 名字 – John
  • 姓氏 – Doe

配置文件中的正确配置

Snom文档指出配置文件应包含以下内容:

  • 分机号: “user_name1$: 113”
  • 验证 ID: “user_pname1$: id_113”
  • 验证密码: “user_pass1$: pw_113”
  • PBX IP 地址: “user_host1$: 10.0.0.11”
  • LCD 显示: “user_realname1$: John Doe”

创建分机的 <deviceconfig>

将上面的信息放到 <deviceconfig> 中,如下:

deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: 113
user_pname1$: id_113
user_pass1$: pw_113
user_host1$: 10.0.0.11
user_realname1$: John Doe
]]>
</deviceconfig> 

整个模板看起来应该如下:

 <?xml version=”1.0″?>
<doc xmlns:tcx=”https://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>
<model>MySnom 320</model>
</models>
</header>
<data>
<device>
<type>phone</type>
<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: 113
user_pname1$: id_113
user_pass1$: pw_113
user_host1$: 10.0.0.11
user_realname1$: John Doe
]]>
</deviceconfig>
</device>
</data>
</doc> 

但是,由于以上是信息是固定的,因此,将模板文件保持原样将基本上将所有配置有此模板的电话都设置为具有相同的姓名,相同的分机号码,并且所有电话均在LCD屏幕上显示 “John Doe”。

将固定模板转换为动态模板

这就是最后一步了,我们需要将上门模板中固定的值替换为 3CX 特定的值。

我们将更新 <deviceconfig>:

<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: %%extension_number%%
user_pname1$: %%extension_auth_id%%
user_pass1$: %%extension_auth_pw%%
user_host1$: %%pbx_ip%%
user_realname1$: %%extension_first_name%% %%extension_last_name%%
]]>
</deviceconfig> 

最终模板看起来如下:

 <?xml version=”1.0″?>
<doc xmlns:tcx=”https://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>
<model>MySnom 320</model>
</models>
</header>
<data>
<device>
<type>phone</type>
<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: %%extension_number%%
user_pname1$: %%extension_auth_id%%
user_pass1$: %%extension_auth_pw%%
user_host1$: %%pbx_ip%%
user_realname1$: %%extension_first_name%% %%extension_last_name%%
]]>
</deviceconfig>
</device>
</data>
</doc> 

恭喜你,这样你就创建了第一份自定义模板!

我们在设置 – 模块中点击添加,将该模板上传到 3CX 中保存并使用,就可以在分机的话机配置的下拉菜单中选择我们添加的话机了。

话机配置

请查看 通过DHCP Option 66 配置部分话机