UX Add-on Mappings Duplicating into “Incorrect” Scope (Broken New Button, Broken Reference Buttons)

[Thomas Walker2]

Overview

In UI Builder pre-Vancouver when duplicating a page the UX Add-on Mappings [sys_ux_addon_event_mapping] duplicates into the original page's mapping record's scopes. Meaning if you duplicate the list page, the declarative action mapping that hooks the “New” button up to the LIST#NAV_ITEM_SELECTED event is placed into an unexpected scope/update set. In the case of the New button, the record is in Common Page Templates scope and if you promote the new variant via just the scoped app, the button won’t work.

The button will work fine in your development environment, but when you go to move the application to another instance, the button will suddenly stop working. Since the other UI Builder records move correctly with the scope (this is the only exception I know of), this is really unexpected.

Explanation of the Issue

The actual sys_update_xml update for the mapping is captured into your active update set (the correct scope), but with the sys_scope field on the record set to the same scope as the mapping on the macroponent being duplicated. Pretty odd since update sets by nature only contain updates for a single scope.

When moving the application, if you export the update set directly from the default update set for your scoped app, it does contain the updates for the mappings, but issues arise. In my testing when attempting to retrieve that update set, it won’t appear in the Retrieved Update Sets table and nothing appears in the logs so there is no way to move the application. Simply, the update set loader gets mad about the malformed updates.

If you instead publish the scoped application to an update set, the UX Mapping records are omitted, and the update set will function as intended. When previewing, no preview errors are thrown, as the missing records are not themselves referenced by anything but your mappings will be broken.

This behavior is incredibly confusing as the updates are placed into an update set they cannot exist in, meaning they won’t create new default updates sets for you to notice and the only way to locate them is by having prior knowledge of the issue or trolling sys_update_xml for any offending records, which is incredibly tedious. They are in some ways, ghost updates, existing in sys_update_xml, but not in a valid update set that they could ever be applied/moved in.

How to Fix

To locate the UX Add-on Mappings for a particular page variant, navigate to that page variant in UI Builder. Depending on your version the actual button is in different places, but Developer > Open page definition will take you to the macroponent the events are mapped to.

Copy that record’s sys_id, this is the parent_macroponent referenced on the sys_ux_addon_event_mapping table. There isn’t a navigator module for the table so use SNUtils (or  sys_ux_addon_event_mapping.list in appnav) to navigate to the table for mappings.

Configure the filter for parent macroponent = {your problematic page}, you may need to apply a sys_id = xyz filter on the reference picker to find it, many macroponents have the same name and are a pain to distinguish, which is why we grabbed the sys_id directly.

If it works you should see, depending on the page, a few records. Adding the Application field to list view, you’ll find that they are spread across several different application scopes. These are your offending records.

 If you don’t find any records, but believe there should be some, you may have messed up the filter or likely a clone down overwrote the mappings that never got promoted when you created the page. The solution to that is similar to the solution if you have caught the issue in time, but I’ll detail that later.

If you are able to locate the mapping records in the wrong scopes you have two options. First is to move those updates to an update set for their respective application, so they can be promoted. Alternatively, you can recreate the mappings in the correct scope. The easiest way to do this in my opinion is to open each mapping and insert and stay. Then go back and delete those original updates in incorrect scopes.

Since its just totally broken by default, with manual intervention required to get anything to work, I lean towards option 2 since that means I don’t need to promote six additional update sets for a customized record page but this is uncharted territory so test, test, test.

Frankly, I haven’t tested moving the updates to proper update sets and promoting since rescoped records worked for me and these records feel like they belong in my applications scope and not the scope of one of a plugin my application requires.

No Trace of Mappings / Post Clone Down

If you find yourself with no trace of the mapping records (likely after a clone down) you may need to duplicate the mappings from the page you duplicated from manually. To do that, open the page definition of the original page, copy the sys_id, locate the event mappings. But instead of just inserting all the records you’ll need to first insert, then update the Parent macroonent field to reference the duplicated page. (Again sys_id = filter on macroponent is your friend since the macroponents are often named alike) This isn’t guaranteed to work, the default page you duplicated from may have evolved since you first duplicated it, but hopefully this gets you on the right track.

A Quick Litmus Test for your Variants

The way this manifests most commonly is dead button on duplicated pages. If you have cloned a page, promoted, and found things to be broken inexplicably, this may well be your culprit. A good litmus test for if you have broken mappings is to on a higher environment (or in dev post clone) check the New button on list pages or on record pages the (i) preview reference icon. Remember you need to check each variant as the mappings are page specific.

Vancouver/Wrap-up

Hopefully, once every single UI builder dev reads this article and gives me a thumbs up, you can incorporate fixing the mappings into your workflow and run into no surprises when promoting.

In my testing, this issue did exist in Utah Patch 7a and Tokyo Patch 10, but in a fresh Vancouver Patch 2 instance, the records were duplicated into the correct scope, and they moved via a published scoped application update set successfully. So, you won’t need to mitigate the issue forever. Vancouver placing the mappings into the correct update set also bolsters my opinion that simply moving the problematic updates to the current scope is acceptable.

Video Explanation

Helpful Links

Introduction to Declarative Actions/UXF Events/Mappings 

Next Experience Center Of Excellence

SNUtils - (If you use it and love it, give it a positive review or join Arnoud's patreon, the price of two cups of coffee a month is a small price for your sanity)

[Thomas Walker2]

Another interesting finding is that the "new" record page doesn't use many UXF client actions, so when duplicating the more modern record page, you are far less likely to run into this issue. The only UXF client action on CSM's version of the new record page is 'Open create collab chat'. 

[ArminB]

Thank you Thomas.  I almost missed the part of fixing the new (properly scoped) record.  The Parent Macroponent can be set in the event mapping list view. And yes, you still need your page variant's Sys ID to find the right record in the picker window. This is all tricky stuff. So glad you posted this blog!