hardis:project:generate:bypass

Description

Command Behavior

Generates custom permissions and permission sets to bypass specified Salesforce automations (Flows, Triggers, and Validation Rules) for specific sObjects, with optional automatic implementation of bypass logic.

This command provides a controlled mechanism to temporarily or permanently disable automations for certain sObjects, which is invaluable for:

• Data Loading: Bypassing validation rules or triggers during large data imports.
• Troubleshooting: Isolating automation issues by temporarily disabling them.
• Development: Allowing developers to work on specific sObjects without triggering complex automations.

Key functionalities:

• Global Bypass Generation: Automatically creates global bypass permissions (BypassAllFlows, BypassAllTriggers, BypassAllVRs) that work across all sObjects.
• sObject Selection: Specify a comma-separated list of sObjects via --objects flag (e.g., Account,Contact), or use interactive prompts to select from available triggerable and customizable sObjects.
• Automation Type Selection: Choose which automation types to bypass via --automations flag: Flow, Trigger, or VR (Validation Rules), or select interactively.
• Automatic Bypass Implementation: Optionally inject bypass logic directly into automation metadata using:
  • --apply-to-flows: Adds a decision node at the start of record-triggered flows to check bypass permissions.
  • --apply-to-triggers: Inserts a bypass check at the beginning of Apex trigger bodies using FeatureManagement.checkPermission().
  • --apply-to-vrs: Wraps validation rule error conditions with bypass permission checks.
• Metadata Source Control: Choose where to retrieve automation metadata from via --metadata-source:
  • org: Retrieves the latest metadata from the connected org (recommended for accuracy).
  • local: Uses local metadata files from the project (faster but may be outdated).
• Metadata Generation: For each selected sObject and automation type, generates:
  • Custom Permission (e.g., BypassAccountFlows) - The bypass switch that can be assigned via Permission Sets.
  • Permission Set (e.g., BypassAccountFlows) - Grants the corresponding Custom Permission to users.
• Comprehensive Reporting: Generates two detailed CSV reports:
  • Metadata Generation Report: Lists all custom permissions and permission sets created.
  • Implementation Report: Shows which automations had bypass logic added, skipped, ignored, or failed.
• Credits Control: Use --skip-credits to omit the "Generated by sfdx-hardis" attribution in XML files.

Technical explanations

The command's technical implementation involves:

• SOQL Queries:
  • Queries EntityDefinition to list all triggerable and customizable sObjects.
  • Queries ValidationRule (Tooling API) to find validation rules for selected sObjects.
  • Queries ApexTrigger (Tooling API) to find triggers related to selected sObjects.
  • Queries FlowDefinitionView to find record-triggered flows for selected sObjects.
• Interactive Prompts: Uses the prompts library for user-friendly selection of sObjects, automation types, and implementation options when flags are not provided.
• XML Generation: Dynamically generates Custom Permission and Permission Set XML files with descriptive labels and comments indicating their purpose.
• File System Operations: Uses fs-extra to create directory structures and write metadata files to force-app/main/default/customPermissions/ and force-app/main/default/permissionsets/.
• Metadata Retrieval: When --metadata-source org is used, executes sf project retrieve start --metadata commands in chunks of 25 records to retrieve current automation metadata from the org.
• Smart Bypass Implementation:
  • Validation Rules: Modifies errorConditionFormula XML nodes to wrap existing formulas with AND(NOT($Permission.Bypass...), ...) checks.
  • Triggers: Injects if(FeatureManagement.checkPermission('Bypass...')) { return; } at the start of trigger bodies.
  • Flows: Adds a decision node named SFDX_HARDIS_FLOW_BYPASS_DO_NOT_RENAME as the first node, checking both specific and global bypass permissions.
• Duplicate Detection: Skips implementation if bypass logic is already present, preventing duplicate additions.
• Error Handling:
  • Validates sObject and automation selections.
  • Handles missing files gracefully when using local metadata source.
  • Reports errors for each automation that fails processing.
  • Continues processing remaining items even when individual items fail (unless critical errors occur).
• Reporting: Generates timestamped CSV reports showing outcomes for both metadata generation and bypass implementation operations.

Parameters

Name	Type	Description	Default	Required	Options
apply-to-flows	boolean	Apply bypass to Flows
apply-to-triggers	boolean	Apply bypass to Triggers
apply-to-vrs	boolean	Apply bypass to Validation Rules
automations -a	option	Comma-separated automations to bypass: Flow, Trigger, VR
flags-dir	option	undefined
json	boolean	Format output as json.
metadata-source -r	option	Source of metadata elements to apply bypass to. Options: 'org' or 'local'.
objects -s	option	Comma-separated list of sObjects to bypass (e.g., Account,Contact,Opportunity). If omitted, you will be prompted to select.
outputfile -f	option	Force the path and name of output report file. Must end with .csv
skip-credits -k	boolean	Omit the "Generated by" line in the XML files
skipauth	boolean	Skip authentication check when a default username is required
target-org -o	option	undefined
websocket	option	Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:project:generate:bypass

$ sf hardis:project:generate:bypass --sObjects Account,Contact,Opportunity

$ sf hardis:project:generate:bypass --automations Flow,Trigger,VR

$ sf hardis:project:generate:bypass --sObjects Account,Opportunity --automations Flow,Trigger

$ sf hardis:project:generate:bypass --skipCredits

$ sf hardis:project:generate:bypass --apply-to-vrs

$ sf hardis:project:generate:bypass --apply-to-triggers

$ sf hardis:project:generate:bypass --metadata-source org