The three Switchboard item types are Switch, Counter, and Keyword. Each stores a different type of value.
When you first create a Switchboard item it has no value set. You can change a Switchboard items type whilst it has no value and is not referenced by an automation, but once the item has been updated with a value or whilst it is referenced by an automation it's type cannot be altered.
Additional settings are available under "advanced options".
Upon saving a new Switchboard item, secure urls are generated that allow it to be updated via an http method (i.e. IFTTT or Zapier webhooks, and/or Microsoft Power Automate's http connector).
The API that Switchur provides and through which value updates to switchboard items are facilitated provides a variety of responses that can inform users how the update request was handled, either successfully or unsuccessfully. The following table lists possible response codes and messages.
Successfully updated switch / counter / keyword to "__________".
The switchboard item has been successfully updated to the value specified. Accordingly, any automations that reference the switchboard item will be evaluated, and the applicable actions queued.
The switchboard item was not modified. [To help with troubleshooting, additional feedback may be available by enabling "Test Mode" and using a GET request method.
This indicates that the API request did not result in the updating of the switch / counter / keyword. This response can occur in several scenarios.
Switch / Counter / Keyword cannot be updated with a GET method request and the switch / counter / keyword value remains unchanged. The "Test Mode" option will permit any method, however we don't recommend leaving "Test Mode" enabled as it can cause unexpected updates to occur.
The HTTP/1.1 protocol defines request methods semantically (RFC 7231 #4.3.) and Switchur conforms to that specification. In essence, a GET request should retrieve a target resource and not modify it. Other methods are explicitly for modification such as POST, PUT, PATCH, DELETE. Web browsers use GET to request content, and so for convenience if the option "Test Mode" is enabled on individual switchboard items, they become susceptible to GET updates. However please note that GET is a common application-level proxy and leaving a switchboard item in this state could result in updates occuring unexpectedly e.g. the result of browsers refreshing cached content extemporaneously.
400 Bad Request
A general error occurred attempting to validate the "set to" value within the API request.
Something unexpected caused an exception to be generated. For assistance, contact Support providing key details such as the request path (the url of the request) along with your message.
400 Bad Request
Possible attempt to set counter using "out-of-bounds" value. Switchur counters can't be set to non-numeric values, or to integers with more than two decimal places, or to integer values greater than positive or less than negative one octillion (+/-10 to the 27).
This response is produced when Switchur receives a request to update a counter to an unusually large number or a number with many fractional digits. Counters are intentionally constrained and there is therefore no workaround - counter values must stay within bounds.
400 Bad Request
No switchboard item corresponds with the supplied token: A1B2C3...Y25Z26
This can be generated if using a GET method combined with "Test Mode" and attempting to update a switchboard item that has since been deleted.
400 Bad Request
Exceeded value parameter maximum length (100).
Can result if Switchur receives a request which contains a keyword value that is greater that the maximum length.
400 Bad Request
Missing a parameter.
This would suggest that the request path was malformed and a path component missing. A complete request will have the following structure "https://api.switchur.com/ [Optional item name] / [Set to value] / [Item token]".
Produced when the supplied token is spurious.
Missing authentication token.
Can result from a request where no token details are supplied.
The request could not be satisfied.
Can result from attempts to use non-standard REST protocols such as WebDAV methods (LINK, UNLINK, PURGE, LOCK, UNLOCK, PROPFIND, VIEW).
405 Method Not Allowed
DELETE / HEAD / OPTIONS is an invalid method. Only PUT, POST, and PATCH methods are permitted by default (a GET can also return status info). The "Test Mode" option will permit any method, however we don't recommend leaving "Test Mode" enabled as it can allow unexpected updates to occur (i.e. background browser interactions).
The response from Switchur when a request method is understood but not accepted.
414 URI Too Long
Maximum combined parameter length (ie. path length) exceeded.
The hard limit on the request path length was exceeded.
Display the advanced editor by expanding "Show advanced options" when editing an automation and toggling "Advanced editor". Doing this will convert existing basic automation builder components into the expression format, which can provide a useful starting point. The basic automation builder is conjunctive, and therefore when converting to an expression all atomic propositions are joined together by the conjunctive operator ("AND").
The objective of the advanced expression editor is to construct a syntactically valid logic statement that can be evaluated to exactly one of two truth-values: true or false. Be aware there is no safeguard for logical contingency to ensure both true and false are possible outcomes based on values assigned. Avoiding always true tautologies (e.g. "counter=1 or counter≠1") and always false contradictions (e.g. "counter=1 and counter≠1") is the responsibility of the user.
The advanced expression editor consists of several dropdown controls to insert elements into the expression as well as the expression text input itself. For example, an expression statement to control home lighting might be ([[Person A at home]] = ⊚ ON or [[Person B at home]] = ⊚ ON) and [[Time of day]] = "evening" so if either person is at home in the evening the lights will turn on.
The aforementioned example also demonstrates how switchboard items in expression statements are encapsulated by double square brackets and become placeholders representing the value of that switchboard item at any time the automation is evaluated. Selecting an option from the dropdown controls will add elements into the expression statement at the position specified by the most recent location of the cursor.
Cascading functions produce more complex expressions. Consider the following example if( [[Time of day]] = "afternoon", if( ceil random(2) = 2, true, false), false). Combining "If", "Ceiling", and "Random" functions within an expression for a workout reminder will result in an expression that evaluates as "true" roughly 50% of the time (in this case 50% of the time each afternoon).
Decomposing this example to discrete functions, we can begin to see how it gets evaluated. First, if(x, y, z) verifies if the switchboard item (named "Time of day") is set to "afternoon", then either the second if(x, y, z) is processed or false is returned immediately (if the switchboard item contains some other value). The second if(x, y, z) considers ceil random(2) = 2 where random(2) generates a random number between 0 and 2 and ceil rounds that number up to the nearest integer (discarding any decimals) for two possible results (either 1 or 2). If the function ceil random(2) produces 2 (which should occur roughly fifty percent of the time) then the expression result is true, otherwise the result is false.
Operand, operator or function
Placeholders for the value of a switchboard item at evaluation time. Switchboard items can store one of three data types; switch is boolean type (true or false), counter is number type (1.xx), keyword is string type ("text"). Operands in expressions have inherent truthy/falsy boolean values when they are the only object of an operation. The following values are always falsy: false, 0 (zero), '' or "" (empty string). Everything else is truthy including: any number other than zero, any sting including '0' or 'false' (a string containing a single zero or the text "false").
=, ≠, <, >, ≤ ≥, and math operators +, -, *, /
All operators have default operator precedence and associativity. If in doubt we suggest using parentheses for grouping. In addition to logical operators (equal =, not equal ≠, less than <, greater than >, less than or equal ≤, greater than or equal ≥) are math operators (addition +, subtraction -, multiplication *, division /). An operator can be redundant e.g. "[[SWITCH]] = on" will always give the same true or false outcome as a lone operand "[[SWITCH]]" which produces true when on and false when off. However, an expression will also evaluate with loose equality if inconsistent data types are compared within an operation, such that "[[COUNTER]] = true" will always produce true where counter is not zero and "[[SWITCH]] = 42" will always produce true when switch is on (an abstract equality in a truthy/falsy context).
(...), &, or, not, and quick insert values "..", on, off
Use parentheses to group operations and override precedence i.e. (third (second (first))). The operators & (shorthand for "and") / or are used to create conjunctive / disjunctive assertions where either all component propositions must be true (a=1 and b=2) or only one component proposition needs to be true (a=1 or b=1). A "not" operator can be used to negate a logical value i.e. "not [[SWITCH]]" will resolve false when the switch is on, and true when the switch is off. Lastly, there are three quick insert values for convenience; On and Off are the two possible switch states, and the "..." placeholder is for keyword values.
The available functions are as follows: