Unifi Custom API Call event action

[stefxx]

Version 4.0.19.4 and higher supports a new event action: "UniFi Custom API Call". With this event action, it is possible to get and set virtually any setting on the UniFi Network. It might be extended to Protect later as well. However, it requires some basic knowledge of the UniFi API, and because of it's endless possibilities it is quite difficult to document it fully.

Instead, the post below is an example on how to use it, created by d834758. Thanks David!

I will update this post if there are any questions on this feature that might benefits others as well.

[stefxx]

Using the new Custom API call to enable/disable and check status of a Guest Network

Background:

I wanted a way to enable and disable my guest network via HS and view the status of the Guest Network.

1. I created virtual device with an on/off state
   • I also made this discoverable via Alexa so I can say “Alexa, enable the guest network” and “Alexa, disable the guest network”
2. I created 2 events to execute on virtual device change
   • When virtual device is enabled, enable the Guest Network
   • When virtual device is disabled, disable the Guest Network
3. I created an event for status to run hourly and update the virtual device state if it is out of sync (if the network was enabled/disabled outside of HS). Unfortunately, the status information is only provided via pull, so it is necessary to obtain that on a periodic basis but it is a single REST call so the cost is low.

Preparation:

Before creating an event to manage the network, you need to obtain the network id. The easiest way to do this is to log into your Cloud Key->Settings->WiFi->click on the network name. The URL will change to:
https://<ipaddress>/network/default/settings/wifi/hotspot/form/<networkid>
where <networkid> is an alphanumeric string

If you want to assign the network to a specific AP Group, you will need that id as well. On the page above, expand the Advanced section, hover over the AP Group and “Edit” will appear. Click Edit and the URL will change to:
https://<ipaddress>/network/default/settings/wifi/hotspot/form/<networkid>/ap-groups/<apgroupid>
where <apgroupid> is an alphanumeric string

Obtaining Status:

To obtain the status of the network (along with much other configuration information), a GET is executed against rest/wlanconf/<networkid>. Stefxx provides a convenient link to the list of available commands when editing the event.

To parse out if the network is enabled or disabled, the relevant information is in the “enabled” property of the return value which can be isolated as data[0].enabled

To assign that value (true or false) to a device, the device name and property are specified in the Result field of the event as
<devicename>|<property>
For example:
GuestHotspotStatus|data[0].enabled

There are two methods to view all of the information returned (rather than just the status of enabled)

1. Run the event, then edit the action and click on the “Click here to open the last known return JSON” link which will open a new browser tab with the complete JSON
2. Omit the pipe and property name after the device name and then run the event and then view the string of the device itself

If you want to parse out other return values, an easy way to determine what to put after the pipe in the Result field is to copy the full return JSON from above and paste it into the JSONPath evaluator (link also provided in the event editor) and then experiment until you have isolated the desired data.

When all put together, you have an event that looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid>



When executed, a device will be created (or updated if it has already been created) and will hold the value true or false.

Enabling the Network:

To enable the network, a PUT is executed against the same URL, rest/wlanconf/<networkid> and the JSON Data provided specifies that the network should be enabled and the AP Group/s to use.

In this example, enabled is true to enable the network and a single AP Group id is specified (replace the <apgroupid> inside the quotes with the alphanumeric string obtained above):
{
"ap_group_ids": [
"<apgroupid>"
],
"_id": "default",
"enabled": true
}

If the network is to be assigned to all APs, the first part of the above can be omitted.
{
"_id": "default",
"enabled": true
}

It also may not be necessary to specify the id as the site information is specified in the event.

When entered into the event action, it looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid> and the blurred text at the blue arrow is the alphanumeric string obtained above as <apgroupid>:

Disabling the Network:

To disable the network, a PUT is executed against the same URL, rest/wlanconf/<networkid> and the JSON Data provided specifies that the network should be disabled.

The Data is simply:
{"enabled": false}

When entered into the event action, it looks like this where the blurred text at the red arrow is the alphanumeric string obtained above as <networkid>

Notes:

• In my configuration, the desired data was always data[0], however, it may be necessary to view the full Result JSON and determine which data block contains your desired return values.
• It’s also important to note that the JSON Result values are written to the “string” of the device specified in the Result field of the action (which makes perfect sense) but HS does not have a native way to trigger on the change of the string or on the string data itself. However, it is possible to do so with scripts or by using the EasyTrigger PI.

[stefxx]

UPDATE THE FIRMWARE ON ALL DEVICES

Here is another useful example of the "UniFi Custom API call". Update the firmware on ALL UniFi devices with a single click!



The command is: cmd/devmgr/set-rollupgrade
The HTTP Method is "POST"
And the Data is: {"types":["uap","usw","ugw"]}

I guess it is possible just to update all APs, Switches or Routers by adjusting the Data (UAP = AP, USW = Switch, UGW = Gateway/Router). Note that I have not tested this!