[Security Solution] Rework Update flyout to display all field updates and build Three-Way-Diff field component

[jpdjere]

Epics: https://github.com/elastic/security-team/issues/1974 (internal), #174168
Design Discussion context: #178211
Design: Figma (internal)
Miro board with UI components breakdown: https://miro.com/app/board/uXjVK0gqjjQ=/?share_link_id=554028328760
Screenshot of the Miro board (click to expand)

TODO (click to expand)

This is roughly the order I plan to implement these.

Front-end logic

• Make there is clear understanding of edge cases in the rules upgrade workflow
• Come up with initial React Context implementation
• Integrate React Context with the components below
• Integrate UI with the _perform upgrade API (PR)

Components: ComparisonSide (left side, please refer to the Miro board to see where it is)

• [PR #188302: merged] Add VersionPicker component that displays a dropdown component to select which 2 versions to compare.
• [PR #189384: merged] Add an InlineDiffView component that uses the existing DiffView component, but in inline diff mode.
• [PR #189384: merged] Add a ComparisonSide component that combines VersionPicker and InlineDiffView
• Get rid of resovedValue ?? merged_version logic

Components: FinalSide (right side)

• Add SaveButton component that saves user changes when they are valid and ready.
• Add EditButton component that switches the edit mode on
• [PR #191499: merged, PR #192342: merged, PR #193261: merged] Add FieldReadOnly component that renders a suitable component / components from the Rule Details page based on the passed field name.
• Add FinalReadOnly component that combines EditButton and FieldReadOnly

Components: FieldEdit
FieldEdit components are components that render one or more UI elements from the Rule Editing page for every field.

Field edit components

• Common Diffable rule fields (PR) @nikitaindik (2d)

  • name (done in PR)
  • tags
  • description
  • severity
  • severity_mapping
  • risk_score
  • risk_score_mapping
  • references
  • false_positives
  • threat
  • note
  • setup
  • related_integrations
  • required_fields
  • rule_schedule
  • max_signals
  • investigation_fields
  • rule_name_override
  • timestamp_override
  • timeline_template
  • building_block

• data_source (PR)

• alert_suppression (PR) (2d)

• kql_query (PR)

• eql_query (PR) @maximpn (3d)

  • event_category_override
  • timestamp_field
  • tiebreaker_field

• esql_query (PR) @maximpn (2d)

• Threat Match rule specific fields (PR) @maximpn (5d)

  • threat_query
  • threat_index
  • threat_language
  • threat_mapping
  • threat_indicator_path

• ML rule specific fields (PR on hold, approx. until 2nd half of December) @nikitaindik

  • threshold
  • machine_learning_job_id
  • anomaly_threshold

• New terms rule (PR on hold, waiting for review and testing, approx. until 2nd half of December) @nikitaindik

  • new_terms_fields
  • history_window_start

Common functional components

• Add FinalEdit component that combines SaveButton, Prefill and FieldEdit components.
• Add FinalSide component that displays either a FinalReadOnly or a FinalEdit component depending on the state.

Components: Basic layout

• Add a new tab component for the three-way diff and hide it behind the prebuiltRulesCustomizationEnabled feature flag

• Add PerformUpgradeButton component that will trigger the upgrade.

• Add UpdateInfoBar component that will display the number of updatable fields and a number of fields that have conflicts.

• Add RuleDiffSection component that will display a collapsible section with a label like "Definition", "About" or "Schedule".

• Add RuleFieldDiff collapsible component that is expanded by default if conflict is SOLVABLE or NON_SOLVABLE.

• Add RuleDiffFieldHeader component that displays the conflict bagde and Accepted/Auto-accepted label. (needs conflict)

• Display fields with SOLVABLE and NON_SOLVABLE conflicts expanded

• Display fields with SOLVABLE conflicts in readonly mode

• Display fields with NON_SOLVABLE conflicts in editing mode (PR) @maximpn

• Implement changes accepting workflow (see Miro chart) (PR) @maximpn

  • Make sure UI and copy match the design in Figma. Display Save, Accept and Save and accept buttons in the field's right side header. Remove Save button from field's right side content.
  • No conflict - Readonly mode doesn't show Save nor Accept buttons, Edit mode shows Save button, badge Auto-accepted (green) after accepting changes
  • Solvable conflict - Readonly mode shows Accept button, Edit mode shows Save and accept or Save button, badge Solved conflict (yellow) before accepting and Solved conflict (green) after accepting
  • Non Solvable conflict - Edit mode shows Save and accept button, badge Unsolved conflict (red) before accepting and Solved conflict (green) after accepting

• Improvements to the UI and copy of the flyout (PR) @maximpn

  • Change icons to more informative badges
  • Update high level callout to : Update status callout, updated copy
  • Updated copy for field update information in the header
  • Update the copy for the transition of solved/Unsolved to ready for update.

• Improvements to the copy of the dropdown to select the diff view (Make diff options more human friendly) (PR) @maximpn
  Base = Original
  Current = Current
  Target = Elastic update

  

Editable components issues

• allow users save queries when indices/fields validation doesn't pass (users don't have ES data) @maximpn
• ES|QL Query toolbar is displaying in a wrong place [Security Solution] Add ES|QL Query editable component #199887 (comment)
• Threat Match Mapping Edit component displays empty values instead of real ones. This is a bug in EsFieldSelector which doesn't display a field name if it's missing in the selected indices. It will be addressed in a follow up PR. Addressed in Threat Match Mapping Edit component PR.

Demo feedback

• Add help texts (popup texts should contain helpful information regarding comparison side like diff options and final side like what will be saved eventually) (PR) @nikitaindik
  
• Display readonly placeholders when there is field value is empty (PR) @nikitaindik
• Make diff view options easier to understand (PR) @nikitaindik
  • Fields without customization should have less diff selector options. When base == current we may omit base (AAB case).
  • Customized fields without updates shouldn't have Elastic update option (ABA case).
  • Options should be goal oriented for example Review my changes showing base vs current and Review Elastic update showing base vs target, Review result showing current vs final. We also can consider removing some options.
  • Current vs Final often shows No changes. It's confusing. We could show Review Elastic update by default instead.
  • Some diffs options might be better readable when flipped. For example current vs target may show rows removed while user added data when editing a rule but target version doesn't have that data.
• (Optional) Add unsaved changes modal confirmation upon flyout closing
• (Optional) Show non-diff view of the changes (target rule field)

---

To address in separate tickets scope (TODO move to appropriate tickets)

Testing

• Write a test plan
• Write tests (will split this into more todos once the test plan is ready)

Refactorings

• Make sure the table and the whole flyout don't re-render on every "save" of a field value
• Extract editable components from Rule creation/editing UI into a separate directory
• (If necessary) Reiterate in React Context after integration to fix/improve the implementation
• Simplify generic types
• Storybook: Sort simple cases before advanced ones
• Storybook: Find a way to add explainer comments in Storybook

Product enhancements

• Try to diff JSONs instead of individual subfields
• Research necessity of state persistence in local/session storage
• Add Prefill component that displays a dropdown with versions available for prefill.
• Update RuleDetailsFlyoutHeader flyout header with components that are shown in designs, for example a badge for Customized Elastic rules.
• Add a component that displays the "Modified" badge for the fields that were edited

Summary

As part of the Prebuilt Rules customization epic, we need to:

1. Update the Update tab from the flyout that pops up open when clicking on a rule in the Rule Updates table.
2. Build a Three-Way-Diff field update component that will be used multiple times for each rule update in the Update tab from point 1, one for each rule field that has an update.

1. Update tab

The Updates tab currently displays a list of fields to be updated, in side-by-side view of the current and target version of each. This basic structure will be maintained, but for each field, the side-by-side diff component will be replaced by the Three-Way-Diff field component described in step 2.

The tab needs other changes:

• An info bar at the top that displays:
  • How many fields have reviewable updates.
  • How many conflicts the upgrade presents
• The "Update" button at the bottom needs to be updated to "Preview update" with the following functionality:
  • Will be disabled until all changes are saved and accepted by the user
  • When clicked, will transition the tab to a Rule Update Preview view.
• Implementation of the "Rule Update Preview view":
  • Reuses the existing JSON diff component to display the side-by-side diff between the Current version and the Final version of the rule in JSON format.
  • The Final version is: the Current version + all autoaccepted field updated + all changes accepted by the user

2. Build a Three-Way-Diff field update component

The Three-Way-Diff field update component allows users to:

1. see and understand the current value for a rule's field
2. see what updates the next version of the rule (coming from the upstream Prebuilt Rules package) proposes for that field
3. be offered a merged version of the current value and the target version of the field
4. edit the "merged version" of the field as they prefer, write one from scratch if no proposal for a merged version is automatically made; or use the base, current, or target version as a starting point from which to create a new value for the field
5. accept the new value for the field

The initial designs for the current component look like so:

Figure 1:

Figure 2:

Notice that this is only an initial iteration and does not include the specs written in this ticket.

Component description

We are thinking about a component that, by default, shows two columns:

• Left column: Used to compare different version of the rules, with an inline diff. For example, current vs target, base vs. target. (This is outdated in the design screenshots pasted above)
• Right column: Used to display, update and confirm the Final version of the field, which will be saved on upgrade.

Left column

The Left column will display, by default, an inline diff between the current and the target version of the field.

This column will additionally display two dropdowns that enable the user to select the two versions being compared. Alternatively, it could be just one, offering the combinations:

• Base vs target
• Base vs current
• Base vs final version
• Current vs target
• Current vs final version
• Target vs final version

Selecting one of the options above will update the content of the Left column to display the diff between those two version.

Right column

The Right Column (Final Version) will contain:

A component displaying the Final Version of the field that will be saved when the upgrade is confirmed. This component can be switched between a read-only view (as seen on the first image above, at the top) and an editable component (as seen on Figure 1, above).

The Read-Only view can be switched to the editable component by clicking on the "Edit" button, and vice-versa by clicking on the "Save button".

The Final version will be displayed differently depending on the value of the conflict field from API response for that field:

• if the value is NO:
  • display, by default, the Read-Only component containing the merge, as seen in Figure 1 above. The "Edit" button can be clicked to switch to the editable component and further edit the field.
  • the field component will be Auto-Accepted and thus collapsed by default
  • a label with the "Auto-Accepted" and a green checkmark will be displayed
• if the value is SOLVABLE:
  • display, by default, the Read-Only component containing the merge proposal. The "Edit" button can still be clicked to switch to the editable component and further edit the field.
  • the field component will be expanded by default
  • a label with the "Conflict" text should be displayed
• if the value is NON_SOLVABLE:
  • display, by default, the Edit component containing the merge proposal (which matches the current version). The "Save" button can be clicked to accept the change.
  • the field component will be expanded by default
  • a label with the "Conflict" text should be displayed

Prefill version dropdown

The Right column will have a button located on top of the component that displays the Final Version that allows the user to fill in (prepopulate) the editable field, by offering the options:

• Prefill with Base Version
• Prefill with Current Version
• Prefill with Target Version
• Prefill with Merge Version (only if merge proposal is available)

Selecting any of the first two options will populate the merge proposal column with either the Current or Target version, respectively.

"Accepted" label

When the user has finished editing the field (prefilled, or edited manually, or just want to keep the proposed merged value), they should click on the "Save" button to "Accept" the changes.

Once the user clicks on the "Save" button, the field updates to display an "Accepted" label with a green tick to confirm that the change for the field was approved by the user and validated by the app.

(If the API response has the value of the conflict field set to NO or SOLVABLE, the field will appear from start as auto-accepted)

When the user clicks on "Save", if the change is validated, the accordion container of the field will collapse. If the accordion is reopened, the component should be in read-only view.

The user can "Un-Accept" a change by manually opening the accordion and clicking on the "Edit" button. That action will "Un-Accept" the field and will "block" the the update of the rule until the field is saved again, by clicking on the "Save" button (all fields to needs to be accepted in order to update the rule).

**EXPAND:** This is a UX similar to the file per file review in Github PR's and the feature to mark a file as "Reviewed":

Before marking file as reviewed

After marking file as reviewed

ONLY once all fields have been confirmed (all have green ticks) the user can make the request to update the rule. (This however is not part of the spec for this component, but important context to understand its role)

Other considerations:

• When updating a rule, the Three-Way-Diff components for all fields should be ordered in such a way that the fields that have CONFLICTS are located first, at the top.
• Certain fields needs to be read-only: the right in the right should be either disabled, or we should prevent the user from going into edit mode. The fields that should be read-only are:
  • version
  • revision
  • author
  • license

[elasticmachine]

Pinging @elastic/security-detections-response (Team:Detections and Resp)

[elasticmachine]

Pinging @elastic/security-solution (Team: SecuritySolution)

[jpdjere]

FYI @approksiu @ARWNightingale

[banderror]

This is a great writeup @jpdjere, very comprehensive and accurate 👍 Thank you!

I made a few small adjustments in the text (description is already updated):

-Selecting any of the first two fields will populate the **merge proposal** column
+Selecting any of the first two options will populate the **merge proposal** column
with either the Current or Target version, respectively.

+When the user finished editing the field (prefilled, or edited manually, or just want to
+keep the proposed merged value), they should explicitly accept the change for this field.
-Once the user selects a version, and accepts it via an **"Accept" button**
+Once the user clicks an **"Accept" button** 
located somewhere in the component (preferably near the third column?),
a **checkbox** gets automatically ticked located on the top right, to confirm
-that the change for the field was successfully selected.
+that the change for the field was approved by the user and validated by the app.

@jpdjere @ARWNightingale @approksiu I have a few other thoughts:

• We should find a more user-friendly terminology for the "Current", "Target" and especially "Merged" versions in the UI. I suspect many users might not be familiar with versioning concepts and what merging means in VCS. The third column could be called "Final version" or "Version to save" or something like that.
• Maybe we should explicitly show a field if it was customized by the user but NOT changed by Elastic in the Target version (which we don't do at the moment). And prefill the 3rd column with the Current (customized) version.
• Maybe we should auto-accept changes in trivial cases (but still allow the user to change the value after it was accepted):
  • StockValueCanUpdate = 'BASE=A, CURRENT=A, TARGET=B'
  • CustomizedValueNoUpdate = 'BASE=A, CURRENT=B, TARGET=A'
  • CustomizedValueSameUpdate = 'BASE=A, CURRENT=B, TARGET=B'
• We should never auto-accept changes when the field was customized + there's an update from Elastic, regardless of whether it's a conflict (we were NOT able to auto-merge) or non-conflict (we were able to auto-merge). In such cases the user should always have to manually accept the change.
  • CustomizedValueCanUpdate = 'BASE=A, CURRENT=B, TARGET=C'
• In the CustomizedValueCanUpdate = 'BASE=A, CURRENT=B, TARGET=C' cases, we could not only highlight conflicts, but also add some extra indicators/labels for non-conflicts when we were able to auto-merge the changes.