Guidelines for creating an offline-enabled application

Several guidelines apply to data pages, worklists, custom JavaScript scripts, and data synchronization when developing an offline-enabled application.

When you are creating an offline-enabled application:

  • Do not use custom code; rely on the functionalities provided by the model.
  • Do not use clipboard pages; use data pages instead. Data pages support life cycle and load management, and can be marked as large to enable data caching on the device.
  • Use the Mobile: Offline landing page to review which case types and access groups are offline-enabled.
Note: For Oracle WebLogic you must manually enable preemptive authentication. Set oracle.webservices.preemptiveBasicAuth=true. For more information, see the Oracle WebLogic documentation.

Flow processing

Consider the following information when creating a flow within an offline-enabled Pega Platform application:

  • Use flows in offline-enabled case types.
  • Case objects are available in offline mode:
    • All cases are available from the worklist.
    • When a case is marked for offline use, a field for adding a data page lists the case objects to send to the client for offline use. Any case in this list that is synced will be available offline. However, if this data page misses a case that a user needs, when the user attempts to open a case online that is marked for offline, and that case is not available locally on the device, the client retrieves the case from the server. The case then remains available on the client even after the user goes offline.
Note: For more information, see Offline capability for case types.

You can extend the app by using a callActivity extension point during each synchronization to handle use cases that are not supported. For example, you can perform additional tasks such as updating the details of a work object. For more information, see callActivity action as an extension.

Data pages

Data pages used in offline mode cannot be larger than 10 million characters. Because the string is UTF-8 encoded, this size represents approximately 7.6 MB if all the character codes are between 1 and 128 (for languages such as English, German, or French).

To improve performance, large data pages are supported for storing reference data for offline use. For a large data page, only the changed records are synchronized when the application goes online.

Note: For more information on using large data pages in an offline-enabled application, see the Creating and sourcing large data pages to store large reference data in offline-enabled applications Pega Community article.

Worklists

To display a worklist for an offline-enabled application:

  • Use the D_pyUserWorkList data page in the UI-Kit-7 (09-01-01) rule as an example for how to configure your data page.
  • The data page must be of type Code-Pega-List and of object class type Assign-Worklist or Assign-Workbasket.
  • To be able to open an assignment, make sure that the following properties are in the data page:
    • pxRefObjectClass
    • pxRefObjectKey
  • Make sure that pyCompletedOffline is set to true when the synchronization has finished, so that you can remove the work object from the worklist by using a client-side when rule.
Note: If the worklist is displayed on the home section, for example, in a section that is initialized in the dynamic container, this section is automatically refreshed after data synchronization.

Custom JavaScript scripts

If you want your custom JavaScript to be available offline, include the scripts in one of the following ways:

  • Add a custom script by saving the pypega_ui_userscripts_offline script bundle to the application ruleset, and then add your script files to this bundle.
  • Save the script bundle as a JavaScript file named pypega_ui_userscript_offline in the application ruleset, and then add custom JavaScript functions to the script bundle.

Data synchronization

Consider the following information in relation to data synchronization:

  • To force a full synchronization of an offline-enabled application, click Force full sync for all users on the Advanced tab of the Edit Access Group form or the Offline Configuration landing page. This action is required if any rules change, because the changed rules are then only synchronized when full synchronization takes place.
  • To prevent data synchronization issues, review the settings on the Context tab of the offlinehttp service package rule, and make sure that Use service session cookie (REST/HTTP only) is selected.
  • Synchronization happens in the following situations:
    • When a user logs in while online.
    • After a single action appears in the ClientStore action queue.
    • When a user taps the online indicator.
    • During a periodic syncing operation - every 5 minutes, if the server was last accessible, or every 1 minute, if the server was not accessible.
    • When the device goes from offline to online mode or a new hardware network interface is attached.

    You can delay synchronization for a set time or until a certain number of actions are in the queue by calling several JavaScript methods with custom scripts. For more information, see Data synchronization JavaScript API.