#3940: Update messages for adding a domain manager - [aa] #4225

abe-alam-ecs · 2025-09-25T16:10:33Z

Ticket

Resolves #3940

Changes

Edited error messaging
Added helper function for hyperlinking "contact us" to views.

Context for reviewers

There are certain cases in which domain manager updates should not be allowed. Review the story's mural and excel, linked here for convenience.

spreadsheet
Mural

Examples:

adding someone who is already a domain manager as a domain manager
adding someone who is a part of a different portfolio as a domain manager

Setup

Create a domain that you manage if one does not already exist
Execute workflows in the mural/excel above... for example:

Go to a domain you manage (or create one)
In the Domain Managers section, click Edit
Try adding yourself as another domain manager. It should fail with an error message, "An unexpected error occurred. Try again, and if the problem persists, contact us." with a hyperlink on contact us.

Repeat such tests for the 12 error message updates.

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

Met the acceptance criteria, or will meet them in a subsequent PR
Created/modified automated tests
Update documentation in READMEs and/or onboarding guide - N/A

Ensured code standards are met (Original Developer)

If any updated dependencies on Pipfile, also update dependencies in requirements.txt. - N/A
Interactions with external systems are wrapped in try/except
Error handling exists for unusual or missing values

Validated user-facing changes (if applicable)

Follow the process for requesting a design review. If code is not user-facing, delete design reviewer checklist
Verify new pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
Checked keyboard navigability
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

Pulled this branch locally and tested it
Verified code meets all checks above. Address any checks that are not satisfied
Reviewed this code and left comments. Indicate if comments must be addressed before code is merged
Checked that all code is adequately covered by tests
Verify migrations are valid and do not conflict with existing migrations

Validated user-facing changes as a developer

Note: Multiple code reviewers can share the checklists above, a second reviewer should not make a duplicate checklist. All checks should be checked before approving, even those labeled N/A.

New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
Checked keyboard navigability
Meets all designs and user flows provided by design/product
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
(Rarely needed) Tested as both an analyst and applicant user

As a designer reviewer, I have

Verified that the changes match the design intention

Checked that the design translated visually
Checked behavior. Comment any found issues or broken flows.
Checked different states (empty, one, some, error)
Checked for landmarks, page heading structure, and links

Validated user-facing changes as a designer

Checked keyboard navigability
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
Tested with multiple browsers (check off which ones were used)
- Chrome
- Microsoft Edge
- FireFox
- Safari
(Rarely needed) Tested as both an analyst and applicant user

References

Code review best practices

Screenshots

…es-for-domain-manager

github-actions · 2025-09-25T16:50:02Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-25T16:51:58Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-25T19:19:44Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-25T19:26:29Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-25T19:54:06Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-25T20:02:08Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-26T13:59:56Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-26T17:07:50Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-26T20:27:24Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-26T20:34:55Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-09-29T13:31:29Z

🥳 Successfully deployed to developer sandbox aa.

erinysong · 2025-09-29T22:11:28Z

src/registrar/utility/email_invitations.py

            exc_info=True,
        )
-        raise EmailSendingError(f"Could not send email invitation to {email} for domains: {domain_names}") from err
+        raise EmailSendingError(f"An unexpected error occurred: {email} could not be added to this domain.") from err


Also noticed the spreadsheet also includes " Try again and contact us if the problem persists." but feel free to ignore if that's outdated!

✅ dm-add-alert006: Feel free to ignore below but flagging just for documentation that this error can be prompted without inviting the user to an organization

I noticed the Mural said this event should result in 2 error messages: dm-add-alert005 and dm-add-alert006 (I think the dm-add-alert006 alert message on the Mural also is different from the message in the spreadsheet, but assuming spreadsheet is the source of truth).

However, when I prompt dm-add-alert006, I do not get dm-add-alert005. But would it make sense to show dm-add-alert005 here? In this case we didn't invite the user to the organization (no domain invitation was made) so I may also be prompting this message in a different way than originally intended.

also keeping that screenshot to verify we successfully concat the contact us message

✅ dm-add-alert013: Correct alert message update

src/registrar/admin.py

erinysong

Left some comments but let me know if things have changed from the spreadsheet sections I reference, since you've been working on this more closely!

github-actions · 2025-09-30T19:52:35Z

🥳 Successfully deployed to developer sandbox aa.

erinysong · 2025-10-03T17:04:23Z

src/registrar/utility/errors.py


    def __init__(self, email):
-        super().__init__(f"{email} is already a manager for this domain.")
+        super().__init__(f"An unexpected error occurred: {email} could not be added to this domain.")


recapping our call: I think this error message doesn't need to be changed and can be reverted to the original message!

erinysong · 2025-10-03T17:08:47Z

src/registrar/utility/email_invitations.py

-        raise EmailSendingError(
-            f"Could not sent email invitation to {email} for portfolio {portfolio}. Portfolio invitation not saved."
-        ) from err
+        raise EmailSendingError(f"An unexpected error occurred: {email} could not be added to this domain.") from err


✅ dm-add-alert001: typo fixed

github-actions · 2025-10-03T17:12:02Z

🥳 Successfully deployed to developer sandbox aa.

erinysong · 2025-10-03T17:13:51Z

src/registrar/utility/errors.py

        # Default message if no additional info is provided
        message = "Can't send invitation email. No email is associated with your user account."

-        # Customize message based on provided arguments


✅ dm-add-alert002: Remove email, domain, and portfolio from error messages and replace with single, generic message.

erinysong · 2025-10-03T17:14:26Z

src/registrar/views/utility/invitation_helper.py

        messages.error(request, str(exception))
    elif isinstance(exception, IntegrityError):
-        messages.error(request, f"{email} is already a manager for this domain")
+        messages.error(request, f"An unexpected error occurred: {email} could not be added to this domain.")


✅ dm-add-alert003: Correct generic IntegrityError message

✅ dm-add-alert012: Correct generic IntegrityError message

erinysong · 2025-10-03T17:18:08Z

src/registrar/views/utility/invitation_helper.py

    else:
        logger.warning("Could not send email invitation (Other Exception)", exc_info=True)
-        messages.error(request, "Could not send email invitation.")
+        messages.error(


✅ dm-add-alert004: Update to generic error message

erinysong · 2025-10-03T17:27:01Z

src/registrar/admin.py

                        portfolio_invitation.retrieve()
                        portfolio_invitation.save()
-                    messages.success(request, f"{requested_email} has been invited to the organization: {domain_org}")
+                    messages.success(request, f"{requested_email} has been invited to become a member of {domain_org}")


❓ dm-add-alert005: Noticed that when we add a domain manager who is not yet a member of the domain's organization, we have 2 error messages. The first one is the correctly updated alert message, but I was wondering if we should be seeing that bottom one as well? It doesn't match any of the error messages from 006-010

I wasn't sure if the messages and alert type (success + failure) may be confusing or contradictory but @witha-k @SamiyahKey will defer to your judgment since you're more well-versed in this

I think this is intended per @witha-k 's conversations with me. Tagging @SamiyahKey as backup.

I think it still makes sense to keep both. It's letting the user know that whomever they added was not a member of this organization (which is why a domain invitation could not be sent) and that an portfolio invitation to join the organization was sent instead. Otherwise, the user might not know why a domain invitation was not sent. And if we don't keep the success message, they might not know that a portfolio invitation was sent instead...

erinysong · 2025-10-03T17:49:00Z

src/registrar/views/portfolios.py

            messages.error(self.request, str(exception))
            logger.error(
-                f"Can't send email to '{email}' for portfolio '{portfolio}'. No email exists for the requestor.",
+                "Can't send invitation email. No email is associated with your account.",


✅ dm-add-alert007: Update alert message language

src/registrar/utility/errors.py

src/registrar/views/utility/invitation_helper.py

erinysong

✅ dm-add-alert010: User gets correct alert

erinysong · 2025-10-03T19:04:30Z

src/registrar/admin.py

                    requested_user=requested_user,
                ):
-                    messages.warning(request, "Could not send email confirmation to existing domain managers.")
+                    messages.warning(request, "Could not send email notification to existing domain managers.")


✅ dm-add-alert011: alert message updated

src/registrar/views/domain.py

erinysong

Checked the add manager alerts which had requested changes on the spreadsheet! Had a couple questions that I marked with ❓ and change requests marked with 🔄 . Happy to go over these together if that's easier or if I misunderstood anything!

github-actions · 2025-10-14T14:41:09Z

🥳 Successfully deployed to developer sandbox aa.

github-actions · 2025-10-14T15:07:41Z

🥳 Successfully deployed to developer sandbox aa.

erinysong

Deferring to design on dm-add-alert005 - thank you for handling everything thoroughly!

…es-for-domain-manager

github-actions · 2025-10-15T13:53:00Z

🥳 Successfully deployed to developer sandbox aa.

abe-alam-ecs added 2 commits September 23, 2025 10:11

initial changes (need to review, as this seems incomplete)

f1131f0

correction to error messaging V2

9afe1b8

github-project-automation bot added this to .gov Product Board Sep 25, 2025

abe-alam-ecs marked this pull request as draft September 25, 2025 16:10

Merge remote-tracking branch 'origin/main' into aa/3940-update-messag…

de57ae3

…es-for-domain-manager

Test corrections and edits

45c9077

removal of mark_safe and linter corrections

60f35c4

linter fixes V2

9ca35d4

correcting rogue docker compose call in test

d3cf495

changes to success messaging

3f1803b

abe-alam-ecs requested a review from a team September 26, 2025 15:26

abe-alam-ecs added the design-review dev ticket needing design review label Sep 26, 2025

updates for SafeString

c6b5187

SamiyahKey requested review from SamiyahKey and removed request for a team September 26, 2025 18:21

updated language

09d9f36

repeated linting and test fix

9832cf9

Updated language (removed please)

da07008

abe-alam-ecs marked this pull request as ready for review September 29, 2025 14:15

erinysong reviewed Sep 29, 2025

View reviewed changes

src/registrar/admin.py Show resolved Hide resolved

erinysong reviewed Sep 29, 2025

View reviewed changes

updated language for OutsideOrgMemberError

2103075

correcting AlreadyDomainManagerError logic

9ac5424

erinysong requested changes Oct 3, 2025

View reviewed changes

github-project-automation bot moved this to 👀 In review in .gov Product Board Oct 3, 2025

erinysong reviewed Oct 3, 2025

View reviewed changes

src/registrar/utility/errors.py Show resolved Hide resolved

erinysong reviewed Oct 3, 2025

View reviewed changes

src/registrar/views/utility/invitation_helper.py Show resolved Hide resolved

erinysong reviewed Oct 3, 2025

View reviewed changes

src/registrar/views/domain.py Show resolved Hide resolved

erinysong reviewed Oct 3, 2025

View reviewed changes

abe-alam-ecs requested a review from erinysong October 14, 2025 14:16

edits to already manager error messaging

458c8bf

correcting domain invitation success message

7f5cd18

abe-alam-ecs requested a review from SamiyahKey October 14, 2025 15:07

erinysong approved these changes Oct 14, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into aa/3940-update-messag…

14f8d97

…es-for-domain-manager

#3940: Update messages for adding a domain manager - [aa] #4225

Are you sure you want to change the base?

#3940: Update messages for adding a domain manager - [aa] #4225

Conversation

abe-alam-ecs commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Ticket

Changes

Context for reviewers

Setup

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

Ensured code standards are met (Original Developer)

Validated user-facing changes (if applicable)

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

Validated user-facing changes as a developer

As a designer reviewer, I have

Verified that the changes match the design intention

Validated user-facing changes as a designer

References

Screenshots

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

github-actions bot commented Sep 26, 2025

Uh oh!

github-actions bot commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erinysong Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

erinysong left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erinysong Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erinysong Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

abe-alam-ecs commented Sep 25, 2025 •

edited

Loading

erinysong Oct 3, 2025 •

edited

Loading

erinysong Oct 3, 2025 •

edited

Loading

erinysong Oct 3, 2025 •

edited

Loading

witha-k Oct 14, 2025 •

edited

Loading