# mobileservice

(plugins.mobileservice)

## Overview

The `mobile service` plugin provides tools for managing offline data synchronization and mobile client interactions. It enables the creation of offline data descriptions, the handling of remote search functionalities, and the synchronization of data changes between mobile clients and the server. This is achieved through methods that manage found sets, retrieve row descriptions, and handle transactions for data updates.

The plugin allows the generation of descriptive models for offline data through `createOfflineDataDescription`, which can optionally take a `prefix`. Remote searches can be executed by leveraging a found set in find mode using `createRemoteSearchFoundSet(data)`, which can then be used to return results to the mobile client. Synchronization of mobile client changes is supported by `performSync(data, version, authenticateResult)`, which processes a complete data package in a single transaction. It redistributes insert, update, and delete operations to respective data forms and ensures rollback in case of errors.

The plugin also supports obtaining detailed JSON descriptions of rows through `getRowDescriptions(datasource, pks)` based on primary keys and their data source.

## **Returned Types**

[OfflineDataDescription](https://docs.servoy.com/reference/servoyextensions/server-plugins/mobileservice/offlinedatadescription),

## Methods Summarized

| Type                                                                                                                             | Name                                                                                           | Summary                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [OfflineDataDescription](https://docs.servoy.com/reference/servoyextensions/server-plugins/mobileservice/offlinedatadescription) | [createOfflineDataDescription()](#createofflinedatadescription)                                | Create a descriptive model for offline data.                                                       |
| [OfflineDataDescription](https://docs.servoy.com/reference/servoyextensions/server-plugins/mobileservice/offlinedatadescription) | [createOfflineDataDescription(prefix)](#createofflinedatadescription-prefix)                   | Create a descriptive model for offline data.                                                       |
| [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset)                                   | [createRemoteSearchFoundSet(data)](#createremotesearchfoundset-data)                           | This should be called by inside the offline\_data.                                                 |
| [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object)                                                     | [getRowDescriptions(datasource, pks)](#getrowdescriptions-datasource-pks)                      | This method returns the description of rows as a json array object.                                |
| [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object)                                                     | [performSync(data, version, authenticateResult)](#performsync-data-version-authenticateresult) | If all the changes for a mobile client needs to come as once so that they can be in 1 transaction. |

## Methods Detailed

### createOfflineDataDescription()

Create a descriptive model for offline data.

**Returns:** [OfflineDataDescription](https://docs.servoy.com/reference/servoyextensions/server-plugins/mobileservice/offlinedatadescription) OfflineDataDescription

**Sample**

```js
//plugins.mobile.getOfflineFoundSetData(foundset,null);
var data = plugins.mobileservice.createOfflineDataDescription('data_');
```

### createOfflineDataDescription(prefix)

Create a descriptive model for offline data.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **prefix** specified formname prefix used to retrieve row data from REST wise

**Returns:** [OfflineDataDescription](https://docs.servoy.com/reference/servoyextensions/server-plugins/mobileservice/offlinedatadescription) OfflineDataDescription

**Sample**

```js
//plugins.mobile.getOfflineFoundSetData(foundset,null);
var data = plugins.mobileservice.createOfflineDataDescription('data_');
```

### createRemoteSearchFoundSet(data)

This should be called by inside the offline\_data.ws\_create method of a mobile service solution.\
That method is called by the the plugins.mobile.remoteSearch(foundset) that can be done on the mobile client.\
This will return a FoundSet that is in findmode with the exact same FindStates that the mobile client had when remoteSearch is called.\
On this FoundSet search() should be called and then this foundset should be added to a OfflineDataDescription.addFoundSet(fs) and that\
OfflineDataDescription object should be returned.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **data** The data that is given into the offline\_data.ws\_create method

**Returns:** [JSFoundSet](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsfoundset) The FoundSet that is in find mode or null if no FoundSet could be created.

**Sample**

```js
function ws_create(data,version,method,authenticateResult) {
// Test if it is a remoteSearch call
if (method == "search") {
  // Create the FoundSet from the data that is send over from the mobile client
  var fs = plugins.mobileservice.createRemoteSearchFoundSet(data);
  // This FoundSet is in find mode, more stuff could be added to it if you want to filter even more. Then call search()
 fs.search();
  // Create the OfflineDataDescription that will be returned for this remoteSearch
 var retval = plugins.mobileservice.createOfflineDataDescription('data_');
 retval.addFoundSet(fs);
  return retval;
 }
}
```

### getRowDescriptions(datasource, pks)

This method returns the description of rows as a json array object.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **datasource** the pks belong to
* [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) **pks** the array of pks

**Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) a JSON array describing the rows from the specified datasource using the provided primary keys.

**Sample**

```js
/** @type {Array<Object>} */
var idsArray = new Array(100,200,300);
var json = plugins.mobileservice.getRowDescriptions('db:/example_data/contacts', idsArray)
```

### performSync(data, version, authenticateResult)

If all the changes for a mobile client needs to come as once so that they can be in 1 transaction. Then the offline\_data form should define a ws\_update((data,version,authenticateResult)) method.\
This method will then get the complete data package which should be give to this function.\
This will redispatch all the inserts,updates or deletes to the various data forms that has the real rest methods to handle the actual insert.\
If something fails then an Exception will be thrown and you can do a rollback so that everything of this sync is reverted.

**Parameters**

* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **data** The data package that is given to the offline\_data form ws\_update method.
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **version** The version number that is given to the offline\_data form ws\_update method.
* [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) **authenticateResult** The authenticateResult object that is given to the offline\_data form ws\_update method. (generated by the offline\_data.ws\_authenticate)

**Returns:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) an object containing all the (key,value) pairs from the ws\_create returned objects

**Sample**

```js
try {
   databaseManager.startTransaction();
   plugins.mobileservice.performSync(data,version,authenticateResult);
   databaseManager.commitTransaction();
} catch (e) {
   databaseManager.rollbackTransaction();
   // log the error and return false to that the mobile client will know the sync did fail.
   application.output(e,LOGGINGLEVEL.ERROR);
   return false;
}
```

***