Migrating your in-house Notification System

This guide outlines the migration strategy for integrating SuprSend into your existing notification system. If you are setting up notifications from scratch, refer to the Quick Start Guide instead.

If you are looking for technical support, reach out to [email protected] and one of our solutions architect will design the entire migration plan befitting to your current notification architecture and business requirement.

General Migration Approach

There are three primary migration strategies for syncing your existing users and events:

• Do one time migration of all users and setup event stream, then configure notifications on a per-use case basis.
• Implement workflow API and identify recipients inline to gradually sync users in SuprSend.
• Third-Party CDP Integration: If you already track data in a CDP (e.g., Segment), you can integrate it directly with SuprSend and go live without needing to set up any additional data sync in your codebase.

If you have an event-stream-based system or cannot identify users within workflow triggers (e.g., sending to a group via an object), do one time migration of users since both cases need pre-creation of users for successful workflow trigger.

For rest of the cases, you can go with either approaches. However, we recommend doing Bulk user migration unless you have some PII restrictions on sharing user data. User migration doesn't take more than 2 days of additional effort.

General guidelines around notification architecture setup

Migrating backend systems

• Call SuprSend APIs from a central place for easy tracking and maintenance: Your backend systems can communicate with SuprSend using a microservice or monolith to centralize all your communication triggers at a central place.
  If you don't have these services in place, you can also call SuprSend APIs directly within the code. In this case, you should have a single function that calls SuprSend service and the same function is referred at the required places in the codebase.
  
  
• Introduce Messaging Queue for high notification volume: If you have a respectable notification volume, introducing a messaging queue in between reduces reliability on the uptime of your internal systems and saves potential notification loss due to downtime of your backend machine or server.
  
  
• Implement retry mechanism for failure response: It's a good practice to implement retry logic if SuprSend APIs doesn't return a 20x response.
  
  
• Sync existing data and assets - There are 3 types of data entities in SuprSend - User Data (user, preferences), its modelling (Objects, tenants) and assets (template, workflow).
  • First, sync your users and their preferences. Do one time migration of existing data and setup integration to auto create new users on every profile change. Release it first so that data starts flowing into SuprSend.
    Skip this step if you are going with inline user identification in workflow API.
  • Setup additional data modelling for objects and tenants alongside user sync.
  • Asset migration (templates and workflows) can be done on per-usecase basis. You can design these directly on SuprSend console or use APIs (currently in beta).
    
    
• Setup notification trigger. Integrate direct workflow API or directly pass user triggered events if you have an existing event stream. You can compare both approaches and see which one fits your usecase better here. Most companies opt for a hybrid approach—passing events for user-initiated actions while using APIs for system-generated alerts.

Migrating frontend applications

Frontend implementation can be planned in parallel but it should be released after your backend migration.

• Migrating frontend components (Inbox or Preferences): It's a good practice to hide the frontend component behind a feature flag, allowing you to run it in parallel with your existing system. This enables a smooth transition, where you can switch off the current implementation and activate the new component as soon as the backend migration is complete.
  
  
• Migrating mobile push notifications: Requires an app release with SuprSend SDK integration. SuprSend SDK automatically registers user tokens on app launch, eliminating the need for manual push token migration. Since users will take time to upgrade, you can maintain dual routing—sending notifications via both your existing vendor integration (e.g., FCM, APNS, OneSignal) and SuprSend until near 100% users upgrade to the new app.
  During this transition, both SDKs will receive notifications, but only the notification from the existing vendor integration will be displayed. Once the majority of users have migrated, disable routing through the existing vendor, allowing SuprSend SDK to take control.

Key Migration Steps

1. User data (Mandatory for Event-Based Triggers):
   User data migration is required for event-driven workflows, as recipient profiles must exist beforehand for successful event triggers. If you are identifying recipients inline within workflow triggers or using a CDP connection, you can skip this step.
   
   
   1. Setup user sync:
      • Users can be updated via backend SDK, frontend SDK, or direct API calls.
      • If integrating with the frontend SDK for push or in-app notifications, users will be identified in the frontend application to authenticate them with their respective channel token. In such cases, you can call other profile updates (set out-of app channels (email, sms) or profile properties) through the frontend SDK as well.
        
   2. Migration Process:
      • First set up and release continuous integration to auto-populate user profiles as they are identified/modified in your database.
      • Perform a one-time bulk migration of existing users. Since, profile updates are upsert functions, syncing the same profile again will not create duplicate users.
        
   3. Required Data:
      At a minimum, each user profile must include a unique, immutable identifier and channel details (e.g., email, phone number) for communication. Additional profile attributes, such as language and timezone, can be progressively synced alongside notification triggers.

2. Modelling Additional Data Entities
   In addition to users, your system may have other entities that require notification modelling from the start. If your system only requires direct user notifications and you always know the recipient in your trigger, you can just migrate users and you are good to go. For other cases, SuprSend supports two key concepts for user modelling:

• Tenants: Use when,
  • You are a SAAS platform where customer notification preferences can be controlled by your org or end customer admin.
  • Sending notifications on behalf of customers and need to white label notification or route via customer's vendor credentials (their email address)
    
    
• Objects: Use when,
  • You need to notify a group of users without having to identify individual recipients in the trigger. For example, send notification to all followers or subscribers when a new content is posted on a channel or send an alert to associated users of a task on status change.
  • You need to send notification to non-user entities like company slack channel, email group or shared inbox feed. Eg. Send incident report or anomaly alerts on a company's Slack channel.
    
    

3. Templates

• If your templates are stored in your database, they can be migrated using template APIs (currently in beta, contact support for migration assistance). We use handlebars as the templating language. So, if you have your variables in a different language, convert it into handlebars before syncing.
  
• If templates are part of your final trigger, you can create a template with all fields set as variable and pass the corresponding content dynamically in the trigger. However, to fully leverage the platform, we recommend a one-time bulk migration of templates. This will reduce engineering overhead as it the templates will be decoupled from the code and product / design team can manage template updates independently without engineering involvement.
  
• For email templates, we recommend using our visual editor to design template directly on SuprSend console. While the initial setup may take some time, it significantly simplifies future template iterations. It also enables non-engineering teams to update templates independently, reducing dependency on developers.

4. Workflows
   Workflows contain notification logic, such as scheduling reminders (e.g., cron jobs) or determining when to trigger specific notifications based on conditions. Currently, this logic would be residing in your code and you would be calling vendor APIs to send the final notification.
   
   We recommend building these logics on SuprSend. This decouples logic from your code and and all you have to do is simply trigger workflow, simplifying future iterations and reducing engineering overhead. Workflows can currently be designed on SuprSend console. We'll soon be exposing APIs for the same.
   
   To streamline migration, start by migrating 3-4 key notification use cases in the first release. Gradually expand to cover all notification scenarios over time.

5. In-app Inbox

• Design Implementation: You can integrate with the relevant SDK and replicate your existing Inbox UI using customizable react components or a headless library. SuprSend's Inbox SDK gives you the flexibility to design any UI you want.
  
• Feature Flagging: After achieving the design parity and implementing the Inbox integration, hide the new Inbox behind a feature flag and run it in parallel with your current implementation.
  
• Releasing without downtime: As soon as your backend is released, remove the feature flag, switch off the current implementation and show SuprSend Inbox component. The notifications sent during parallel run of current and new SDK will be visible in SuprSend Inbox when switched.

6. Migrate User Preferences

• Use Preference API for a one-time migration and capture future preferences through SuprSend’s hosted preference page or embeddable UI.
• If you have an existing preference centre in your application, you can continue to use that. Just pass the updates via API back to SuprSend. Some companies also pass this data along with workflow trigger but we generally recommend syncing preferences in SuprSend, so you don't need to compute this everytime on trigger.
• If preferences are managed directly by vendors (e.g., email opt-outs via suppression lists), SuprSend will automatically track these and mark the emails as inactive for a given period, generally 30 days, to ensure that we don't keep making vendor calls in case of hard bounce.
  
  In this case, You can avoid adding SuprSend preference centre in the first integration, but we recommend adding it later. Vendor unsubscription page doesn't give granular preference control to users and leads to user resorting to channel-level unsubscriptions.

After data migration and setup, next is setup your workflow trigger. There are 2 ways to setup workflow triggers. You can compare them here and see which is the most suitable for you.

Rollout Plan

Now, that you've understood how the migration will happen, you don't need to setup everything in the first phase and plan your release in multiple phases. Here are some of the phases and the timeline for the migration tasks in each phase. You can rollout all notifications in phase 1 or divide your migration in 2 phases, migrate 3-4 usecases at the start and then migrate rest of the usecases in phase 2.