App Object

Developer documentation for App object

Provided Methods

TIP: See also Common Methods, which includes methods available to both apps and drivers.

createAccessToken

Creates an OAuth access token that can be used as part of the OAuth functionality of a properly configured app. The function will return the token, but will also automatically set the state variable state.accessToken to the return value. This value can then be passed to any API Endpoint (for example those defined in the mappings section of an app) using a query string parameter called access_token.

Signature

  • String createAccessToken()

Parameters

None

Returns

The OAuth access token.

getApiServerUrl

Returns the base URL of the Hubitat cloud API.

Signature

  • String getApiServerUrl()

Parameters

None

Returns

The base URL of the Hubitat cloud API, generally https://cloud.hubitat.com/api

getFullApiServerUrl

Returns the full URL of the Hubitat cloud API for a specific App.

Signature

  • String getFullApiServerUrl()

Parameters

None

Returns

The URL of the Hubitat cloud API for the app, generally https://cloud.hubitat.com/api/hubid/apps/appid

getLocalApiServerUrl

Returns the base URL of the Hubitat local API.

Signature

  • String getLocalApiServerUrl()

Parameters

None

Returns

The base URL of the Hubitat local API, generally https://hubip/apps/api

getFullLocalApiServerUrl

Returns the base URL of the Hubitat local API for a specific App.

Signature

  • String getFullLocalApiServerUrl()

Parameters

None

Returns

The URL of the Hubitat local API for the app, generally generally https://hubip/apps/api/appid

getHubUID

Retrieves a unique identifier that represents your hub.

Signature

  • String getHubUID()

Parameters

None

Returns

A UUID that uniquely identifies your hub.

getRooms

Returns a List of Rooms the user has configured on their hub along with select information for each.

Signature

  • List<Map> getRooms()

Parameters

None

Returns

A List of Maps. Each Map contains the following keys/values:

  • id - unique Long identifying this room
  • name - a String matching the name the user provided for this room
  • deviceIds - a List of Long device IDs for devices the user has assigned to this room (note that this does not allow you to use these devices unless the user has already selected them from an input in your app, as normal)

Example: [[id:1, name:"Bedroom", deviceIds:[5, 6]], [id:2, name:"Kitchen", deviceIds:[7]]

subscribe

Subscribe to events sent from a device, app or location.

Signature

  • void subscribe(InstalledAppWrapper app, handlerMethod)

  • void subscribe(Location location, handlerMethod)

  • void subscribe(DeviceWrapper device, String handlerMethod, Map options = null) (Since 2.2.1)

  • void subscribe(DeviceWrapperList devices, String handlerMethod, Map options = null) (Since 2.2.1)

  • void subscribe(DeviceWrapper device, String attributeName, handlerMethod, Map options = null)

  • void subscribe(DeviceWrapperList devices, String attributeName, handlerMethod, Map options = null)

  • void subscribe(Location location, String attributeName, handlerMethod, Map options = null)

Parameters

  • app - Installed App to subscribe to
  • location - Location to subscribe to
  • device - Device to subscribe to
  • handlerMethod - The method to run when an event is received
  • attributeName - The name of the attribute to subscribe to
  • options - Optional values to configure the subscribe. Possible values:
    • Boolean filterEvents - Used for device subscriptions. Defaults to true, which ignores events where the value did not change (unless isStateChange is set to true on the event, in which case the event will still be handled). Set to false to receive all events.
    • String subscriptionData - (as of platform 2.4.1) Can optionally be used to pass a subscriptionData field to the handler method with the specified data, e..g, [subscriptionData: "someValue"]

unsubscribe

Unsubscribe from events sent from a device or all event subscriptions.

Signature

  • void unsubscribe()

  • void unsubscribe(DeviceWrapper device)

  • void unsubscribe(List<DeviceWrapper> deviceList)

  • void unsubscribe(DeviceWrapper device, String attributeName) (Since 2.0.7)

  • void unsubscribe(List<DeviceWrapper> deviceList, String attributeName) (Since 2.1.0)

  • void unsubscribe(DeviceWrapper device, String attributeName, String handlerMethod) (Since 2.1.0)

  • void unsubscribe(List<DeviceWrapper> deviceList, String attributeName, String handlerMethod) (Since 2.1.0)

  • void unsubscribe(InstalledAppWrapper installedApp) (Since 2.1.2)

  • void unsubscribe(Location location) (Since 2.1.2)

  • void unsubscribe(Location location, String attributeName) (Since 2.1.2)

  • void unsubscribe(String handlerMethod) (Since 2.1.2)

Parameters

  • device - The device to unsubscribe from.
  • deviceList - A list of devices to unsubscribe from.
  • attributeName - which attribute you want to unsubscribe from.
  • handlerMethod - The name of a method which was subscribed to a device event.
  • location - The location to unsubscribe from.
  • installedApp - The installed app to unsubscribe from.

Returns

None

addChildDevice

Creates a new child device and returns that device from the method call.

Signature

  • ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId) (since 2.1.9)

  • ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Map properties) (since 2.1.9)

  • ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Long hubId) (deprecated)

  • ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Long hubId, Map properties) (deprecated)

Parameters

  • namespace - The namespace of the child driver to add as a child device (optional, if not specified it will default the the namespace of the parent)

  • typeName - The name of the child driver to add as a child device

  • deviceNetworkId - unique identifier for this device

  • hubId - present for backwards compatibility, pass 1.

  • properties - optional parameters for this child device. Possible values listed below

Properties:

  • boolean isComponent - true or false, if true, device will still show up in device list but will not be able to be deleted or edited in the UI. If false, device can be modified/deleted on the UI.
  • String name - name of child device, if not specified, driver name is used.
  • String label - label of child device, if not specified it is left blank.

Returns

ChildDeviceWrapper

getChildDevices

Gets a list of all child devices for this device.

Signature

  • List<ChildDeviceWrapper> getChildDevices()

  • List<ChildDeviceWrapper> getAllChildDevices()

Parameters

None

Returns

List<ChildDeviceWrapper>

getChildDevice

Gets a specific child device with the device network id specified.

Signature

  • ChildDeviceWrapper getChildDevice(String deviceNetworkId)

Parameters

  • deviceNetworkId - The unique identifier for the device

Returns

ChildDeviceWrapper

deleteChildDevice

Deletes a specific child device with the device network id sepcified.

Signature

  • void deleteChildDevice(String deviceNetworkId)

Parameters

  • deviceNetworkId - The unique identifier for the device

Returns

None

sendEvent

Generates an event for the app based on the values in the provided map. (NOTE: App events are rarely used. Only a few built-in apps, mostly older apps, utilize this feature. Writing to logs is often a better method of communicating information, debugging, etc. This method is more commonly used in drivers to generate events that apps may subscribe to.)

Signature

  • void sendEvent(Map properties)

Parameters

  • properties - a Map of properties for the event. Valid keys are:
    • String name (required) - name of the event
    • value (required) - value of the event
    • String unit - units corresponding to the value, if appropriate
    • String descriptionText - a human-friendly description of the event or additional information
    • Boolean isStateChange - typically omitted; if true, will generate event even if previous value is the same as new value

Example

  • sendEvent(name: "myAppEvent", value: "theValue")

Returns

none

User Defined Methods

These methods should be defined in your app code and will be called as indicated below.

installed

This method is called when the app is first installed.

Signature

  • void installed()

updated

This method is called when the preferences of an installed app are updated.

Signature

  • void updated()

uninstalled

This method is called when the app is uninstalled. This method can be used to do any cleanup that is necessary.

Signature

  • void uninstalled()

Additional to be documented

  • Map getState()

  • String apiServerUrl(String url)

  • String localApiServerUrl(String url)

  • String fullLocalApiServerUrl(String url)

  • void setLocationMode(String mode)

  • void pause(Long millisecs)

  • InstalledAppWrapper getParent()

  • InstalledAppWrapper addChildApp(String namespace, String name, String label, Map properties = null)

  • void deleteChildApp(Long childAppId) DeviceWrapper getSubscribedDeviceById(Long deviceId)

  • void sendEvent(DeviceWrapper device, Map properties)

  • void sendEvent(String dni, Map properties)

  • List<Event> getLocationEventsSince(String attributeName, Date startDate, Map options = null)

  • void subscribe(Object thing, String attributeName, handlerMethod, Map options = null)

  • void subscribe(location, handlerMethod)

  • List<InstalledApp> getAllChildApps()

  • List<InstalledApp> getChildApps()

  • InstalledAppWrapper getChildAppById(Long childAppId)

  • InstalledAppWrapper getChildAppByLabel(String childAppLabel)