Skip to main content

server.load()

Returns the most recent data stored in the impCloud™

Availability

Agent

Returns

Table — the data read from persistent storage

Description

This method returns the most recent data stored on the server using server.save(), even if it was written before the agent restarted. Agents can use this permanent storage mechanism to cache data which will outlast server upgrades or migrations, or agent restarts called because the device has not communicated with the server for a long period of time.

In almost all instances, the data loaded will indeed be the data most recently preserved using server.save(). However, this cannot be guaranteed. If the data is written during the migration of an agent from one server to another, for instance, and subsequently read, the timing of the save, transfer and load may be such that the loaded data is not the most recent.

The saved data must be packaged within a Squirrel table and can be any serializable data type: tables, arrays, ‘safe’ strings, integers, floats and bools.

If server.save() has never been called by an agent, server.load() will return an empty table.

The recommended practice for retrieving cached device data is to call server.load() and then relay the information to the imp using a device.send()/agent.on() pairing. If the data is device set-up information, for instance, the agent can retrieve that data on restart and later provide it to the imp on request when the device reboots.

Agent Lifespan

If a device remains offline for more than 30 days, its agent will be shut down. However, this does not affect any data previously persisted by the agent. When the device comes back online, a new agent will be instantiated and that agent will be able to retrieve the previously persisted data using server.load().

The only instance in which the persisted data will not be accessible is when the device is re-activated using BlinkUp and it is assigned a new Plan ID (see server.save()).

Example Code

This snippet places the device’s settings in a table with default values. A second table is loaded from permanent storage. If the loaded table is not empty, it contains previously cached settings values, and these are used to replace the defaults.