Building an application to run payroll requires comprehensive communication to prevent missed deadlines, unblock payrolls, update users on changes to taxes, notify users to submit new tax forms, and many more actions needed to ensure a smooth payroll experience. The key to building a successful and clear platform involves sending out the right form of communication at the right time. Gusto has spent years focusing on how to best deliver these notifications in app through emails, dashboard alerts, SMS, and other forms of communication. Gusto Embedded partners want their own notification system built with similar robustness and comprehensiveness. How do we take our external framework, and build a service that accelerates our partners’ implementation and quickly spin up their own embedded notifications?
Current System
Our initial system for communicating to partner end users involved two parts:
- Mark existing Gusto app emails as necessary for Gusto Embedded and expose to partner end users.
- Webhooks that partners can subscribe to for notification of events.
This existing system allowed us to quickly expose any emails for compliance reasons and unblock partners from launching. However, we noted several issues with this approach. Emails from the Gusto app often included resolutions and links for the Gusto app, confusing end users. Partners could not customize their own messaging, branding, and communication forms. Webhooks, although great for exposing events, do not provide any messaging or follow up actions for users.
Goals
Gusto Embedded had several goals when providing partners the ability to build and white-label their own notification system.
- We want to be able to leverage existing communications in the Gusto app so we don’t rebuild new notifications.
- Notifications include recipient information
- Partners can customize the branding and messaging to their end users with the tools to resolve any action items
- Partners control the form of communication to their clients (email, SMS, dashboard alert)
- Thoughtful messaging for notifications to limit excessive noise
Design
Gusto’s communication team recently built out a new To-do (an action-required notification) platform for consolidating all the different forms of communication into one notification framework. This framework consists of templates for constructing messaging to users and a notification database table with the template data populated for each notification sent out. We decided to use a combination of our webhook framework, API endpoints to allow partners to fetch notification details, and a service built on top of the new To-do framework to accomplish our goals. This new embedded service filters out notifications to only include Gusto Embedded communication, control default messaging, and to surface necessary data to resolve any action items.
We built our framework to be read only to give partners complete control of the state of their notification. Our partners would start by subscribing to events for notifications (i.e. created, updated, expired, resolved) to identify when they should update their notification system. Once a notification is created, our partner would fetch the notification details such as title, messaging, expiration, deadline and store it.They then choose to customize their messaging, branding, and communication form to their end users along with providing resolution paths with the notification resources. Partners have the final say on when notifications are resolved although we do provide resolved events from our end as guidance.
Process to migrate comms to partners
The first version of our embedded notification framework required us to convert all our existing critical emails into notifications. Unfortunately, this involved looking into a lot of legacy emails and working with different domain teams to gain enough context to identify where to add creating a notification. We also had to get trained on how to utilize the To-do framework, requiring extensive collaboration with the Gusto comms platform team. The migration process involved first contacting the domain team owning the email to gain context. We would then register a new notification template, identify the creation trigger, and the resolution trigger if necessary. We would then add the notification to the new embedded notification service, ensuring the messaging was appropriate for partners. Once all the emails for a domain were migrated, we collaborated with our Technical Solutions team to build out guides for partners to implement resolutions for each notification.
With this plan in place, our team split up the work so each engineer would own the process for a few domains to reach out and complete the migration process. Several issues we ran into involved teams continuously redirecting context ownership to other teams, owning teams having recently inherited domains without much knowledge, and getting support in general from teams that had low bandwidth. The team also worked around building on top of a notification framework still in the early stages, leading to additional updates as the framework continued to evolve.
After the first few migrations, we decided to have a monthly retro to iterate on our migration process. We ended up making a few adjustments
- Piece together any context, questions, and bandwidth ask in a 1-pager template to send to the engineering manager and product manager.
- Setup sync meetings with respective stakeholders and domain experts to avoid async back and forth and establish concrete action items
- Prioritize reaching out to domain teams early so they can adjust bandwidth as necessary instead of scrambling at the last minute before the deadline.
- Pair as much as possible with engineers from other domains to unblock, even if they are learning too. PRs and knowledge sharing happen much faster in person.
- Add a dedicated comms platform engineer to our standups. Notify the need for more support early as peer reviews increase closer to the migration deadline
- Escalate to managers on prioritization if domain teams can’t provide the necessary support
Whats next?
Gusto embedded will continue surfacing new notifications as other Gusto teams continue to add their own notifications. We have also built a new notification testing framework for partners to test firing out and resolving notifications via developer portal. Some other features for the future include expanding our framework to feature surfacing one off notifications and building out a partner inbox flow to save partners on frontend development. We hope to continue building out more communications to continue expanding our product, but also find ways to speed partner development time to relive the partner pain point of needing deep understanding of domain context to resolve each notification.
