Reply
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

[ Edited ]

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?

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

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.
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

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.

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

[ Edited ]

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'

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

Sure, the public URL of a plugin can be used as an endpoint for webhook in UCRM or any other system.
Thanks for typo.
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

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

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Ubiquiti Employee
Posts: 915
Registered: ‎03-21-2016
Kudos: 150
Solutions: 111

Re: UCRM Plugins are here!!

@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.

Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

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

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

[ Edited ]

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.

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Highlighted
Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

@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

Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

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

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

@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

 

Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

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.

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
Emerging Member
Posts: 85
Registered: ‎03-19-2018
Kudos: 14
Solutions: 2

Re: UCRM Plugins are here!!

[ Edited ]

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.

HTML, SCSS, Javascript(Ember.js), Ruby(Ruby on Rails), PHP
New Member
Posts: 3
Registered: ‎03-07-2018

Re: UCRM Plugins are here!!

Markb450... can you assist me in creating a plugin to change client speed during specific times of the day?
Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

@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
New Member
Posts: 20
Registered: ‎11-08-2016

Re: UCRM Plugins are here!!

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.

Ubiquiti Employee
Posts: 2,782
Registered: ‎12-10-2015
Kudos: 1004
Solutions: 231

Re: UCRM Plugins are here!!

@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?
New Member
Posts: 20
Registered: ‎11-08-2016

Re: UCRM Plugins are here!!

@UBNT-Petr

 

 

 

 

$users = API::fetchUsers();

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

 // run remote billing, petting, whatever

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

 

 

New Member
Posts: 20
Registered: ‎11-08-2016

Re: UCRM Plugins are here!!

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

Reply