UCRM Plugins are here!! [ Edited ]

[Brandon-W]

Is there plans for further documentation on what kind of access a plugin has to the UCRM admin code/data?

Where can I find more about the new UCRM webhooks mentioned?

[UBNT-Petr]

Hi @Brandon-W UCRM Plugins are using API, so plugins can manage exactly the same scope of data as API can.
API docs: https://ucrm.docs.apiary.io/
Plugins docs: https://help.ubnt.com/hc/en-us/articles/360002433113-UCRM-Plugins

webhooks: type webhooks to the UCRM search bar or see the guide here https://ucrm-demo.ubnt.com/help/webhooks

I hope it's more clear now. If not, let us know.

[Brandon-W]

Yes! @UBNT-Petr Thank you, that's tremendously helpful. Looks like the reason I couldn't find it was because my UCRM wasn't updated.

[Brandon-W]

Could the public url of a plugin be used for webhooks? Such as if a stripe and/or ucrm webhook was set to the plugin url?

Also, the help documentation appears to have a typo. The example json is:

{ 
"uuid":"61167377-e29f-4e37-a8b1-0f782e3918d0",
"changeType":"insert",
"payment":"service",
"entityId":28
}

I think the correct output is:

{ 
"uuid":"61167377-e29f-4e37-a8b1-0f782e3918d0",
"changeType":"insert",
"entity":"service",
"entityId":28
}

 aka, 'payment' should be 'entity'

[UBNT-Petr]

Sure, the public URL of a plugin can be used as an endpoint for webhook in UCRM or any other system.
Thanks for typo.

[Brandon-W]

Is there plans to add a signature for security to UCRM webhooks?

[UBNT-Ondra]

@Brandon-W  You can verify the webhook data by pulling it from UCRM API ( https://ucrm.docs.apiary.io/#reference/webhook-events/webhook-eventsuuid/get ).

If you think signature is better, feel free to create a feature request for it, but this should be enough. If you don't care about security (e.g. some not-important actions), you can just use the data, otherwise get the event from API via HTTPS connection and if it does not exist, it's not from UCRM.

[Brandon-W]

Thank you @UBNT-Ondra I think pulling from the API will be sufficient for my purposes.

[Brandon-W]

What are the limitations on execution of the plugin script? If I am using webhooks and/or expecting payloads from another script, will one request prevent another or are they put into a queue? I don't expect a lot of traffic but wasn't sure what this note implied:

https://github.com/charuwts/UCRM-plugins/blob/master/docs/file-structure.md#ucrm-plugin-running

.ucrm-plugin-running

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

Also, does the UCRM docker have SQLite available? Could the plugin have it's own file database? Is there any plans for maybe an optional installation of such a feature? Would it hinder future updates if I were to add SQLite to the docker container myself?

I don't currently need a database but it could be helpful for future plugins.

[UBNT-Petr]

@Brandon-W

Don't worry about webhooks, they can access the plugin's URL simultaneously. This is the updated description:

.ucrm-plugin-running

This file is used to prevent multiple plugin execution if the previous instance is still running. This measure is used only for manual execution (using the "execute manually" button) and for automatic execution (using cron and execution period). The execution triggered by plugin's public URL is not affected, it can be accessed and run simultaneously by users or webhooks without any limitations.

-----------------------------------------------------------------

Regarding the database:

You can 1) add a new container with your own database or 2) use the UCRM's database.

1 - deploy a new docker container with your own database of any kind and link it with UCRM web_app container in the docker-compose.yml file. Take a look at how UCRM is using postgres container: https://github.com/Ubiquiti-App/UCRM/blob/master/docker-compose.yml#L21 and do the same with your database.

2 - use the existing UCRM's postgres database. - In this case, you should really know what you are doing as you can damage your data or crash UCRM immediately or later, during the future UCRM upgrades. If you choose this option, I suggest you use your own db/sheme or some table prefix at least. 

In your plugin, use the db credentials stored in /home/ucrm/docker-compose.env

[Brandon-W]

Could someone share an example of the data/config.json file?

[UBNT-Petr]

@Brandon-W you don't need to create the config.json file manually. It is created and maintained by UCRM automatically to store values of plugin parameters which are set by the user. The only reason why you may want to create this file is to set the default values.

In this case, this is an example of the config.json file related to QB Plugin:

{"qbClientId":"X","qbClientSecret":"Y"}

the format is key:value where the keys are listed in the plugin's manifest.json file in the configuration section. For example, see the "qbClientId" key in https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/plugins/quickbooks-online/src/manifest.json

[Brandon-W]

Thank you @UBNT-Petr, I understand the file is generated. I was looking for an example in order to parse the file. Is there a better way to access these values? I figured that's what the file was for.

In one place the docs sound like it was formatted differently then a flat object:
https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/docs/manifest.md#configuration

Determines configuration keys of the plugin. Frontend configuration form is generated from this and the values are then saved to data/config.json file.

Contains an array of items. Each item is defined as follows:

• key - property key
• label - label of the property as displayed in UCRM
• description (optional) - description of the property, displayed under the form input in UCRM
• required (optional, default: 1) - whether the property is required or optional, configuration cannot be saved without required properties

And in another place it sounds more like the example you gave:
https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/docs/file-structure.md#dataconfigjson

data/config.json

Plugin configuration (i.e. plugin's parameters and their values) will be saved to this file. When the UCRM plugin's paramteres are set by the user, this file is regenerated. Values can be modified by the plugin manually but any manual changes to the keys (e.g. removing, modifying or adding new keys) by the plugin will be discarded during any plugin configuration update. As a developer, you don't need to create this file unless you want to set default values for the parameters mentioned in the configuration section of manifest.json file.

[Brandon-W]

I misunderstood the doc, the first is refering to the manifest.json and doesn't reference the format of the config file. Sorry for the misunderstanding. @UBNT-Petr, thanks for the help.

[e-Wisp]

Markb450... can you assist me in creating a plugin to change client speed during specific times of the day?

[UBNT-Petr]

@e-Wisp although this plugin is possible, it might be complicated to configure all the parameters you need for this (e.g. for each service plan configure time period & speed)

In case your configuration is simple, for example: you got only one service plan, the plugin could handle this easily using this API: https://ucrm.docs.apiary.io/#reference/service-plans/service-plansid/patch

Otherwise, it might be better to wait till this is implemented directly in UCRM. Please comment & upvote this request: https://community.ubnt.com/t5/UCRM-Feature-Requests/Shaping-advanced-settings/idi-p/1819981