UCRM - Plugins


Overview


This article describes how to enable UCRM plugins to extend the functionality of UCRM.

NOTES & REQUIREMENTS: UCRM plugins are compatible with UCRM v. 2.10.0 and higher.

Table of Contents


  1. Introduction
  2. How to Enable Plugin
  3. UCRM Plugin Creation and Modification Requirements
  4. Related Articles

Introduction


Back to Top

Plugins are open-source programs that extend the functionality of UCRM. These plugins can make your UCRM experience even better by adding a number of useful and time-saving features to your installation: 

  • Automatic bank data imports
  • Integration with external accounting software
  • Enhanced integration with 3rd-party hardware and tools
  • Custom data modifications and bulk actions
  • Various exports or imports
  • Basically, anything you can imagine thanks to UCRM API
  • And one more thing: Thanks to new UCRM webhooks, you can trigger the plugin automatically based on various action (e.g. when a late payer client is suspended)

As we are working hard to implement the most requested and valuable features and integration into UCRM, we realize there are many in the UCRM community who have ideas and needs. With UCRM Plugins, you can create your own plugin or improve an existing plugin and then push your updates to the open source repository to share your code, ideas, and comments with other members of the UCRM Community.

There are many plugins available to download. Take a look at the currently available plugins at: https://github.com/Ubiquiti-App/UCRM-plugins


How to Enable Plugin


Back to Top

  1. Find the plugin you need and download its ZIP archive. Each plugin will have a description and instructions that are more specific than the ones below.
  2. Upload the ZIP archive in UCRM (System > Plugins). Here it will be checked, and if validated, extracted to a folder with the plugin's name.
  3. Enable the plugin and configure its settings.
  4. That's it, let UCRM run the plugin repeatedly or click to execute it on demand.

UCRM Plugin Creation and Modification Requirements


Back to Top

These plugins are under MIT license enabling anyone to contribute any upgrades to existing plugins or create new ones. Plugins are PHP programs and are automatically executed based on a user-defined period.

NOTE: Some basic knowledge of scripting will be necessary to Create or Modify a UCRM Plugin.

File structure


The minimum valid plugin consists of 2 files, manifest.json and main.php. These files are required for successful installation in UCRM. Other than the required files, archives can contain anything the plugin needs (with some exceptions, see Reserved Files below).

  • manifest.json: This file contains all needed information about the plugin, like name, author and required configuration. See the manifest documentation for more information.
  • main.php: Main file of the plugin. This is what will be executed when the plugin is run by UCRM.
  •   public.php: If this file is present, public URL will be generated for the plugin which will point to this file. When the URL is accessed, the file will be parsed as PHP script and executed. This file is optional.

Reserved Files 


These files cannot be contained in the plugin archive as UCRM handles them and they would be overridden.

ucrm.json

This is an auto-generated file, created after plugin is installed in UCRM. It contains prepared configuration, that the plugin can use right away. The configuration is automatically refreshed, when changes are made in UCRM settings.

The following options are available:

  • ucrmPublicUrl - URL under which is UCRM publicly accessible, this will be null if the Server domain name or Server IP options are not configured in UCRM.
  • pluginPublicUrl - URL under which the public.php file is publicly accessible, this will be null if the plugin does not have public.php file or if the Server domain name or Server IP options are not configured in UCRM.
  • pluginAppKey - An App key automatically generated for the plugin (with write permissions), which can be used to access UCRM API.

Example of the ucrm.json file:

{
    "ucrmPublicUrl": "http://ucrm.example.com/",
    "pluginPublicUrl": "http://ucrm.example.com/_plugin/dummy-plugin",
    "pluginAppKey": "5YbpCSto7ffl/P/veJ/GK3U7K7zH6ZoHil7j5dorerSN8o+rlJJq6X/uFGZQF2WL"
}

"data" directory

This directory is protected in between updates of the plugin. Anything in this directory will not be touched. All other files will be deleted and new files will appear from the plugin archive.

data/config.json

Plugin configuration will be saved to this file. When the UCRM plugin config form is saved, this file will be regenerated. Values can be modified by the plugin manually but any manual changes to the keys by the plugin will be discarded during any plugin configuration update.

data/plugin.log

Anything this file contains will be displayed as text on plugin detail page in UCRM.

.ucrm-plugin-running

This file is used to prevent multiple plugin execution if the previous instance is still running.

NOTE: Please note, that regardless of execution period chosen by the user, the plugin is never executed if the previous instance did not finish. If the script does not finish in an hour, it will be automatically killed.

.ucrm-plugin-execution-requested

This file is used to plan execution of the plugin from UCRM frontend, regardless of the chosen execution period.


Related Articles


Back to Top

UCRM - API Usage


We're sorry to hear that!