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_token_type_to_api_tokenMigration to add token types to API tokens
rails generate cm_admin:add_unique_index_to_permissionsMigration to prevent duplicate permissions
rails generate cm_admin:file_export_improvementMigration to upgrade file export functionality

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/zcm_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 zcm_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 zcm_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.

Migration Generators (Upgrades)​

11. 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.

12. 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.

13. 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.

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:install_role - For role-based permissions
  4. 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 zcm_admin.rb.