UX cleanup: Adding an alert integration

Summary

While we work to add custom mappings for HTTP alert integrations &4390 (closed), we are (obviously) adding more complexity to the form for adding integrations.

Over the course of enabling multiple HTTP integrations for GitLab Premium+, we made a few concessions in UX to accommodate technical needs. With custom mappings, we're making a few more.

Notable issues:

Area	Issue	Solution overview
Error handling	A “can’t add integration” message doesn’t really tell users why things have failed or how to fix them	Improve error messaging so it's more descriptive - explain what the failure was (if possible)
Error handling	We’re using alerts for things like “name can’t be blank” rather than form validations (which appear directly under the fields that have the errors)	Update alert text: "There are errors that need to be corrected in the form," and add in form field validation under the required fields: "Name field can't be blank," etc. Do not collapse form if there is a failure
Initial setup	It’s unclear that the token & url for a new integration aren’t available until the integration has been saved for the first time	Update intro text and hide the URL/auth key fields as they aren't available (design shown below). Include a button for accessing the webhook/URL after successfully saved and form has collapsed that links directly to the view credentials section.
Initial setup	It's unclear that a user on GitLab Premium may choose to opt out of using custom mappings by leaving the mappings blank	Update intro text to custom mapping section; details shown below
Initial setup	The 'sample payload' field is not optional for custom mappings, but the title indicates it is	Update section intro text as shown below
Test alert	Disabling the sample payload fields for custom mappings makes it difficult/weird to trigger a test alert with a secondary payload. It means the user must accept the “mappings are about to break” message before they can do so.	Separate out the test alert functionality into a separate tab; Only disable the sample payload field on the custom mapping form/show the warning message if a payload has already been submitted
Test alert	The sample payload field is disabled, even if the user intends to use the built-in gitlab alert mappings (rather than the custom mappings).	Separate out the test alert functionality into a separate tab; Only disable the sample payload field on the custom mapping form/show the warning message if a payload has already been submitted
Test alert	The sample payload mapping is disabled before a user ever enters content into it (even with an integration toggled to ‘active’)	Should only be disabled if content had been entered into it and saved previously
Re-attempts	When an integration has failure for whatever reason, the menu still closes while using the 'Save Integration' button	Section should not collapse when there is a failure
Re-attempts	Sometimes values in the form carry over from a previous attempt at editing the form; sometimes they disappear between attempts	Previously entered values should remain

Solution details

List View

Changes:

• Hide 'Add new integrations' form by default
• Introduce 'Add new integration button'
• Display PROMETHEUS type as Prometheus
• Change pencil icon to settings icon
• Settings icon should open 'Configure details'

Integration tabs view

High-level: We replace the Add/Edit view with 3 justified tabs: 'Configure details,' 'View credentials,' and 'Send test alert.' 'Configure details' takes the bulk of the existing Add/Edit functionality, but the credentials and test alerts are off-loaded to their own sections of the UI.

Clicking on a tab should switch visible content for that integration. Content in the fields should be preserved when switching between tabs. For example, unsaved changes made in the 'Configure details' should still be visible if the user navigates to the 'Test alert' tab, then back to the 'Configure details' tab.

Configure details

	HTTP Core	HTTP Premium	Prometheus
Add
Edit

Changes:

• Remove form title ('Add new integrations')
• URL/token fields are removed
• Introduce field validation for required fields, and improve the general error messaging (right now, the error just says, "Failed to save the integration.")
• 'Cancel' button is renamed 'Cancel and close'
• 'Cancel and close' button discards changes and closes the form, revealing the 'Add new integration' button
• 'Save and test payload' button is removed
• Hide title field on the Prometheus form
• 'Save integration' button should be btn-confirm instead of btn-success
• On successful save, add a link to the 'Configure details' tab for the integration to the success alert (design shown in the top portion of this image)
  • Because the page has a table and a static URL, any anchor tag will not be tied to the particular integration, but is tied instead to the spot on the page for any integration which is currently open. If no integration is open, the anchor tag will not be tied to anything. This is the case for either the tab view or the the original form. So if the user copies the link from the button, it will not necessarily lead to the right place if they try to share it with other people or use it later.
  • We're ok if the link/anchor just leads to the correct section while the current page is open & isn't shareable with other users. Credentials aren't needed often and don't necessarily need to be shared. We can look at LOE of making this link shareable as part of implementation.
• Section should not collapse when there is a failure; previously entered values should remain
• [Core] Sample payload field is removed

Add-view-only changes

• Disable 'View credentials' and 'Send test alert' tabs
• On successful save, navigate the user directly to the 'View credentials' tab
• 'Submit payload' button for sample payload is replaced with text 'Parse payload for custom mapping'

Edit-view-only changes

• Hide the 'Select integration type' field
• Disable 'Save integration' button until user as modified a field on the page
• Allow the payload field to be editable by default providing no payload as previously been saved. (It's currently disabled.)
• On successful save, close the form so 'Add new integration' button is visible again
• [Prometheus] Hide the 'Name integration' field

Credentials view

Changes:

• URL/token fields should be added to this view
• 'Reset token' button should be main action on the tab (Danger button)
• After a user resets the token, leave the form open
• 'Close' button should be added which closes the form and makes the 'Add new integration' button visible again

Test alert view

Changes:

• Payload field should be added
• Include text at the top of the tab explaining that test alerts can only be sent to active integrations.
• 'Discard and close' button should be added. This will clear the field and close the form, allowing the 'Add new integration' button to be visible again
• 'Send' should be the main action on the tab.
  • Clicking 'Send' should use the provided input as the payload for a test alert.
  • Clicking 'Send' should NOT save the integration. The integration will have credentials already available.
  • After clicking 'Send' the form should stay open.
• If a user clicks 'Send' while there are unsaved changes in the 'Configure details' tab, pop up an alert.
  • Pop-up should provide two options: 'Save integration & send' || 'Proceed without saving integration'
  • If user proceeds without saving, changes made in the 'Configures details' section will still be preserved.
• In the "successful test alert has been sent" message, add a View your test alert link that will open up the alert list page in a new tab.