When you develop Pega^® Platform applications such as mobile apps, you must follow certain guidelines and be aware of special considerations to enable the offline capability in applications.

For more information, see the following sections:

• Enable offline capability in your access groups and case types
• Create an application
• Use supported controls
• Flow processing considerations
• Other considerations

For background information about the offline capability in applications, see Offline capability.

Enable offline capability in your access groups and case types

Consider the following information when enabling offline capability for access groups and case types:

• You enable offline capability for an access group on the Advanced tab of the Edit Access Group form by selecting the Enable offline support check box.
• A single offline-ready application can support both online-only and offline-ready case types. The online-only case types are still available in the mobile app, but a user can create assignments or edit them only while online.
• The following restrictions apply while working offline:
  • Case stage transitions are not supported.
  • Subcases are not supported.
  • Circumstance application rules are not supported.
• You must enable the offline capability for each case type that you want to support in offline mode. On the Advanced tab of the Edit Case Type form, select the Enable offline support check box.
• After you log in to a custom mobile app on a device and enable or disable the offline capability in Designer Studio (for example, for the application's case types and access groups), for the settings to take effect, you need to reinstall the mobile app or clear its data.
• After offline capability is enabled, you can create individual assignments within that case type while working offline. Screen flows that are a part of the case type can also be run while offline. For more information, see Flow processing considerations.
• If you create a case type, it uses dynamic views by default, which will not work in offline mode. However, you can disable dynamic views on the Views tab of the case type so that the case type uses regular harnesses and sections.
• The login rule for all offline-enabled applications must be based on the Web-Login rule in the Pega-EndUserUI ruleset. This rule contains all the required user interface items and references to scripts that are used by the offline-enabled applications.

By default, you use a portal in the UI-Kit-7 (09-01-01) ruleset to build applications. You can create your own portal for offline capability, as long as it uses some of the key principles and design of the pyCaseWorker portal. For more information, see Composite portal and Creating a composite portal. A portal that is based on the Case Worker portal (such as pyCaseWorker) has the following requirements:

• It must be set as the default portal for every access group whose users access the offline-enabled application.
• It must use an iFrame-less dynamic container.
• The harness in the portal must be defined in the Data-Portal class.
• The cases must use stages and use pyStartCase as the starting flow on a case.

Create an application

When you create an offline-enabled Pega Platform application, make sure to follow these guidelines:

• Do not use custom code; rely on the functionality that is 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.

Build the user interface

Because grids with too many columns might not display correctly on a mobile device, follow these guidelines:

• Use layout groups instead of tabs and accordions.
• Use screen layouts instead of containers.
• Use repeating dynamic layouts instead of grids for repeating structures.

Sections that are displayed on a mobile device might need to be refreshed and reoriented; therefore, follow these guidelines:

• Use skin rules to specify the presentation of your content by defining mixins and style formats.
• To promote re-usability, use sections instead of solid structural elements.
• Use dynamic layouts and column layouts, and use flexbox helper classes to position user interface elements within layouts.
• Configure your dynamic container to render as a single page in the central panel of the portal screen layout.
• Configure refresh when rules on the user interface elements that need to be refreshed, such as dynamic layouts, instead of refreshing entire sections.
• When using the defer load option:
  • The defer load sections or layouts are loaded on the initial load, and the defer load preactivity is always ignored. This behavior affects the performance of loading screens.
  • Defer load is not supported in tabs. You must use a layout group instead.

When adding buttons, links, icons, and menu items, use only the supported set of actions. For a complete list of actions that are supported while working offline, see Supported actions when working offline.

For a complete list of supported controls that you can use while creating the user interface, see Supported controls when working offline.

For more information about building the user interface and working with dynamic layouts, see Creating the user experience and Using dynamic layouts to create responsive user interfaces.

Flow processing considerations

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

• Use flows in 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 goes to online mode and attempts to open a case 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.

For more information, see Flow processing in offline mode.

Other considerations

The following information is important to know while developing Pega Platform applications with offline capability:

• You configure and build an Android or iOS offline-enabled custom mobile app as a channel interface. For more information, see Configuring a custom mobile app.
• A landing page lists various configurations that must be performed for the offline mobile app. To access this landing page, click Designer Studio > Mobile > Offline.
• 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 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 Code-Pega-List type and of Assign-Worklist or Assign-Workbasket object class type.
  • 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.
• If the worklist is displayed on the home section, for example, the section that is initialized in the dynamic container, this section is automatically refreshed after data synchronization.
• 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.
• If the Pega Platform was installed on an Oracle WebLogic application web server, you must manually enable preemptive authentication because it is disabled by default. Set the following Oracle SOA 11g partnerlink binding property to true:
  oracle.webservices.preemptiveBasicAuth=true
• If you want your custom JavaScript scripts 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 as a JavaScript file named pypega_ui_userscript_offline to the application ruleset, and then add custom JavaScript functions to it.
• Synchronization might happen after a single action appears in the ClientStore action queue. When adding custom JavaScript scripts, you can configure data synchronization by calling the following JavaScript methods:
  • pega.offline.DataSync.setIntervalBetweenSynchronizationsWhenServerAccessible – Sets the interval (in milliseconds) between subsequent synchronization sessions when the server is available. By default, it is set to 5 minutes.
  • pega.offline.DataSync.setIntervalBetweenSynchronizationsWhenServerInaccessible – Sets the interval (in milliseconds) between subsequent synchronization sessions when the server is not available. By default, it is set to 1 minute.
  • pega.offline.Indicator.setDeferDurationTime – Sets the time (in milliseconds) that must pass from the start of the synchronization session before the Syncing/Synced label is displayed. By default, it is set to 4 seconds.
  • pega.offline.Indicator.setHideSyncedAfterTime – Sets the time (in milliseconds) that must pass from the end of the synchronization session before the Synced label is no longer displayed. By default, it is set to 5 seconds.
  All values must be greater than 0.