Can I use Savable Data Pages to create a new instance? 

We had a lot of questions about this - it can be done.

Firstly, remember that the first thing any Data Page (including Savable Data Pages) does is to attempt to load from its Data Source, likely using keys captured via the application UI used to lookup the instance from the System of Record. If the instance doesn't yet exist, depending on the data source this will yield either an empty result set, or an error. 

If your application need is to capture details for creating a new instance when none exists, ensure the Response Data Transform or Post Load Processing Activity clears any "record not found" error from the page (for it is not an error in your scenario) and stages the Data Page to provide any default values for creation of a new instance.  Depending on the User Experience you provide for creating a new instance, the loading of the Data Page may be triggered before you have captured (all of) your keys. Consider having the parameters optional and have conditional Data Sources that run an inexpensive, 'stub' Data Transform (such as @baseclass.empty) if the keys are blank or incomplete. Once all key values have been captured, these are a distinct parameter combination resulting in a new Data Page instance being loaded, this time attempting a look-up from the genuine Data Source. Any existing instance for the keys entered can then be retrieved and shown in the User Experience, rather than capturing a second item for the same set of keys.

If your Data Page is used multiple times to capture multiple new instances in a list (for example, adding many drivers to a car insurance policy), also include an additional optional "index" parameter to the Data Page that holds a different value for each item in the list. This is purely to ensure that multiple, potentially-unkeyed Data Pages remain resident as distinct pages on your clipboard to capture each new instance separately. Remember if the application seeks a Data Page with the same parameter values as one that already exists on the clipboard, it will use that one and not load a new one.

Once the Data Page is loaded with default values for a new instance, it can become the context page for part of your Flow Action's User Interface and be directly populated with content entered in the application. Assuming Flow Action completion is the right time to save this Savable Data Page, its Save Plan can navigate the different approaches needed. 

• For a Database Save, like with Obj-Save, the record will be created if a record doesn't exist with the values entered for the keys; or will be updated otherwise. Saves are deferred by default.
• For other Save types, conditional logic in the Save Plan can test a property staged on the Data Page to determine whether it should do a Create or Update operation, and use the appropriate save path. For example, Connect-REST rules typically use POST for Create operations but PUT for Update Operations, with some slight variance in the Request payload. This complexity could be pushed into an Activity if needed. Consider this as a last resort, but feel empowered to do so. 

However, don't ever use Commit in your Save Plan activity as this will commit deferred saves that are unrelated to your Savable Data Page. Investigate the WriteNow support for the Save Data Page options if your Save Plan database changes need to be immediate, but ideally treat these as any other deferred saves.

Finally! Pega 8.4 adds better support for referencing Savable Data Pages from Flow Actions, Flows and Activities via Auto-populate properties. This allows you to encapsulate the relationship between your case data model and the Data Pages that supply your case with persistent data within the Property configuration, and reduces the number of places that you need to both explicitly reference the Data Page names and wire in the correct parameters they require. 

The create/update use case is a good example of where the "Copy data from data page" Auto-populate option could be used. As above, once you have the keys, you likely want to retrieve any existing instance (or stage a new, 'default' instance if none exists), allow the user to start capturing modifications, but allow those in-flight modifications to be saved with the case data if they don't complete the action before the end of their day. So long as the keys don't change, the Auto-populate property that uses "Copy data from data page" will retain the in-flight modifications and not reload the Data Page from the System of Record, allowing the user to complete their action later. On completion of the action, if the Auto-populate property is included on the Flow Action's "Save Data Pages" list, then the changes are posted to the System of Record by the Save Plan on the Savable Data Page.

Discussion on this topic was sought from the LSA Data Excellence (Pega 8.4) webinar conducted in July 2020. The webinar and its full set of discussions that arose from it are available at LSA Data Excellence: Webinar, Questions & Answers.