Clarifying that actions can be about non-physical processes

[egekorkan]

The spec states "ActionAffordance: An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time)". Both of those suggest a primarily one-way action and both modify Thing state in some way. There are many examples of functions/actions that simply ask the Thing to perform a task that may return data but not alter state - querying log files, querying local data such as sensor history or application data, and so on. These do not modify the state in any way.

Coming from a separate discussion with @RickBullotta

[benfrancis]

Just recording my comments from the same conversation here, since I'm not convinced that actions should be used for the kinds of use cases suggested.

Personally my rule of thumb is that you should only use an action when the setting of a property alone is not sufficient to affect a required change in state.

This may be used to describe a function which takes a period of time to complete, manipulates multiple properties, or has a different outcome based on provided arguments or current state. Examples might include a "fade" action which has a specified "duration", a "sequence" action which triggers a sequence of flashing lights or a "toggle" action on a switch.

I always struggle to think of good examples of actions which have an output, but I can imagine a machine which carries out an action and then reports back its status, e.g. you tell a robot to go and collect all the widgets from a room and once it's finishes it reports back how many widgets it collected.

I personally don't think that querying log files or historical sensor data are great examples of actions. Partly because they could be modelled as reading a property, but actually maybe they're not interaction affordances at all (since they don't represent the current state of a physical device).

WebThings Gateway used to have an API for historical sensor data and we spent time arguing for an operation type for reading historical values of properties, but in the end concluded it was out of scope. There is a topic around time-series data for WoT 2.0, so maybe there will be a formally defined mechanism for that in the future.