LinkedIn
Copied!

Client Store API for Pega Infinity Mobile Client

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]

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 is stopped (the store stays 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 an 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 an 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 handler 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 object 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/updates accompanied with actions that are supposed to reproduce the same modifications on the server. This is the only way of making consistent changes to the store.
When using this method it is guaranteed that the modifications will not be overwritten by server changes without having the corresponding actions processed first. This is not true if the actions are added in a separate call or 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 first form:

  • 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.
  • The pending/ongoing upload is canceled and the action is removed from the queue when the corresponding item is removed with the deleteItem method.

Use the first form for actions that require the content of the item when processing on the server, and the second form otherwise.

Example

As an example, when adding an attachment, the commitAttachment action should be placed in the array of the item because you want the binary content of that item to be uploaded and available when the server processes the action. The addStub action should be placed 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, which 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 and not specifying the url parameter is invalid and 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. The API guarantees that the deletion will not be overwritten by the server changes without processing the corresponding actions first. This is not true if the actions are added separately by calling the addAction method.
Additionally, if the item was added/updated by calling the writeItems method and accompanied with an action, the pending/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()

This method is for the development purposes only.
Clears all items from the client store. In most cases it makes the application unusable until the next synchronization.

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.

runQuery(query, args, targetDatapageName)

Executes 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. A name of the target datapage. Used to obtain the column types when formatting the result. If null or undefined, a raw SQL result is returned.

Return value

A Promise that resolves to a result set of the given SQL, which 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 taken from the datapage 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])

Gets the size that is occupied by each given table, 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 more information about the actions should be retrieved (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

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. 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 - Id of an action to be remove. Required.

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()

This method is for the development purposes only. Removes all actions from the queue.

Return value

A Promise that resolves with no value. The promise is rejected when it is called during the 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 is stopped successfully, or when it is not running.

getFileForwardingState()

Gets the file forwarding state. See the setFileForwardingState method for details.

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 the file forwarding. If disabled, actions that reference a file are not forwarded and their content is not uploaded until the 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 has been added before a standard action may be processed on the server after the standard action). The file forwarding is enabled by default. The value is persisted across application restarts.

Parameters

  • state - Setting this value to true enables the file forwarding. Setting this value to false disables the file forwarding. Required.

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 changes to the items with the specified types are reported to listeners. This affects all the listeners that have been 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 - An array of synchronization item types. Required.

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 - The number of actions. Must be either -1 (no limit) or more than 0. Required.

Return value

A Promise that resolves with no value.

Constants

Errors

Following JavaScript object pms.plugins.clientstore.Error defines 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.
}

Where options is an action options object.

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).
}

Note: The content and url parameters are mutually exclusive. The content of an item can be created directly from the value of the content parameter or form the content of a file that has been specified by the url parameter. Exactly one of the parameters must be specified. Passing either none or both parameters causes the ILLEGAL_ARGUMENTS error.

Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.