How to add new notifier to Databasus

This guide will walk you through the process of contributing a new notification integration to Databasus. You'll learn how to implement the backend logic, create database migrations and build the frontend UI components.

Backend implementation

The backend implementation involves creating models, updating enums and setting up database migrations.

1. Create new notifier model

Create a new model in backend/internal/features/notifiers/models/{notifier_name}/ folder. Your model must implement the NotificationSender interface from the parent folder.

The interface requires the following methods:

• Send(encryptor encryption.FieldEncryptor, logger *slog.Logger, heading string, message string) error - sends the notification
• Validate(encryptor encryption.FieldEncryptor) error - validates the configuration
• HideSensitiveData() - masks sensitive fields before logging/display
• EncryptSensitiveData(encryptor encryption.FieldEncryptor) error - encrypts sensitive fields before saving

2. Add notifier type to enums

Add your new notifier type to backend/internal/features/notifiers/enums.go in the NotifierType constants section. This enum is used throughout the application to identify different notifier types.

3. Update the main Notifier model

Modify backend/internal/features/notifiers/model.go to integrate your new notifier:

• Add a new field with GORM foreign key relation to your notifier model
• Update the getSpecificNotifier() method to handle your new type
• Update the Send() method to route notifications to your implementation

4. Add environment variables (if needed)

If your notifier requires environment variables for testing, add them to backend/internal/config/config.go. This allows the test suite to access necessary configuration values.

5. Configure Docker containers (if needed)

If your notifier needs external services for testing, add them to backend/docker-compose.yml.example. Keep sensitive data blank in the example file.

6. Add CI/CD secrets (if needed)

For sensitive environment variables needed in the GitHub Actions pipeline (like API keys or credentials), contact @rostislav_dugin to add them securely to the CI/CD environment.

7. Create database migration

Create a new migration file in the backend/migrations folder:

• Create a table with notifier_id as UUID primary key
• Add a foreign key constraint to the notifiers table with CASCADE DELETE
• Include all necessary columns for your notifier configuration
• Look at existing notifier migrations (e.g., Slack, Teams) for reference

8. Update and run tests

Update backend/internal/features/notifiers/controller_test.go to add encryption verification tests for your notifier:

• Add a test case to Test_NotifierSensitiveDataLifecycle_AllTypes for your notifier type
• Add a test case to Test_CreateNotifier_AllSensitiveFieldsEncryptedInDB
• Verify that sensitive fields are encrypted with enc: prefix in the database
• Verify that decryption returns the original plaintext values
• Verify that sensitive data is hidden when retrieved via API

Before submitting your pull request, make sure all existing tests pass and your new encryption tests are working correctly.

Frontend implementation

The frontend work involves creating TypeScript models, validators and React components for managing your notifier.

1. Add TypeScript models and validators

Create your notifier model and validator in frontend/src/entity/notifiers/models/{notifier_name}/. Update the index.ts file to export your new model for use throughout the application.

2. Upload icon and update utilities

Complete the following steps to add visual assets:

1. Upload an SVG icon to public/icons/notifiers/
2. Update src/entity/notifiers/models/getNotifierLogoFromType.ts to return your icon path
3. Update src/entity/notifiers/models/NotifierType.ts to include your new notifier type constant
4. Update src/entity/notifiers/models/getNotifierNameFromType.ts to return the display name for your notifier

3. Build UI components

Create two main React components:

• src/features/notifiers/ui/edit/notifiers/Edit{NotifierName}Component.tsx - for creating and editing notifier configuration
• src/features/notifiers/ui/show/notifier/Show{NotifierName}Component.tsx - for displaying notifier details in read-only mode

These components should handle form inputs, validation and data formatting specific to your notifier.

4. Integrate with main components

Update the main notifier management components to handle your new type:

• EditNotifierComponent.tsx - add import, validation function and component rendering for your notifier
• ShowNotifierComponent.tsx - add import and component rendering to display your notifier

These updates enable the application to dynamically render the correct component based on the notifier type selected.

5. Test the implementation

Thoroughly test your implementation to ensure everything works as expected:

• Create a new notifier of your type
• Edit existing notifier configurations
• Send test notifications
• Verify validation works correctly
• Check that sensitive data is properly masked
• Test the delete functionality

Submission guidelines

When you're ready to contribute your work:

1. Fork the Databasus repository
2. Create a feature branch with a descriptive name
3. Commit your changes with clear commit messages
4. Ensure all tests pass
5. Submit a pull request with a description of your changes