Plugins¶
This section cover the preferred way to extend the functionalities of a Wazo server. There are many extension point in Wazo, all of them can be used in combination to add complete features to you favorite PBX.
What is a plugin¶
A plugin is a set of additions made to a custom Wazo installation to add a new functionality.
What can be done with a plugin¶
Wazo plugins allow a third party to add almost anything to Wazo. Most of our services have extension points that can be used together to create a complete feature as a plugin.
Here’s a non exhaustive list of what can be done with plugins
Add configuration files to wazo services in
/etc/*/conf.d/
Add configuration files and dialplan files to Asterisk
Reload services to complete the installation
Extend wazo services using the available extension points
- wazo-auth
- xivo-confd
- xivo-confgend
- xivo-ctid-ng
- xivo-dird
Creating a plugin¶
A plugin has the following structure:
wazo/plugin.yml
wazo/rules
plugin.yml¶
The plugin.yml
file contains all the metadata of plugin. It should contains
the following fields:
description
: The description of the pluginname
: The name of the pluginnamespace
: An identifier for the author of the pluginversion
: The version of the pluginplugin_format_version
: The version of the plugin specification implemented by this plugin.depends
: Other plugins which this plugin depends ondebian_depends
: Debian packages which this plugin depends on
Example:
name: foobar
namespace: foocorp
version: 0.0.1
description: This plugin adds some foo to your Wazo
plugin_format_version: 1
depends:
- name: foobaz
namespace: foocorp
- name: admin-ui-context
namespace: official
debian_depends:
- golang-go
rules¶
The rules file is an executable that will accept the following commands
- build
- package
- install
- uninstall
Hello World¶
This example will create a plugin that adds an extension ***42 that says Hello World when called.
wazo/plugin.yml
:
namespace: demo
name: helloworld
description: Adds the extension "***42" to you dialplan to greet users
version: 0.0.1
plugin_format_version: 0
wazo/rules
:
#!/bin/sh
case "$1" in
build)
;;
package)
mkdir -p ${pkgdir}/etc/asterisk/extensions_extra.d
cp helloworld.conf ${pkgdir}/etc/asterisk/extensions_extra.d/
;;
install)
asterisk -x 'dialplan reload'
;;
uninstall)
;;
*)
echo "$0 called with unknown argument '$1'" >&2
exit 1
;;
esac
helloworld.conf
:
[xivo-extrafeatures]
exten = ***42,1,Playback(hello-world)
same = n,Return()
Plugin format version¶
0 (default)¶
A plugin in version 0 should implement the following requirements:
- an executable name
wazo/rules
that returns 0 on success for the following commands:- build
- package
- install
- uninstall
1 (recommended)¶
Version 1 adds support for the postrm instruction in the rules file.
rules commands¶
- build
- The build command is used to compile or generate files that will be included in the package.
- package
The package command is used to copy all files required by the plugin in the
<pkgdir>
directory.The pkgdir environment variable holds the prefix that will be used to build the package. If the plugin needs to install a file in
/etc/foo/bar
do the following commandsmkdir -p ${pkgdir}/etc/foo cp bar ${pkgdir}/etc/foo/bar
- install
- The install command is used at the end of the installation to execute instructions that are usually not related to the file system. It will be used as the postinst of the generated debian package.
- uninstall
- The uninstall command is used before the debian package is removed. It will be used as the prerm of the generated debian package.
- postrm (added in version 1)
- The postrm command is used at the end of the debian package removal. It will be used as the postrm of the generated debian package.