Skip to main content

CM Admin Generators

CM Admin provides a set of Rails generators to help you quickly set up and extend your admin panel functionality.

Overview​

Generators automate the setup process by creating necessary migrations, configurations, and boilerplate code. They save time and ensure consistency across projects.

Quick Reference​

CommandDescription
rails generate cm_admin:installInitial setup - creates migrations, initializer, and mounts the engine
rails generate cm_admin:install_roleSets up role-based access control with permissions
rails generate cm_admin:add_authenticationAdds Devise authentication if no auth system exists
rails generate cm_admin:add_graphqlInstalls GraphQL API with types, mutations, and queries
rails generate cm_admin:add_schedulerCreates cron job and job log tables for scheduled tasks
rails generate cm_admin:add_comments_with_mentionsAdds commenting system with @mentions support
rails generate cm_admin:add_cm_support_ticketSets up support ticket system for customer requests
rails generate cm_admin:add_cm_platform_settingCreates platform settings table for app configuration
rails generate cm_admin:add_cm_index_preferenceAdds user-customizable column preferences for lists
rails generate cm_admin:add_cron_job_notificationsCreates notification system for cron job alerts
rails generate cm_admin:add_prompts_with_constantsAdds Lexxy rich text templates with category support
rails generate cm_admin:add_token_type_to_api_tokenMigration to add token types to API tokens
rails generate cm_admin:add_name_to_api_tokenMigration to add a name field to API tokens
rails generate cm_admin:add_unique_index_to_permissionsMigration to prevent duplicate permissions
rails generate cm_admin:file_import_improvementMigration to add tracking columns to file imports
rails generate cm_admin:file_export_improvementMigration to upgrade file export functionality
rails generate cm_admin:add_audit_metadata_to_versionsAdds action_type and action_name columns to PaperTrail versions
rails generate cm_admin:add_otp_requestsCreates otp_requests table for OTP-based authentication
rails generate cm_admin:add_email_logsCreates the cm_email_logs table for recording CmAdmin.send_email deliveries
rails generate cm_admin:rename_file_import_and_export_tablesRename file_imports and file_exports tables
rails generate cm_admin:add_webhook_eventsCreates the cm_webhook_events table for webhook logging
rails generate cm_admin:add_webhook_event_recipientAdds recipient link and original_link columns to cm_webhook_events
rails generate cm_admin:ct_page_viewCreates ct_page_views table for Saved Views (replaces index preferences)
rails generate cm_admin:add_bot_conversationsCreates the tables for the Catalyst AI (CT Bot) chat feature
rails generate cm_admin:add_bot_transcriptionsCreates the ct_bot_transcriptions table for Catalyst AI voice input

Core Generators​

1. Install Generator​

Command:

rails generate cm_admin:install

What it does:

  • Installs Action Text for rich text editing
  • Creates the CM Admin initializer (config/initializers/cm_admin.rb)
  • Sets up custom JavaScript and CSS files
  • Creates the application policy for authorization
  • Mounts the CM Admin engine in routes
  • Creates migrations for FileImport, CmIndexPreferences, and FileExports
  • Installs i18n ActiveRecord for translations
  • Runs database migrations

Why you need it: This is the essential first step when setting up CM Admin. It creates the foundation that all other features depend on.

2. Install Role Generator​

Command:

rails generate cm_admin:install_role

What it does:

  • Creates migration for CmRole (roles table)
  • Creates migration for CmPermission (permissions table)
  • Creates a default "Admin" role
  • Automatically assigns all available permissions to the Admin role for all configured models

Why you need it: Enable role-based access control (RBAC) in your admin panel. This allows you to define different user roles with specific permissions.

3. Add Authentication Generator​

Command:

rails generate cm_admin:add_authentication

What it does:

  • Adds Devise gem to your Gemfile
  • Installs and configures Devise
  • Prompts for the user model name (defaults to "user")
  • Creates the user model with Devise
  • Sets up application controller with authentication
  • Creates authentication concern
  • Creates Current model for thread-safe context
  • Adds super_admin? method to the user model

Why you need it: Use this when your application doesn't have an authentication system yet. It quickly sets up Devise-based authentication with CM Admin integration.

Feature Generators​

4. Add GraphQL Generator​

Command:

rails generate cm_admin:add_graphql

What it does:

  • Adds GraphQL-related gems (graphql, graphql-errors, graphql-rails_logger)
  • Installs GraphQL Rails
  • Creates GraphQL schema
  • Sets up type directories (inputs, enums, objects)
  • Creates base mutation and query classes
  • Sets up model concerns
  • Creates exception handling

Why you need it: Enable GraphQL API for your application. Useful when you need a flexible API for external integrations or modern frontend frameworks.

5. Add Scheduler Generator​

Command:

rails generate cm_admin:add_scheduler

What it does:

  • Creates migration for CmCronJob (scheduled jobs)
  • Creates migration for CmCronJobLog (job execution logs)

Next steps:

  • Add CmCronJob, CmCronJobLog to config.included_models in cm_admin.rb
  • Run rails db:migrate
  • Start Sidekiq for background job processing

Why you need it: Add cron job management to your admin panel. Schedule and monitor recurring background jobs directly from the admin interface.

6. Add Comments with Mentions Generator​

Command:

rails generate cm_admin:add_comments_with_mentions

What it does:

  • Creates migration for CmComment (comments table)
  • Creates migration for CmUserMentions (user mentions in comments)

Next steps:

  • Run rails db:migrate

Why you need it: Enable commenting with @mentions functionality. Users can comment on records and tag other users with @mentions for notifications.

7. Add CM Support Ticket Generator​

Command:

rails generate cm_admin:add_cm_support_ticket

What it does:

  • Creates migration for CmSupportTicket
  • Creates migration for CmSupportTicketEmployee (ticket assignments)
  • Creates migration adding created_by to CmComment

Next steps:

  • Add CmSupportTicket to config.included_models in cm_admin.rb
  • Run rails db:migrate

Why you need it: Set up a support ticket system within your admin panel. Manage customer support requests and assign them to team members.

8. Add CM Platform Setting Generator​

Command:

rails generate cm_admin:add_cm_platform_setting

What it does:

  • Creates migration for CmPlatformSetting (platform-wide settings)

Next steps:

  • Run rails db:migrate

Why you need it: Add platform settings management to your admin panel. Store and manage application-wide configuration values.

9. Add CM Index Preference Generator​

Command:

rails generate cm_admin:add_cm_index_preference

What it does:

  • Creates migration for CmIndexPreferences (user column preferences)
  • Creates constants initializer

Next steps:

  • Run rails db:migrate

Why you need it: Allow users to customize which columns appear in list views. Each user can save their preferred column visibility and order.

10. Add Cron Job Notifications Generator​

Command:

rails generate cm_admin:add_cron_job_notifications

What it does:

  • Creates migration for CmNotifiable (notification system)

Next steps:

  • Run rails db:migrate
  • Add to your models: 
    has_many :notifiables, as: :notifiable, dependent: :destroy
    accepts_nested_attributes_for :notifiables, allow_destroy: true

Why you need it: Enable unified notification system for cron jobs. Send email and webhook notifications when scheduled jobs complete or fail.

11. Add Prompts with Constants Generator​

Command:

rails generate cm_admin:add_prompts_with_constants

What it does:

  • Creates migration for CmPrompt (rich text templates)
  • Creates migration for ConstantMap (polymorphic associations)
  • Adds Lexxy template platform setting
  • Enables AI-powered slash commands in rich text editors

Next steps:

  • Add CmPrompt to config.included_models in cm_admin.rb
  • Run rails db:migrate
  • Ensure Lexxy gem is installed (~> 0.8)

Why you need it: Add AI-powered rich text templates to your admin panel. Users can create reusable prompt templates with category-based filtering and access them via slash commands (/) in any rich text field.

Migration Generators (Upgrades)​

12. Add Token Type to API Token Generator​

Command:

rails generate cm_admin:add_token_type_to_api_token

What it does:

  • Creates migration to add token_type column to API tokens

Why you need it: Upgrade existing installations to support different token types (e.g., read-only, read-write) for API authentication.

13. Add Unique Index to Permissions Generator​

Command:

rails generate cm_admin:add_unique_index_to_permissions

What it does:

  • Creates migration to add unique index on cm_permissions table

Why you need it: Database integrity upgrade to prevent duplicate permission entries.

14. File Import Improvement Generator​

Command:

rails generate cm_admin:file_import_improvement

What it does:

  • Creates migration to add action_name, importer_class_name, import_type, and associated_model_id columns to the file_imports table

Next steps:

  • Run rails db:migrate

Why you need it: Upgrade existing installations to store import metadata directly on the file import record. This enables the job processor to work without relying on runtime model lookups and provides better traceability in the file imports index and show views.

15. File Export Improvement Generator​

Command:

rails generate cm_admin:file_export_improvement

What it does:

  • Creates migration to improve file export functionality
  • Runs the migration automatically

Why you need it: Upgrade existing installations to the improved file export system with better performance and features.

16. Add Audit Metadata to Versions Generator​

Command:

rails generate cm_admin:add_audit_metadata_to_versions

What it does:

  • Creates a migration to add action_type and action_name columns to the PaperTrail versions table
  • Adds indexes on both columns for fast audit filtering
  • Checks that the versions table exists before generating the migration
  • Only adds columns that are not already present

Next steps:

  • Run rails db:migrate

Why you need it:

Upgrade existing installations to record queryable audit metadata on every PaperTrail version. cm-admin uses these columns to store which admin action (CRUD, custom action, or bulk action) triggered a change. Required for the auditing feature described in Auditing.

17. Add OTP Requests Generator​

Command:

rails generate cm_admin:add_otp_requests

What it does:

  • Creates migration for otp_requests table with columns: otp, email (citext), expired_at, status, verified_at, user_id (optional foreign key), and timestamps
  • Adds an index on the email column
  • Prints post-install instructions reminding you to add has_many :otp_requests and include OtpAuthenticatable to your User model

Next steps:

  • Run rails db:migrate
  • Add to your User model: 
    has_many :otp_requests, dependent: :destroy
    include OtpAuthenticatable
  • Enable in cm_admin.rb: 
    config.use_catalyst_otp = true
    config.auth_method = :otp  # or :password, :custom

Why you need it:

Set up OTP-based authentication in your admin panel. The otp_requests table stores one-time codes with expiry and status tracking. Supports both user-associated OTPs and email-only OTPs (for signup flows without a user record). See OtpAndAuth for the full setup guide.

17. CT Page View Generator​

Command:

rails generate cm_admin:ct_page_view

What it does:

  • Enables the PostgreSQL citext extension if needed
  • Drops the legacy cm_index_preferences table if it exists (data is not migrated)
  • Creates the ct_page_views table with:
    • owner as a required polymorphic reference
    • name (citext, required)
    • ar_model_name, associated_ar_model_name, visible_columns, hidden_columns, records_per_page
    • is_default, plus a partial unique index allowing one default view per owner / model
    • view_type (integer enum: table, card, kanban)
    • filter_params (jsonb) and sort_params (json), both defaulting to {}

Next steps:

  • Run rails db:migrate

Why you need it:

Powers Saved Views: per-user saved filters (including Advanced Filters), sort, columns, page size, and view type. Replaces Index Preference.

18. Add Email Logs Generator​

Command:

rails generate cm_admin:add_email_logs

What it does:

  • Creates the cm_email_logs table used to record every CmAdmin.send_email delivery when config.enable_email_logging is true.

Next steps:

  • Run rails db:migrate

Why you need it:

Enable email delivery logging for your admin panel. This stores delivery status, recipients, failure reasons, and record associations, which is useful for auditing and debugging outgoing emails. See CmAdminEmail for the full email sending API.

19. Rename File Import and Export Tables Generator​

Command:

rails generate cm_admin:rename_file_import_and_export_tables

What it does:

  • Creates a reversible migration that renames file_imports to ct_file_imports and file_exports to ct_file_exports
  • Updates persisted model names from FileImport and FileExport to CtFileImport and CtFileExport in Active Storage, PaperTrail, permissions, and index preferences

Next steps:

  • Run rails db:migrate
  • Replace application references to FileImport and FileExport with CtFileImport and CtFileExport

Why you need it:

Use this generator when upgrading an existing installation to the CtFileImport and CtFileExport model names.

20. Add Webhook Events Generator​

Command:

rails generate cm_admin:add_webhook_events

What it does:

  • Creates the cm_webhook_events table used to log incoming webhook events when config.enable_webhook_processing is true
  • Adds columns for cm_service (gem-managed service enum, e.g. postmark), host_service (host-app service enum), event_type, status, event_id, uuid (auto-assigned via SecureRandom, unique index), error_message, processed_at, and a polymorphic eventable association
  • Adds indexes on status, both services, event type, event ID, UUID (unique), created date, the eventable association, and composite service + event ID + event type lookups

Next steps:

  • Run rails db:migrate
  • Ensure ActiveStorage is installed and configured (rails active_storage:install) — webhook payloads are stored as raw_payload attachments

Why you need it:

Enable webhook logging for your admin panel. Incoming webhooks are persisted with their payload, status, and error information, and processed asynchronously via ProcessWebhookEventJob. See CmAdminWebhooks for the full webhook setup guide.

21. Add Webhook Event Recipient Generator​

Command:

rails generate cm_admin:add_webhook_event_recipient

What it does:

  • Adds a polymorphic recipient association (recipient_type/recipient_id + index) to cm_webhook_events — links each event to the recipient it belongs to, populated at webhook receipt by matching the payload's recipient email against the log's record
  • Adds an original_link column — for Click events, the clicked URL, denormalized at receipt so clicks can be grouped and counted in SQL

Next steps:

  • Run rails db:migrate

Why you need it:

For installations that already ran add_webhook_events. Per-recipient open/click tracking (recipient columns, Click Details, Events tab, campaign engagement metrics) depends on these columns. The migration is idempotent — it skips columns that already exist, so it is safe to run more than once.

22. Add Description to API Token Generator​

Command:

rails generate cm_admin:add_name_to_api_token

What it does:

  • Creates a migration to add a name string column to the api_tokens table
  • Backfills existing records with 'Unnamed Token' so every token is identifiable
  • Drops the legacy description column if it exists (added by v8.2.14's add_description_to_api_token)

Next steps:

  • Run rails db:migrate

Why you need it:

Upgrade existing installations to give every API token a mandatory, human-readable name (max 100 characters), making it easier to identify what each token is used for and to search tokens by name.

22. Add Bot Conversations Generator​

Command:

rails generate cm_admin:add_bot_conversations

What it does:

  • Creates migration for ct_bot_conversations (chat conversations per user)
  • Creates migration for ct_bot_messages (user/assistant messages with rich text content and file attachments)
  • Creates migration for ct_bot_artifacts (interactive elements such as clarifying-question cards)
  • Creates migration for ct_cost_trackings (per-request token usage and cost)
  • Creates migration adding is_catalyst_ai_enabled to cm_roles (per-role opt-in flag)

Next steps:

  • Add CtBotConversation, CtBotMessage, CtCostTracking to config.included_models in zcm_admin.rb
  • Run rails db:migrate
  • Add your OpenRouter key to credentials: catalyst_ai.openrouter_api_key
  • Ensure config/cable.yml exists (Redis adapter recommended in production) — replies stream over ActionCable
  • Declare mcp_actions on the models the assistant may query
  • Enable Catalyst AI on each CmRole that should see the widget

Why you need it:

Sets up Catalyst AI (CT Bot) — an in-app chat widget that answers admin users' questions using your MCP-enabled models. See Catalyst AI for the full feature guide.

24. Add Bot Transcriptions Generator​

Command:

rails generate cm_admin:add_bot_transcriptions

What it does:

  • Creates migration for ct_bot_transcriptions (voice recordings with their transcribed text, status and cost, optionally linked to a conversation and message)

Next steps:

  • Add CtBotTranscription to config.included_models in zcm_admin.rb
  • Run rails db:migrate

Why you need it:

Enables voice input in the Catalyst AI chat widget (added in v8.4.1). Run it after add_bot_conversations — on existing Catalyst AI installs and fresh installs alike. See the v8.4.1 upgrade guide.

For new projects, run generators in this order:

  1. rails generate cm_admin:install - Foundation setup
  2. rails generate cm_admin:add_authentication - If no auth exists
  3. rails generate cm_admin:add_otp_requests - For OTP-based auth
  4. rails generate cm_admin:install_role - For role-based permissions
  5. rails generate cm_admin:file_import_improvement - Add tracking columns to file imports
  6. Feature generators as needed (scheduler, comments, support tickets, etc.)

Troubleshooting​

Missing models: After running feature generators, remember to add the new models to config.included_models in cm_admin.rb.