window.pms.plugins.clientstore

An object that exposes access to an offline database of the client.

Properties

busy

Read only. A Boolean that represents the synchronization state:

• true

  Synchronization is running.

• false

  Synchronization is idle.

lastError

Read only. A JavaScript object that describes the last synchronization error.

{
  string 'name',   // Error name, as defined in pms.plugins.clientstore.Error
  string 'message' // Error message
}

Events

actionadded

An event that is fired when a new action is added to the action queue.

actionremoved

An event that is fired when an action is removed from the queue.

actionscleared

An event that is fired when the action queue is cleared (all actions are removed from the queue).

synchronizationstarted

An event that is fired when the synchronization starts.

synchronizationprogress

An event that is fired during the synchronization to report progress. The following object is placed in the detail field:

{
  float 'progress',// A numerical value from 0.0 to 100.0 .
  integer 'phase' // A synchronization phase code, as defined in pms.plugins.clientstore.Progress
}

synchronizationsucceeded

An event that is fired when the synchronization finishes successfully. The following object is placed in the detail field:

{
  boolean 'wasFullSync', // True if the synchronization was of fullSync type.
  'upsertedItems': [ // Items that were added or modified. Only available if the `wasFullSync` parameter is false.
    {
      string 'type',
      string 'handle'
    }, ...
  ],
  'deletedItems': [
    {
      string 'type',
      string 'handle'
    }, ...
  ],
  'modifiedCustomTables': [ // An array of table names that were modified (for example, records were added, updated or deleted).
    string, ...
  ]
}

synchronizationfailed

An event that is fired when the synchronization fails. The following object is placed in the detail field:

{
  string 'name', // Error name, as defined in pms.plugins.clientstore.Error
  string 'message'
}

synchronizationstopped

An event that is fired when the synchronization stops (the store remains unchanged).

Methods

getItemUrl(type, handle)

Gets the URL address of an item. The URL address can be passed to the preview method of the window.pms.plugins.documents API to preview the contents of an item.

Parameters

• type

  Required.

• handle

  Required.

Return value

A Promise that, when resolved, calls its fulfillment handler with a URL address of the item.

getItem(type, handle)

Retrieves a single item by type and handle.

Parameters

• type

  Required.

• handle

  Required.

Return value

A Promise that resolves to an item.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getItems(matchers)

Retrieves a collection of items that match the passed matchers.

Parameters

• matchers

  Required. An array of matcher objects. (If an empty array is passed, then an empty array is returned.) The matcher object is defined as a JavaScript object with two required fields:

  {
      string 'type',   // An item type to search for.
      string 'handle'  // An item handle to search for or an asterisk ("*") to match any handle.
  }

Return value

A Promise that, when resolved, calls its fulfillment handler with an array of matched items.

In case of errors, the Promise is rejected with Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getItemTypes()

Retrieves a list of item types for the currently stored data items.

Return value

A Promise that, when resolved, calls its fulfillment hanlder with an array of the available item types (an array of string values).

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getItemsStats()

Calculates the statistics for all the currently stored items.

Return value

A Promise that, when resolved, calls its fulfillment handler with an array of objects. The objects is defined as follows:

{
  string 'type',     // An item type.
  string 'handle',   // An item handle.
  integer 'length'   // A size of the item content.
}

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getOfflineStorageCount()

Retrieves a number of currently stored items.

Return value

A Promise that, when resolved, calls its fulfillment handler with a number of items.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

writeItems(items, additionalActions)

Updates the store. An update consists of item inserts accompanied by actions that reproduce the same modifications on the server. This is the only way of making consistent changes to the store.

When using this method, server changes do not overwrite the modifications until the corresponding actions are processed first. This does not apply if the actions are added in a separate call or in the addAction call.

Actions can be provided in two ways: in the actions array within an item, or a separate actions parameter. There are additional guarantees when using the the actions array within an item:

• The content of the item is treated as part of the action data. It is uploaded to the server before the action and is available during processing.
• If the corresponding item is removed with the deleteItem method, the pending or ongoing upload is canceled and the action is removed from the queue.

Use the actions array within an item for actions that require the content of the item when processing on the server. Otherwise, use a separate actions parameter.

For example, when adding an attachment, you place the commitAttachment action in the array of the item so that the binary content of that item can be uploaded and available when the server processes the action. You place the addStub in a separate parameter.

  window.pms.writeItems([
      {
        string 'type',
        string 'handle',
        string 'url', // A URL address obtained from the document picker.
        'actions': [ commit_action ]
      }
    ],
    [ stub_action ]
  )

Where commit_action is the commitAttachment action and stub_action is the addStub action.

Parameters

• items

  Required. An array of item objects with an additional actions parameter. The actions is an array of actions that require the content of the item when processing on the server.

  Note: Passing the actions array inside of an item without specifying the url parameter will cause the ILLEGAL_ARGUMENTS error.
• additionalActions

  Optional. An array of actions that are related to the items. An action in this collection does not require file data to be specified by the url of an item.

Return value

A Promise that, when resolved, calls its fulfillment handler with an array of action identifiers that have been added to the action queue. The order in the array corresponds to the order in which actions were added to the queue. The actions from the additionalActions array are processed first, followed by the actions from each of the items.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

deleteItem(type, handle, actions)

Deletes a specific item that is identified in the store by specifying its type and handle. The third parameter must provide the actions that are supposed to delete the item on the server. When using this API, server changes do not overwrite the deletion until the corresponding actions are processed first. This does not apply if the actions are added separately by calling the addAction method.

Additionally, if the item was added or updated by calling the writeItems method and accompanied by an action, the pending or ongoing upload is canceled and the action is removed from the queue.

Parameters

• type

  Required. An item type (String).

• handle

  Required. An item handle (String).

• actions

  Optional. An array of actions to be added when the item is deleted.

Return value

A Promise that, when resolved, calls its fulfillment handler without parameters.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

clearItems()

For development purposes only. A method that clears all items from the client store. In most cases, this method makes the app unusable until the next synchronization.

Return values

A Promise that, when resolved, calls its fulfillment handler without parameters.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

runQuery(query, args, targetDatapageName)

Runs the SQL queries directly on the client store database.

Parameters

• query

  Required. An SQL query (SQLite syntax).

• args

  Optional. An array of SQL parameter values in the order of their appearance in the query.

• targetDatapageName

  Optional. Name of the target data page. Used to obtain the column types when formatting the result. If the value is null or undefined, a raw SQL result is returned.

Return value

A Promise that resolves to a result of the given SQL that is represented by an array of objects. Column types are matched to Float, Integer or Text type.

If targetDatapageName is specified, the column types are fetched from the data page definition. In that case additional conversions to Boolean, Date, Time and DateTime types are available.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getCustomTableSizes([tableNames])

Fetches the size that is occupied by each given table. The size is calculated by summing up the lengths of each field in each record.

Parameters

• parameter

  Required. An array of table names.

Return value

A Promise that resolves to a list of integers.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getActionUrl(actionId)

Gets a URL address of an item. The URL can be passed to the preview method of the window.pms.plugins.documents API in order to preview the content of an action.

Parameters

• actionId

  Required.

Return value

A Promise that, when resolved, calls its fulfillment handler with a URL address of the content of an action.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

listActions(getDetails, options)

Retrieves a list of actions that are queued for synchronization.

Parameters

• getDetails

  Optional. A Boolean value that determines whether to retrieve more information about the actions (defaults to false).

Return value

A Promise that, when resolved, calls its fulfillment handler with a JavaScript object with all the actions.

{
  id_of_action: {      // The id_of_action is an identifier of an action (number).
    string 'metadata',   // The metadata of an action (string).
    string 'data',       // The data of an action (string).
    boolean 'forwarded'  // When set to `true`, an action has been forwarded. When set to `false`, it is otherwise.
  }
}

Or, when getDetails is set to false:

{
  id_of_action: metadata // The id_of_action is an identifier of an action (number), metadata is the metadata of an action (string).
}

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

getQueuedActionsCount(options)

Retrieves a number of queued actions.

Parameters

• options

  Optional. See Action options.

Return value

A Promise that, when resolved, calls its fulfillment handler with a number of queued actions.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

addAction(metadata, data, options)

Adds an action to the queue.

Parameters

• metadata

  Required. A JavaScript object with the metadata of an action to be passed to the server.

• data

  Required. A JavaScript object with the data of an action to be passed to the server.

• options

  Optional. See Action options.

Return value

A Promise that, when resolved, calls its fulfillment handler with an id of the action that has been added.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

removeAction(id)

Removes an action with the given ID from the queue, provided that it is still pending and is not being transferred.

Parameters

• id

  Required. ID of the action to be removed.

Return value

A Promise that resolves with no value.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

clearActions()

For development purposes only. A method that removes all actions from the queue.

Return value

A Promise that resolves with no value. The promise is rejected when it is called during synchronization.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

start()

Starts the synchronization, provided that it is not already in progress.

Return value

A Promise that resolves (with no value) when the synchronization has finished successfully.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

stop()

Stops the synchronization.

Return value

A Promise that resolves (with no value) when the synchronization stops, or when it is not running.

getFileForwardingState()

Gets the file forwarding state. For more information, see setFileForwardingState(state).

Return value

A Promise that resolves to true if the file forwarding is enabled and to false if otherwise.

In case of errors, the Promise is rejected with an Error object with a property name set to one of the names that are defined in pms.plugins.clientstore.Error.

setFileForwardingState(state)

Enables or disables file forwarding. If disabled, actions that reference a file are not forwarded and their content is not uploaded until file forwarding is re-enabled. Ongoing uploads are paused as soon as possible. Other actions are not affected. As a result, queue order is altered (if file forwarding is disabled, a binary action that was added before a standard action might be processed on the server after the standard action).

By default, file forwarding is enabled. The value is persisted across application restarts.

Parameters

• state

  Required. Setting this value to true enables file forwarding. Setting this value to false disables file forwarding.

Return value

A Promise that resolves with no value.

setReportedTypes([types])

Appends the list of synchronization item types for reporting changes that come from the server during the synchronization. Only the changes to the items with the specified types are reported to listeners. This affects all the listeners that were registered prior and after a call to this method, and all synchronizations that start after the call. The list is not persisted across application restarts.

Parameters

• types

  Required. An array of synchronization item types.

Return value

A Promise that resolves with no value.

setMaxNumberOfActionsPerRequest(number)

Sets the maximum number of actions that are sent in a single request during the synchronization. If there are more actions in the queue, more requests are made. The value is not persisted across application restarts.

Parameters

• number

  Required. The number of actions. The value must be either -1 (no limit) or greater than 0.

Return value

A Promise that resolves with no value.

Constants

Errors

The following JavaScript object, pms.plugins.clientstore.Error, defines the possible error names:

pms.plugins.clientstore.Error = {
  ALREADY_STARTED:        6,  // The synchronization is already running.
  AUTHENTICATION_FAILURE: 8,
  CLIENT_DB_FAILURE:      4,
  CLIENT_PARSING_FAILURE: 5,
  ILLEGAL_ARGUMENTS:      9,
  INTERNAL:               1,  // Internal issues (See the device logs for details).
  ITEM_NOT_FOUND:         11,
  NETWORK_FAILURE:        2,
  NONE:                   0   // No error.
  NOT_CONFIGURED:         7,  // The plugin is not configured to perform an operation.
  SERVER_FAILURE:         3,
  SESSION_EXPIRED:        10,
}

Synchronization phase

pms.plugins.clientstore.Progress = {
  // The first two phases:
  //DEBUNDLING_STATED:    1,
  //DEBUNDLING_COMPLETED: 2,
  // are not reported to JavaScript.
  UPLOAD_STARTED:       3,
  UPLOAD_COMPLETED:     4,
  REQUEST_SENT:         5,
  RESPONSE_INCOMING:    6,
  RESPONSE_CONSUMED:    7,
  NO_CHANGE: -1
}

Common syntax

Action

An action in clientstore can be represented by using a JavaScript object:

{
  object 'metadata', // Required. Metadata of an action as a JavaScript object.
  object 'data',     // Required. Data of an action as a JavaScript object.
  object 'options',  // Optional.
}

Action options

The action options in clientstore can be represented by using a JavaScript object that contains three optional flags:

{
  boolean 'silent',       // Prevents the incrementing of "item to sync" counter that is visible next to the synchronization status icon.
  boolean 'lax',          // Adding an action with this flag does not cause an ongoing data sync to be restarted.
                          // An action is forwarded with the next synchronization.
  boolean 'negligible'    // If only actions with this flag exist in an action queue, the user is not warned
                          // of data loss when logging out.
}

Item

An item in clientstore can be represented by using a JavaScript object:

{
  string 'type',     // A type of an item (always set).
  string 'handle',   // A handle of an item (always set).
  string 'content',  // A content of an item (can be null if the item has content stored in a file).
  string 'url'       // A URL address of the content of an item (can be null).
}