Skip to main content

Generators

cm-admin ships Rails generators that create the migrations, initializers and boilerplate each feature needs. Run rails generate cm_admin:install first, then add feature generators as you need them.

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:install_user_groupsCreates User Groups tables and seeds the Enable User Groups setting
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:remove_status_from_api_tokenDrops api_tokens.status; expiry is derived from expires_at
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
rails generate cm_admin:add_ruby_llm_persistenceUpgrades an existing Catalyst AI install to RubyLLM persistence tables
rails generate cm_admin:add_trackable_columnsAdds created_by_id / updated_by_id to models that include Trackable
rails generate cm_admin:cm_cron_improvementsAdds notification_emails to cm_cron_jobs
rails generate cm_admin:form_draftCreates the ct_form_drafts table used by progressive forms

Copying All Pending Migrations​

Instead of running each generator by hand, you can copy every cm-admin migration your app is missing in one command:

rails cm_admin:install_migrations

This detects the same pending migrations the development boot warning lists ("The following cm-admin migrations may not be applied") and generates them into db/migrate β€” it does not run db:migrate, so you can review the files and apply them yourself. Migrations the app already has a file for are not reported as pending, templates superseded by a later migration (like create_cm_index_preferences, whose table ct_page_view drops) are left out, and templates that need generator-specific input are skipped with a hint to run their generator instead.


Core Generators​

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 the ct_file_imports, ct_file_exports and cm_index_preferences tables
  • 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.


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.


Install User Groups Generator​

Command:

rails generate cm_admin:install_user_groups

What it does:

  • Creates migrations for ct_user_groups and the cm_roles_ct_user_groups join table
  • Runs the migrations
  • Seeds the default platform settings, including Enable User Groups (CmPlatformSetting.add_cm_default_settings)

Why you need it:

Group users and assign roles to groups. Requires install_role and add_cm_platform_setting first.


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​

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.


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.


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.


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.


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.


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.


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.


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)​

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.


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.


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.


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.


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.


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.

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.


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.


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.


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.


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.


Add Name 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.


Add Bot Conversations Generator​

Command:

rails generate cm_admin:add_bot_conversations

What it does:

  • Creates migration for the ruby_llm_* persistence tables (ruby_llm_models, ruby_llm_tool_calls, ruby_llm_mcp_credentials, ruby_llm_usages, ruby_llm_queued_messages, ruby_llm_chat_files, ruby_llm_batches, ruby_llm_provider_files) that acts_as_chat / acts_as_message use to store chats, tool calls, usage and queued messages
  • Creates migration for ct_bot_conversations (chat conversations per user, linked to a ruby_llm_models row, with the run-claim columns cancelled, claim_token and claimed_until)
  • Creates migration for ct_bot_messages (messages with rich text content and attachments, a string role β€” user/assistant/system/tool β€” and assistant metadata columns such as thinking text, citations and finish reason)
  • Creates migration for ct_bot_artifacts (interactive elements such as clarifying-question and confirmation cards)
  • Creates migration adding is_catalyst_ai_enabled to cm_roles (per-role opt-in flag)

Next steps:

  • Add CtBotConversation, CtBotMessage, RubyLlmUsage to config.included_models in zcm_admin.rb
  • Upgrading an existing Catalyst AI install? Don't rerun this generator β€” run cm_admin:add_ruby_llm_persistence instead (below)
  • 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.


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.


Remove Status from API Token Generator​

Command:

rails generate cm_admin:remove_status_from_api_token

What it does:

  • Stamps expires_at with the current time on tokens stored as expired that would otherwise still be valid by date, so none are re-enabled
  • Drops the status column from api_tokens
  • The down migration re-adds status and marks tokens whose expires_at has passed as expired

Next steps:

  • Replace enum :status, %i[live expired] in your ApiToken model with the derived scopes and methods (the cm-admin API Tokens pages call status and live?):
scope :live, -> { where(expires_at: [nil, Time.current..]) }
scope :expired, -> { where(expires_at: ...Time.current) }

def live?
expires_at.nil? || expires_at.future?
end

def expired?
!live?
end

def status
live? ? "live" : "expired"
end
  • Run rails db:migrate

Why you need it:

Whether an API token is live is now derived only from expires_at. ApiToken#status, #live?, #expired? and the live / expired scopes are computed from it.


Add Ruby LLM Persistence Generator​

Command:

rails generate cm_admin:add_ruby_llm_persistence

What it does:

  • Creates the create_ruby_llm_records migration for the ruby_llm_* persistence tables
  • Creates the add_ruby_llm_persistence_to_ct_bot migration, which renames message files attachments to attachments and links existing conversations to the default bot model in ruby_llm_models

Next steps:

  • Run rails db:migrate

Why you need it:

Upgrade existing Catalyst AI installations that ran add_bot_conversations before RubyLLM persistence was added. Fresh installs get these tables from add_bot_conversations and don't need it. See Catalyst AI.


Add Trackable Columns Generator​

Command:

rails generate cm_admin:add_trackable_columns

What it does:

  • Eager-loads the app and finds every model that includes Trackable but is missing created_by_id or updated_by_id
  • Creates one migration (add_trackable_columns_to_models, or _v2, _v3… if one already exists) that adds the missing columns

Next steps:

  • Run rails db:migrate

Why you need it:

Records which user created and last updated each record. See Trackable.


CM Cron Improvements Generator​

Command:

rails generate cm_admin:cm_cron_improvements

What it does:

  • Creates a migration that adds notification_emails to cm_cron_jobs
  • Runs the migration automatically

Why you need it:

Upgrade existing installations so each cron job can list the emails notified about its runs. See Cron Jobs.


Form Draft Generator​

Command:

rails generate cm_admin:form_draft

What it does:

  • Creates the create_ct_form_drafts migration

Next steps:

  • Run rails db:migrate

Why you need it:

Progressive (multi-step) forms store each step's values in ct_form_drafts. See Progressive Forms.


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.