AppState

The AppState object encapsulates information about the state of a SmartApp attribute. These attributes are usually set in SmartApps using the sendEvent method. Here is a small code snippet that illustrates a potential use case.

// If the current state of the "status" attribute is not what is expected,
// then send and event to update it.
if (app.currentState("status")?.value != "expectedValue") {
    def text = "$app.label someAction"
    sendEvent(name: "status", value: "expectedValue", linkText: app.label,
        descriptionText: text, eventType:"SOLUTION_EVENT", data: [icon: icon, backgroundColor: color])
}

getDateValue()

The value of this Event, if the value can be parsed to a Date.

Signature:
Date getDateValue()
Returns:
Date - the value of this Event as a Date.

Warning

getDateValue() will throw an Exception if the value of the Event is not parseable to a Date.

You should wrap calls in a try/catch block.

Example:

def eventHander(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Double
    // throws an exception of the value is not convertable to a Date
    try {
        log.debug "The dateValue of this event is ${myState.dateValue}"
        log.debug "myState.dateValue instanceof Date? ${myState.dateValue instanceof Date}"
    } catch (e) {
        log.debug("Trying to get the dateValue for ${myState.name} threw an exception", e)
    }
}

getId()

The unique system identifier for this Event.

Signature:
String getId()
Returns:
String - the unique device identifier for this Event.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "event id: ${myState.id}"
}

getDescriptionText()

The description of the Event that is to be displayed to the user in the mobile application.

Signature:
String getDescriptionText()
Returns:
String - the description of this Event to be displayed to the user in the mobile application.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "event description text: ${myState.descriptionText}"
}

getDoubleValue()

The value of this Event, if the value can be parsed to a Double.

Signature:
Double getDoubleValue()
Returns:
Double - the value of this Event as a Double.

Warning

getDoubleValue() will throw an Exception if the value of the Event is not parseable to a Double.

You should wrap calls in a try/catch block.

Example:

def eventHander(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as a Double
    // throws an exception of the value is not convertible to a Double
    try {
        log.debug "The doubleValue of this event is ${myState.doubleValue}"
        log.debug "myState.doubleValue instanceof Double? ${myState.doubleValue instanceof Double}"
    } catch (e) {
        log.debug("Trying to get the doubleValue for ${myState.name} threw an exception", e)
    }
}

getFloatValue()

The value of this Event as a Float, if it can be parsed into a Float.

Signature:
Float getFoatValue()
Returns:
Float - the value of this Event as a Float.

Warning

getFloatValue() will throw an Exception if the Event’s value is not parseable to a Float.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Float
    // throws an exception if not convertable to Float
    try {
        log.debug "The floatValue of this event is ${myState.floatValue}"
        log.debug "myState.floatValue instanceof Float? ${myState.floatValue instanceof Float}"
    } catch (e) {
        log.debug("Trying to get the floatValue for ${myState.name} threw an exception", e)
    }
}

getIntegerValue()

The value of this Event as an Integer.

Signature:
Integer getIntegerValue()
Returns:
Integer - the value of this Event as an Integer.

Warning

getIntegerValue() throws an Exception of the Event value cannot be parsed to an Integer.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Integer
    // throws an exception if not convertable to Integer
    try {
        log.debug "The integerValue of this event is ${myState.integerValue}"
        log.debug "The integerValue of this event is an Integer: ${myState.integerValue instanceof Integer}"
    } catch (e) {
        log.debug("Trying to get the integerValue for ${myState.name} threw an exception", e)
    }
}

getIsoDate()

Acquisition time of this Event as an ISO-8601 String.

Signature:
String getIsoDate()
Returns:
String - The acquisition time of this Event as an ISO-8601 String.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "event isoDate: ${myState.isoDate}"
}

getJsonValue()

Value of the Event as a parsed JSON data structure.

Signature:
Object getJsonValue()
Returns:
Object - The value of the Event as a JSON structure

Warning

getJsonValue() throws an Exception if the value of the Event cannot be parsed into a JSON object.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as a JSON structure
    // throws an exception if the value is not convertable to JSON
    try {
        log.debug "The jsonValue of this event is ${myState.jsonValue}"
    } catch (e) {
        log.debug("Trying to get the jsonValue for ${myState.name} threw an exception", e)
    }
}

getLastUpdated()

The last time this Event was updated as a Date.

Signature:
Date getLastUpdated()
Returns:
Date - The last time this Event was updated as a Date.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "event was last updated: ${myState.lastUpdated}"
}

getLongValue()

The value of this Event as a Long.

Signature:
Long getLongValue()
Returns:
Long - the value of this Event as a Long.

Warning

getLongValue() throws an Exception if the value of the Event cannot be parsed to a Long.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Long
    // throws an exception if not convertable to Long
    try {
        def evtLongValue = myState.longValue
        log.debug "The longValue of this event is $evtLongValue"
        log.debug "evt.longValue instanceof Long? ${evtLongValue instanceof Long}"
    } catch (e) {
        log.debug("Trying to get the longValue for ${myState.name} threw an exception", e)
    }
}

getName()

The name of this Event.

Signature:
String getName()
Returns:
String - the name of this Event.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "the name of this event: ${myState.name}"
}

getNumberValue()

The value of this Event as a Number.

Signature:
Number getNumberValue()
Returns:
Number - the value of this Event as a BigDecimal.

Warning

getNumberValue() throws an Exception if the value of the Event cannot be parsed to a Number.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Number
    // throws an exception if the value is not convertable to a Number
    try {
        def evtNumberValue = myState.numberValue
        log.debug "The numberValue of this event is ${evtNumberValue}"
        log.debug "evt.numberValue instanceof BigDecimal? ${evtNumberValue instanceof Number}"
    } catch (e) {
        log.debug("Trying to get the numberValue for ${myState.name} threw an exception", e)
    }
}

getNumericValue()

The value of this Event as a Number.

Signature:
Number getNumericValue()
Returns:
Number - the value of this Event as a BigDecimal.

Warning

getNumericValue() throws an Exception if the value of the Event cannot be parsed to a Number.

You should wrap calls in a try/catch block.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as an Number
    // throws an exception if the value is not convertable to a BigDecimal
    try {
        def evtNumberValue = myState.numericValue
        log.debug "The numericValue of this event is ${evtNumberValue}"
        log.debug "evt.numericValue instanceof Number? ${evtNumberValue instanceof Number}"
    } catch (e) {
        log.debug("Trying to get the numericValue for ${myState.name} threw an exception", e)
    }
}

getUnit()

The unit of measure for this Event, if applicable.

Signature:
String getUnit()
Returns:
String - the unit of measure of this Event, if applicable. null otherwise.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "The unit for this event: ${myState.unit}"
}

getValue()

The value of this Event as a String.

Signature:
String getValue()
Returns:
String - the value of this Event as a String.

Example:

def eventHandler(evt) {
    def myState = app.currentState("someAttribute")
    log.debug "The value of this event as a string: ${myState.getValue()}"
}

getXyzValue()

Value of the Event as a 3-entry Map with keys ‘x’, ‘y’, and ‘z’ with BigDecimal values. For example:

[x: 1001, y: -23, z: -1021]

Typically only useful for getting position data from the “Three Axis” Capability.

Signature:
Map<String, BigDecimal> getXyzValue()
Returns:
Map < String , BigDecimal > - A map representing the X, Y, and Z coordinates.

Warning

getXyzValue() throws an Exception if the value of the Event cannot be parsed to an X-Y-Z data structure.

You should wrap calls in a try/catch block.

Example:

def positionChangeHandler(evt) {
    def myState = app.currentState("someAttribute")
    // get the value of this event as a 3 entry map with keys
    //'x', 'y', 'z', and BigDecimal values
    // throws an exception if the value is not convertable to a Date
    try {
        log.debug "The xyzValue of this event is ${myState.xyzValue }"
        log.debug "myState.xyzValue instanceof Map? ${myState.xyzValue  instanceof Map}"
    } catch (e) {
        log.debug("Trying to get the xyzValue for ${myState.name} threw an exception", e)
    }
}