Offline mobility guidelines in Pega 7.1.9
Developers of Pega 7 Platform mobile apps must follow certain guidelines and be aware of some special considerations to enable mobile apps to work in offline mode.
- Enable offline in your access groups and cases
- Use supported controls
- Use supported actions
- Flow processing considerations
- Other considerations
For more information, see Offline mobility.
Enable offline in your access groups and cases
Keep the following information in mind while enabling the offline capability for your access groups and cases:
- You enable offline capability for an access group by selecting the Enable offline support check box on its Advanced tab.
- You must enable offline capability for each case. Select the Enable offline support check box on the case's Advanced tab.
- After offline capability is enabled, you can perform individual assignments within that case while working offline. Screen flows that are a part of the case can also be performed while offline. For more information, see Flow processing considerations.
- The following restrictions apply:
- All cases accessible to an offline user must be enabled for offline. There cannot be a mix of cases that are offline-enabled and cases that have offline capability disabled.
- Case stage transitions are not supported while working offline.
- Circumstanced application rules are not supported.
- You must build a mobile app by using the Mobile tab of the application rule form. For more information, see How to build and brand a hybrid mobile application.
- A new access class called Pega-OfflinePack must be added to existing access groups. Set level 5 access for all rules except for the write and delete rules.
- The login rule for all offline-enabled apps must be based on the Web-Login rule found in the Pega-EndUserUI ruleset. This rule contains all the necessary user interface items and references to scripts used by the offline-enabled apps.
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 How to create a composite portal. A portal that is based on the Case Worker portal (such as pyCaseWorker) has the following requirements:
- It is not available by default in the Pega 7 Platform. You need to add the UI-Kit-7 ruleset to the application stack - see Using the UI Kit ruleset, for more information.
- Must be set as the default for every access group whose users access the offline-enabled application.
- Must use a frameless dynamic container.
- The harness in the portal must be defined in the Data-Portal class.
- Must adhere to the guidelines listed below.
Use supported controls
When developing a mobile app for offline capability, every screen must be built by using modern layouts and lists. Refer to the Supported controls while working offline help topic for a complete list of supported controls that can be used while creating the user interface.
Use supported actions
Buttons, links, icons, and menu items must use only the supported set of actions. The complete list of actions that are supported while working offline is described in the Supported actions while working offline help topic.
Flow processing considerations
You must use cases in flows. Case step flows can be used to perform assignments when offline:
- Case steps can be performed offline.
- Back-to-back case steps can also be performed offline.
- Case step flows can be expanded. Only assignment shapes can be performed while offline. If any other shape is reached, the flow processing stops when offline.
- Subflows are not supported.
Screen flows can be used to perform back-to-back assignments when offline:
- Screen flows can contain only assignment shapes. If the flow contains any other type of shape, the user, while offline, cannot continue past the assignment that precedes the unsupported shape. In addition:
- Utility shapes can be present at the end of the screen flow. The utility does not run when offline, but becomes available online when the completed assignments are synced to the server.
- Only assignment shapes can be performed while offline. If any other shape is reached, the flow processing stops when offline.
- You can include custom JavaScript code to execute some basic business logic before and after a flow action is rendered in offline. This is accomplished by adding your own JavaScript code into a custom user scripts bundle. Its functions must be called within a
try
/catch
clause. The JavaScript code to be executed before a flow action is rendered is always called after ClientCache and before the DisplayHarness is called. Pre-activities and post-activities can also run when the flow is syncing to the server. - Back-to-back assignments are supported, but you must use the default button in the screen flow harness. The button returns you to the previous assignment as defined in your screen flow.
- The completed
datetime
recorded in the audit trail is thedatetime
that the assignment completes on the server when the item is synced when back online.
Other general flow processing notes:
- The worklist displayed in an offline app must be of Assign-Worklist type.
- pyWorkParty is not supported while working offline.
- The confirm harness used is the confirm harness that is set on the pyStartCase flow.
- When building an application on top of another application, you cannot reuse flows from the built-on application in offline cases. To solve this issue, save the flows again into the class of the current application.
Other considerations
The following information is important to know while using mobile offline capability.
- The following is a Pega Mobile Client and data sync limitation:
- The data page size cannot be larger than 8,000,000 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).
- You can extend the app by using a CallActivity extension point. Refer to CallActivity action as an extension for details.
- You can include external 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.
- Add a custom script by saving the
- When using defer load support:
- The defer loaded sections or layouts are loaded on the initial load, and the defer load pre-activity is always ignored.
- Defer load is not supported in tabs. You must use a layout group instead.