.. _offline-mode:

Offline mode
####################################################################################################
Working offline allows the app to work without contacting the server, thus improving the overal user experience.
As nothing comes easy, the K2 developer needs to configure various items to allow a project to work offline completely.

The term *working offline* can be interpreted in two ways: the user tells the app to work in offline mode or there is no connection with the K2 server.
The table below shows the four quadrants created.
Each of them will be discussed later on.

+---------------+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
|               | **Online Mode**                                                           | **Offline Mode**                                                                    |
+---------------+-----+---------------------------------------------------------------------+-----+-------------------------------------------------------------------------------+
| **K2 Server** | Pro | Always the latest version of data sources.                          | Pro | Optimal speed as each data source is stored locally.                          |
| **Available** +-----+---------------------------------------------------------------------+-----+-------------------------------------------------------------------------------+
|               | Con | Sub-optimal speed as each data source is retrieved from the server. | Con | Data is not always up to date. User needs to sync manually.                   |
+---------------+-----+---------------------------------------------------------------------+-----+-------------------------------------------------------------------------------+
| **K2 Server** | App shows a message telling the user it's waiting for a connection.       | Pro | Optimal speed as each data source is stored locally.                          |
| **Not**       |                                                                           +-----+-------------------------------------------------------------------------------+
| **Available** |                                                                           | Con | Data is not always up to date. User cannot sync as the server is unavailable. |
+---------------+---------------------------------------------------------------------------+-----+-------------------------------------------------------------------------------+

Online mode & K2 server available
****************************************************************************************************
This is the default situation, where there is an internet connection with the K2 server and internet may be used normally by K2 Business Apps.
The big upside is that the user always has the latest version of the data source, can easily retrieve the latest version of forms and view and so on.
The slight downside lies in the speed.
When executing SmartObjects that return big data sets, they need to be downloaded to the device.
If e.g. a data source contains 10 rows and each one holds an image of 1 megabyte, that single SmartObject call will download 10 megabytes of data.
That may not only be time consuming, but can also gobble up someones mobile data plan if left unchecked.
The K2 developer needs to make sure only the absolute necessary is downloaded to provide the optimal speed and lowest amount of data consumption.

Offline mode & K2 server available
****************************************************************************************************
When the user prefers to work in offline mode, this is the quadrant you're looking for.
The K2 developer needs to make sure all data used by the available forms on the project are downloaded to the users device.
To do this, the K2 Business Apps control is used, or more specifically execute K2 Business Apps control's Download Data Source method.
This method takes the following inputs:

SmartObject ID (guid, mandatory)
	The ID of the SmartObject in K2.

SmartObject Method (text, mandatory)
	The name of the method on the SmartObject that will be executed.

Inputs (text)
	The input properties of the method in the form key1=value1;key2=value2;....

If you want to download multiple data sources, you may want to use the then complete the following concurrently.

If a form executes a SmartObject, starts a Workflow, or other actions that normally require the K2 server, they will be stored locally and will be send to K2 once the user synchronizes with the server.
All actions are executed in chronological order.

CRUDL
====================================================================================================
So is it possible to execute SmartObjects while working in offline mode?
Yes, it is! There are some limitations though!

Using conventional K2, a SmartObject can be executed.
K2 receives the order, triggers the correct service broker, which in turn executes a piece of code.
The code can basically be anything.

K2 Business Apps can never mimic the "basically anything" behavior.
What we can do is check what kind of method is being executed.
K2 forces you to provide one of the following types: Create, Read, Update, Delete, List, or Execute.
The first five can be considered basic database operations and we can do that while working in offline mode.
*Execute* however is a generic term of which we do not know how to process it.
This method type will be ignored while working in offline mode.

Create
	Most create methods return an ID and we'd like to do the same.
	If the SmartObject has a property of type AutoGuid or AutoNumber, K2 Business Apps can create a new entry in the local database and will think of a value for the return property.
	That value can then be used to execute other SmartObjects.
	Once the user syncs, the server will return the actual value for the return property, and K2 Business Apps updates everything internally, so it matches what K2 told it.

Read
	A read usually takes the ID of an item as input and return the complete item.
	The app does the same.

Update
	This is similar to the Create, except that the inputs contain the ID of the item.

Delete
	A delete takes the ID of an item and then removes it from the local data source.

List
	A list method takes an arbitrary amount of inputs. The data source the checked and basically filtered on each input property provided. The resulting set can vary from no items to the entire data source.

Online mode & K2 server unavailable
****************************************************************************************************
While forms and views are available, data sources are not by default available.
We could store every last version retrieved from the server, but we hate to make assumptions and will never be sure whether that data source is the same as the K2 developer wanted in that particular case.
So this quadrant results in a popup message blocking the screen, telling the user we're waiting for an internet connection.

Offline mode & K2 server unavailable
****************************************************************************************************
This is almost identical to "Offline mode & K2 server available" except that the user cannot synchronize with the server as it is unavailable.

Being Online Or Offline
****************************************************************************************************
Next to the offline mode, there is the matter of having a connection with the server or not.
By default, K2 Business Apps may use internet as it pleases.
Users may object to this and have the option to tell the app to only allow the usage of internet if there is a Wi-Fi connection.
When this option is set, the *K2 server available* may turn into a *K2 server unavailable*, as the user may have no active Wi-Fi connection at the time.
The quadrants at the top of this document will describe the predicament of the user.