Please note this docuemntation is in BETA


Zegami has a flexible plugin architecture which makes it possible to extend its functionality to support custom use cases. Blueprints represet the most powerful plugins as it allows Zegami to host custom API endpoints that can communicate with internal Zegami modules.

Zegami Server is built with Python v3.5, which is an interpreted language. This means Zegami plugins can be created with a simple text editor and no additional compilation is required.

Internally Zegami uses the Flask microframework for all it's API endpoints. Because of this, Zegami is able load and register custom Flask Blueprints which can then be used by the Zegami client or other applications. For more details on Flask Blueprints see the official documentation http://flask.pocoo.org/docs/0.12/blueprints/

This tutorial will take you through creating a simple Hello World example of a Blueprint plugin.

Hello World

With a text editor create a new file called HelloWorldBlueprint.py.

To get started we first need to import the neccesary modules.

from flask import Blueprint

In this case we are importing Blueprint from the flask module.

Next we define the plugin metadata. This is used by Zegami to identify the name, description, version number and the engine or main class of the plugin.

# plugin version number
version = '1.0.0'
# name reference for plugin. This name will be used as part of the prefix of an URL
name = 'HelloWorld'
# engine must contain the class name of the blueprint
engine = 'mod_hello_world'
# description
description = "Hello World! REST API endpoint"

Now that we have set up the plugin we can create a Blueprint instance called 'HelloWorld' and assign it to the mod_hello_world variable.

mod_hello_world = Blueprint('HelloWorld', __name__)

Finally we can define the hello function and bind it to a route using the route decorator.

@mod_hello_world.route('/')
def hello():
    return 'Hello World!'

That's it! The full file is avaliable here to download.

Now that the plugin is created the next step is to register it with Zegami.

Registering the plugin

In order for Zegami to load a plugin it needs to be placed in a location where it can find it. The Zegami installation includes a plugins directory where all plugin files need to be placed.

Place the hello.py file into the blueprints directory in the plugins directory. On Windows this is located at: C:\Program Files\Zegami\Lib\site-packages\zegami\plugins\blueprints and on Linux this is at: /opt/zegami/plugins/blueprints

The plugin then needs to be activated. To do this edit the plugins.conf file which is located in the conf directory. On Windows this is located at: C:\Program Files\Zegami\conf\plugins.conf and on Linux this is at: /opt/zegami/conf/plugins.conf.

In the [Blueprints] section add the follwoing new line

[Blueprints]
HelloWorldBlueprint=

The last thing left to do is restart the Zegami web service. On Windows Server this can be done by running iisreset from the command line, on Windows desktop the command is net stop ZegamiWeb' then 'net start ZegamiWeb' and on Linux the command issudo supervisorctl restart zegami_uwsgi`.

Testing

Now that the plugin has been registered we can now see the results.

Open a browser and navigate to: http://localhost/api/plugin/helloworld/. You should see the "Hello World!" message displayed in the window.

Hello World plugin

Dependencies

Our example wasn't very complicated, but for non-trivial applications 3rd party modules may be required. For dependency management Zegami uses the Conda package management system.

To list all of the avaliable packages included in the Zegami environment from the terminal run:

conda list

Note for linux Zegami is installed as the zegami user. To access the Python and Conda environment you first need to run sudo su zegami to run as the zegami account.

To install a dependency, for example OpenCV run

conda install opencv

Once installed, OpenCV can be imported as normal

import cv2