Skip to main content

Architecture

SimplePerm internals, for developers and security reviewers.

Package Overview​

SimplePerm is a first-generation managed package for Salesforce.

  • Namespace: simpleperm
  • API Version: 62.0
  • Apex Classes: 25+ (excluding test classes)
  • LWC Components: 20
  • Custom Objects: 4 (Migration_Project__c, Migration_Log__c, SimplePermConfig__c, Migration_Event__e)

The package runs entirely within the customer's Salesforce org. No external services, no Heroku backend, no third-party integrations.

Migration Pipeline​

The migration pipeline has five stages: read profile metadata, parse it, build a permission set definition, deploy it, assign it to users.

Each stage has one job:

ClassResponsibility
MetadataRetrieverReads profile metadata via SOQL (object permissions, field permissions, system permissions, tab settings) and SOAP Metadata API (app visibilities, access types).
ProfileParserConverts the raw metadata maps from MetadataRetriever into strongly-typed ParsedProfile wrapper objects.
PermissionSetBuilderTransforms a ParsedProfile into a deployable PermissionSetMetadata definition. Sanitizes API names and filters out disabled entries.
MetadataDeployerDeploys permission sets via the SOAP Metadata API createMetadata() call. Batches at 10 items per call to stay within API limits.
PermissionSetAssignerAssigns newly created permission sets to users on the source profile. Prevents duplicate assignments.

MigrationOrchestrator coordinates the full pipeline from retrieval through assignment and aggregates errors across stages.

Two-Phase Execution​

Salesforce prohibits HTTP callouts after DML in the same transaction. SimplePerm splits execution into two phases to work within this constraint.

  • Phase 1 (Callout Phase): SOQL queries and HTTP callouts only. Reads profile metadata, parses it, builds permission set definitions, deploys via SOAP Metadata API, verifies results. No DML.
  • Phase 2 (DML Phase): insert and update operations only. Updates Migration Project records, flushes Migration Log records to the database, creates permission set assignments. No callouts.

Log entries accumulate in memory as LogEntry objects during Phase 1, then get written to Migration_Log__c in bulk during Phase 2.

Data Model​

Four custom objects handle tracking and configuration.

  • Migration_Project__c -- One record per migration run. Tracks status (Queued, Running, Success, Partial Success, Failed), source profile name, timestamps, and error messages.
  • Migration_Log__c -- Master-detail child of Migration_Project__c. Captures step name, log level (Info/Warning/Error), and message for each pipeline step.
  • SimplePermConfig__c -- List Custom Setting storing the API version for SOAP Metadata API calls. Seeded by PostInstallScript on fresh installs.
  • Migration_Event__e -- Platform event for real-time progress notifications from the Queueable job to the LWC wizard.

Controller Layer​

Two Apex controllers expose backend functionality to LWC:

  • MigrationController -- @AuraEnabled methods for the Migration Wizard: list profiles, generate previews, check conflicts, enqueue migrations, poll status, retrieve history, trigger user assignments. Service-layer exceptions are caught and re-thrown as AuraHandledException.
  • ProfileViewerController -- Read-only @AuraEnabled methods for the Permission Viewer: browse profiles, load detailed permissions, compare profiles against permission sets, supply CSV export data.

LWC Architecture​

The 20 Lightning Web Components fall into three groups:

Migration Wizard -- A LightningModal with 8 step components:

  1. Select Profiles (multi-select datatable)
  2. Configure Permission Types (13-type checkbox grid)
  3. Preview Migration (permission breakdown with section toggles)
  4. Handle Conflicts (rename/overwrite/skip options)
  5. Migration In Progress (stage-based progress tracker)
  6. Migration Results (per-profile success/failure summary)
  7. Assign Users (optional user-to-permission-set assignment)
  8. Done (completion summary with navigation)

Permission Viewer -- An orchestrator managing four sub-components: browse list, profile detail view, profile-vs-permission-set comparison, and CSV export.

History -- Migration history table with expandable log detail rows and a stats summary widget.

Components communicate through standard LWC events and @api properties. The wizard passes a shared state model down from the modal container to each step.