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 more information, see Offline capability.
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 Dev 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.
To build an offline-enabled application, you must:
- Use the latest version of UI-Kit-7 in your application stack.
- Use the pyCaseWorker portal as a starting point.
- Make the application skin inherit from the pyEndUser skin.
By default, you use a portal in the UI-Kit-7 (12-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.
When you create an offline-enabled Pega Platform application, follow these guidelines:
- 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.
- The data page size 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. For more information, see Creating and sourcing large data pages to store large reference data in offline-enabled applications.
Because grids with too many columns might not display correctly on a mobile device; therefore, 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.
Because 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 reusability, 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.
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 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.
For more information, see Flow processing in offline mode.
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 > > .
- To force a full synchronization of an offline-enabled application, click 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. on the
- 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:
- 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:
- 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.
All above values must be greater than 0.
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.
pega.offline.DataSync.setQueueMaxSize– Sets the number of actions in the queue that must be reached before synchronization is triggered. By default, it is set to 1, which means that actions are immediately sent to the server after they are added to the queue.
pega.offline.DataSync.setQueueFlushInterval– Sets the amount of time (in milliseconds) that must pass from the moment when an action is queued in the client store before synchronization is triggered. By default, it is set to 0, which means that synchronization is not delayed.
pega.offline.DataSync.enableFlushOnLastStep– Enables or disables synchronization triggering after the user processes the last step in an assignment. By default, it is set to false.
pega.offline.DataSync.isFlushOnLastStepEnabled– Checks whether synchronization triggering is enabled after the user processes the last step in an assignment.
pega.offline.DataSync.setMaxNumberOfActionsPerRequest- Sets the maximum number of actions with a single request. By default, it is set to 60, which means that 60 actions are sent per each synchronization request. Specifying a value of -1 switches off the limit.