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

[takeiteasyeh]

It would be extremely useful to have a built-in version of the API using some kind of class object to wrap around the database

$clients = UcrmData::getClients(array('id' => 3));


ect


along with UcrmData::patchClient(array()))

This would also help to limit the overhead in larger transactions by avoiding calls to the httpd platform and seems more natural than having to access local information through curl. Alternatively, being able to extend the client object to receive the information would also be acceptable if we could get documentation on the models.

[UBNT-Petr]

@takeiteasyeh that's good idea and actually, you can do this right now. The Plugin is executed inside the docker container along with the rest of UCRM, so the direct access to the database from the plugin is possible. See the config file /home/ucrm/docker-compose.env for logging into your UCRM database.

However, this approach is extremly risky, you may crash your UCRM and you should know what you are doing. It also requires the knowledge of UCRM internal database and its structure. Modifying the data directly without this knowledge may have bad consequences.

That's why we provide API which is a safe layer between users and UCRM database and we can provide the support for this and btw, also the API is pretty powerful - your example (find client by any attribute & value) can be achived by this: https://ucrm.docs.apiary.io/#reference/clients/clients/get

Indeed, some batch modifications can take a while if you have huge database. But on the other hand, how often do you need to modify all the clients or all their services? And does it really matter that the script execution takes more time in this case?

[takeiteasyeh]

@UBNT-Petr

I assume the good idea is in regards to having a static method to call that can mimic the api?

At the end of the day it's not just about speed/efficiency, it's also about the fact that it would be more natural to be able to access an internal object to do the queries rather than parsing curl responses.

It is much simpler to do:

$users = API::fetchUsers();

while ($users = $user)
{
  $hasUpdated = false;

 // run remote billing, petting, whatever

   if ($hasUpdated)
     API::patchUser($user->clientID,
                             array(
                            'fieldtochange' => $somecoderesult,
                            'otherfield' => $someotherresult));
}
                            

I hate the fact that, when doing something like billing, hundreds of calls are being sent internally to curl when, in my opinion, best practice of a internal interface, would reduce the overhead greatly. This seems like a more scalable solution. I appreciate the external API, but I would prefer to only have to use that remotely when I dont have actual access to the internal functions/objects.

Also, yes please on the admin interface ect. I have developed a signup form plugin but would rather have an admin panel area where signups are verified to be added to ucrm (ie: You have x signup requests) on the dashboard or even a seperate admin area for said plugin.

Thanks for all your hard work

[takeiteasyeh]

Didnt preview as bold.. Guess I've just got some magical touch...