Introduction

Purpose of this Document

The purpose of this document is to provide a set of guidelines and best practices that the development team (Admins and Developers)  must follow, when working on Syensqo’s Salesforce applications.

Audience

Reading is mandatory for anyone that potentially will be configuring/customizing/building components in Salesforce, namely:

• Administrators
• Developers
• Tech Leads
• Technical Architects
• Deployment Team

Reading is advisable for:

• Management team
• Functional Analysts
• Functional Lead

Reading is optional for:

• Support Team

Configurations Guidelines (point & Click)

Objects

Naming Convention: Use the prefix in the Annex I according to the Accountable Process

• Description: mandatory to fill in (when editing is not blocked) - it should be clear enough in order to be used by AI. 
• There is no default recommendation for object properties like field history tracking, enabling reports, chatter feed, etc. For a new object, all these options need to be discussed and aligned with Analyst/Business.
• When creating new objects, please don’t forget about compact layouts and the different types of search layouts. Each one needs to be discussed and defined.
• Default CRUD access should be provided on Permission sets (Exception allowed only for System Administrator Profile)
• Define Sandbox dataseeding needs. 

Record Types

• Always assess  the need to have record type instead of using Master record type. This guideline is to enable future evolutions and reduce the impact if a new record type needs to be created for the same object.

Fields

Naming Convention: Use the prefix in the Annex I according to the Accountable Process

• Description field: please describe, from a functional perspective for what the field will be used for and for each process if used in Integration including external reporting (Qlik), this is an enabler for future AI implementations. is advisable to include the Jira/requirement number.
• Default CRUD access should be provided on Permission sets (Exception allowed only for System Administrator Profile)
• Relationships: Establish correct relationships (lookup, master-detail) with other objects taking into account Key Visibility Principles and Sharing Model. 
• For lookup fields with filters, the error message needs to be clear and clearly mention the name of the field where the error is happening. E.g. Invalid value for field BU. Please review.
• Regarding picklists, if a picklist is likely to be used in more than 1 object, please consider using global value sets picklist, but remember that, for global value sets picklist, values are always restricted.

Validation Rules

Naming Convention: Use the prefix in the Annex I according to the Accountable Process

• Avoid Validation rules if possible to perform the same functionality with Dynamic forms - we would like to avoid users to discover mandatory fields after saving. 
• Validation Rules must be used when enforcement should be absolutely maintained at the database level which will not be guaranteed by the Dynamic Forms
• All rules must have the global bypass using the custom permission ($Permission.Bypass_Validation_Rules). Other bypasses can be used in specific situations (e.g. SAP bypass, integration users bypass, etc.). This should be used very carefully with a lot of considerations, this should be only exceptional cases. 
• Error messages need to be concise and clear. If possible, the error should be displayed next to the field and not on top of the page.
• Please use indentation to make validation rule reading easier.
• When creating new validation rules (and sometimes when updating), always take some time to consider what needs to happen to existing records. Do we need to enforce an update? If the rule is firing for existing records, then we should ask the Business to fix the data for those existing records, or agree on using record creation date as criteria.

Page Layouts

• Generic naming convention is not applicable, as layouts don’t have API names. Generically, layout name should match object name or, if record types exist, layout name should match the record type name. There is no need to include the expression “layout” in the name.
• By default, the sharing button should not be included. It should only be included if the requirement clearly mentions it as a functionality for the user.
• Make sure you discuss layout structure, buttons and actions, both for lightning and   - Ideally request the mockup to the Analyst, or propose one.

Dynamic Layouts

• Dynamic vs Non dynamic behavior: Field-level visibility rules are evaluated dynamically, so changes a user makes while editing a record can cause fields to appear or disappear in real time. In contrast, field-section visibility rules are not dynamic and do not respond to user edits during record editing; they are evaluated only after the record is saved.
• Universally Required Fields: Do not hide universally required fields using visibility filters, as users cannot save a record if any required value is missing—even when the field is hidden by a visibility rule.
• Polymorphic Relationship Fields: Polymorphic relationship fields are not supported as cross-object fields in Dynamic Forms.
• In case a field is mandatory in the layout and if we must be guaranteed from a data quality and consistency perspective, a validation rule must also be created.

Custom Labels

• Naming Convention: Use the prefix in the Annex I according to the Accountable Process
• As mentioned in section Generic Guidelines, please use custom labels to store constants that you can reference on apex, validation rules, workflows, etc.
• Short description can be a more developer friendly text.
• Use categories field for better understanding of what your custom label is used for. Examples:

Process nameController name

• NOTE: defining constants in a specific class is also a recommended approach:
• Constants | Apex Developer Guide
• Using the final Keyword | Apex Developer Guide

Approval Processes

• Naming Convention: Use the prefix in the Annex I according to the Accountable Process
• Do not set queues as assigned approvers. Even if you need several approvers, make sure you add them individually. Doing this ensures that it is possible for them to approve or reject by email.
• After Changing an approval process approver, please follow this SOP - How to handle existing data after change on Approval Process
• If you inactivate an approval process, make sure you add the prefix “(UNUSED) ” to its label. This will be very helpful to identify it after.

Email Alerts

• Naming Convention: Use the prefix in the Annex I according to the Accountable Process
• Avoid using the “Additional Emails” field. In some sandboxes, we don’t want emails to be sent. It is easy to inactivate or freeze users and mask contact email addresses. But if we have a lot of rules with additional emails, we increase the manual effort of reviewing them all, if you really need to do it, please update the Sandbox Refresh Procedures.
• Should you use Additional Email ensure to update the CRM Refresh Procedure document in order to anonymize those email addresses.
• All automations using email alerts must have a global bypass, based on a custom permission ($Permission.Disable_All_Emails), Because sometimes you may want to run an automation but not send the email alert

Email Footers

Not used in syensqo so far.

Mail Merge Templates

No specific guidelines identified so far.

Organisation-Wide Addresses

• Every Organization-Wide Address must be assigned to System Administrator and System Admin (lite) profiles.

Matching Rules

No specific guidelines identified so far.

Duplicate Rules

• Each duplicate rule needs to include the following bypass: Current User:GEN_ByPassDuplicateRules__c. This is needed to run the anonymization in UAT without hitting the duplicate rules. This field should be checked only for OwnBackup integration user. Ideally Custom Permission should be used but it is not supported for Duplication Rules.

Classic Email Template

Guidelines Valid for Text,  HTML, Custom and Visualforce template type:

• Please organize email templates in specific folders (e.g. process name).
• Always prefer HTML templates, usage of VisualForce templates will require justification.
• Default Letterheads: Internal Templates: (emails sent to our company Users/ employees)
• Default Internal Communication Header
• Default Letterheads: External Templates:(emails sent to our Contacts, Leads or Community Users)
• Default External Communication Header
• Documentation: Please Update Email Templates Master File, every time you create/use Classic Email templates.

Lightning Email Template

No specific guidelines identified so far.

Case Assignment Rules

• Since rules don’t have a name or description, on the rule criteria please use formula and start by including a comment that explains what is used for. E.g. /* Complaints - Aroma Performance*/
• Avoid hard-coding specific users as assigned users. If possible, use queues instead. Motivation: in dev sandboxes, the business users are typically inactive and it is not possible to deploy assignment rules that contain reference to inactive users.

Lead Assignment Rules

No specific guidelines identified so far.

List Views

No specific guidelines identified so far.

Lightning App

No specific guidelines identified so far.

External Client App/Connected App

• One Connected App must be created per environment per system integrated with.
• One for SAP BTP
• One for Sailepoint
• …
• The secured authentication to use is OAuth 2.0 JWT Token Flow, if not possible please reach out to your Tech Lead/Architect because an assessment needs to be performed. To be confirmed with the security committee.

Chatter Groups

• For business chatter groups, assign a business user as group manager

Email to Case

• <need to be dined, in the past, we could not use the auto-forwarding feature from the mailbox, with microsoft we need to see, we might need to request the forwarding to be done before the email arrives to mailbox.>

Custom Settings & Custom Metadata Types

. The decision to go for Custom Metadata or  Custom Settings depends on the use case. Please take the following into consideration:

• Custom settings: useful for configurations that differ from sandbox to sandbox/ Org. E.g. URLs for external apps.
• Custom metadata types: useful for configurations that don’t change between sandboxes and PROD.

Useful  Custom Settings and Custom Metadata

• Before creating a custom metadata or custom settings, assess if an existing one can be reused or extended first
• Maintain a central repository of all the Custom Metadata and Custom Settings and their usage

Guidelines for Custom Settings

Flows Guidelines (Low Code)

General Guidelines

Modular Design & Architecture

• Single Responsibility Principle: Each flow should handle ONE specific business process or function
• Maximum Elements Guideline: Aim for flows with fewer than 50 elements; if exceeding, consider splitting
• Subflow Strategy: Extract reusable logic into subflows (e.g., validation logic, notification logic, calculation logic)
• Flows First: Use flows for all business logic. If flows cannot be used, a justification must be provided.

Flow Version Management

⚠️ IMPORTANT: Pay attention to the Flow API version

• Build your flow using the same version available in Production at the Go Live Date
• Recommendation: Always use the current API Version -1
• Example: If the current version available is 60, use version 59
• This ensures stability and avoids issues with newly released features that may have bugs

Flow Trigger Explorer Management

⚠️ MANDATORY: Use Flow Trigger Explorer to explicitly set execution order for all Record-Triggered Flows on the same object

• When adding a record trigger flow, always reflect on the order of execution and setup a proper order compared to the other record trigger flows.

Naming Conventions

Flow API Name Pattern

The prefix represents the process category or business domain the flow belongs to.

📋 Reference: See the Domain Prefix Mapping Table (Annex I) in the Appendix for the complete list of prefixes.

The suffix represents the type of event:

• Before Save: _BS
• After Save: _AS
• Before Delete: _BD

Examples:

• ACC_Account_ValidateAddress_BS - Account process flow for address validation
• OPP_Opportunity_CalculateDiscount_BS - Opportunity process flow for discount calculation
• GEN_SendEmailNotification_AS - Generic/cross-process subflow for sending email notifications

Element Naming Within Flows

Email Notifications

⚠️ MANDATORY: Use Email Alerts instead of single emails

• Email Alerts allow handling the email body with an Email Template instead of managing it manually in the flow
• This provides better maintainability and allows business users to update email content without modifying flows
• Exception: Single emails are acceptable only when reaching Email Alert limits

Error Handling & Logging

Default Error Handling

Uncaught exceptions in flows are automatically captured in the persistent Log Message table via platform events fired by Salesforce. This provides baseline error tracking without additional configuration.

Fault Path Implementation (When Required)

ℹ️ SELECTIVE USE: Fault paths should NOT be added systematically to every element. Only implement fault paths when a business exception is expected and requires special behavior.

When to Add Fault Paths:

When NOT to Add Fault Paths:

• Standard DML operations where default error handling is sufficient
• Simple field updates where failure should stop the process
• Operations where the default platform event logging provides adequate visibility

Performance & Bulkification

Loop Optimization

🚫 NEVER place DML operations (Create, Update, Delete) inside loops
🚫 NEVER place Get Records inside loops

Correct Pattern:

1. Collect records in a collection variable within the loop
2. Perform single DML operation outside the loop

Governor Limit Awareness

Entry Conditions

⚠️ MANDATORY: Define precise entry conditions to prevent unnecessary flow executions

• Use $Record__Prior comparisons to detect actual field changes
• Example: Only run when Status changes from any value to "Closed"

Record-Triggered Flows - Synchronous & Asynchronous Paths

Bypass Automation Check

⚠️ MANDATORY: Flows at the beginning of execution should verify if they are bypassed

• Check a ByPassAutomation custom permission at the start of the flow
• This allows administrators to temporarily disable automations for data migrations or troubleshooting
• Implement as the first Decision element in the flow

Flows First Approach

• Use flows for all business logic
• If flows cannot be used, a justification must be provided
• Wherever Apex is required for lightweight operations, it should be called from the trigger flow
• Examples: Apex sharing, formula recalculation, complex calculations

Asynchronous Path Limitations

⚠️ IMPORTANT: Only ONE asynchronous flow per object

• Since we cannot force the order of execution for Asynchronous Flows, we should have only one async flow per object
• This prevents unpredictable behavior and race conditions
• If multiple async operations are needed, consolidate them into a single async path with decision logic

Test Coverage Requirements

Synchronous Path

• Test classes are mandatory for synchronous paths
• Build during the build phase following normal Apex testing guidelines
• Include assertions to validate expected outcomes

Asynchronous Path

⚠️ KNOWN LIMITATION: Due to current Salesforce limitations, the Test.stopTest() method does not function as expected for asynchronous paths of autolaunched flows.

Approach:

• We are unable to validate the results of asynchronous path flows in unit tests
• This is different from testing @future methods and Queueables where results can be validated after Test.stopTest()
• Exception: We do not include assertions in unit tests for asynchronous paths of autolaunched flows
• These unit tests are created solely to achieve code coverage, enabling the deployment of flows as active

Future Benefit: A positive outcome of this approach is that we will have pre-existing unit tests ready for when Salesforce introduces the capability to verify asynchronous flow results in tests.

Record-Triggered Flows - Scheduled Paths

Lead Object Restrictions

⚠️ IMPORTANT: Avoid scheduled paths on the Lead object unless the time offset is very short (a day or less)

Reason: There is a known issue where a Lead cannot be converted if it has pending time-based actions.

Workaround: If an action needs to happen X days after a trigger:

1. Create a Scheduled Flow running daily
2. Check if the criteria is met (e.g., if 30 days passed after creation)
3. Execute the required actions in that scheduled flow

General Scheduled Path Guidelines

• Keep time offsets as short as practical
• Consider the impact on record operations during the scheduled window
• Document the expected timing and business justification for scheduled paths

Screen Flows

Screen Flows as Preferred Solution

✅ RECOMMENDED: Screen flows and dynamic layouts are the recommended solution over LWC

Assessment Process:

1. Every new requirement (User Story) should first be assessed to determine if it can be achieved using a no-code solution
2. If requirements cannot be achieved via screen flow, they should be challenged to assess and provide a simplified proposal using the standard no-coding approach
3. Only after exhausting no-code options should custom development be considered

LWC Embedding

• It is acceptable to include LWC components into screen flows
• Balance is key: Maintain the right balance between flow elements and custom components
• Use LWC only for functionality that cannot be achieved with standard flow components

Test Coverage

ℹ️ NOTE: Screen flows do not require Apex test coverage to be deployed

• It is not possible to write Apex tests for screen flows
• Testing should be performed manually through the UI
• Document test scenarios for QA validation

Flow Test Coverage Summary

When Test Coverage is Required

ℹ️ Note: Salesforce only requires test coverage for Record-Triggered Flows to deploy them as active. Other flow types (Scheduled Flows, Platform Event-Triggered Flows, Screen Flows) do not require Apex test coverage for deployment.

Test Coverage Best Practices

• Positive: Testing: Test happy flow scenario
• Negative Testing: Test scenarios where entry conditions are NOT met (flow should not execute)
• Edge Cases: Test null values, empty collections, and boundary conditions
• In Syensqo all flows are deployed as active therefore the flow coverage of the org (number of flows that are ‘called’ during apex tests execution divided by number of all active flows) should be greater than 75%. (see Queries to calculate flow coverage to have details on how to calculate flow coverage)
• In relation to the Apex tests, point and click flow tests are not considered part of test coverage. It lead  to the situation that  developers needs to assure that AutolaunchedFlow, CustomEvent flows,  invocable flows and scheduled are covered (executed at least once) by apex tests

Important: Apex Tests vs Flow Tests

⚠️ CRITICAL DISTINCTION: Salesforce offers two types of flow testing, but only one counts for deployment:

Flow Tests created in Flow Builder are useful for manual validation and debugging, but they:

• Are NOT executed during deployment
• Do NOT count toward flow coverage requirements

Therefore, Apex test classes are required to achieve the coverage needed for deploying Record-Triggered Flows as active.

Documentation Requirements

Flow Description

Every flow MUST include a clear description explaining what the flow does:

This flow validates the billing address format for Account records when they are created or updated. 

It checks for required address fields and standardizes the format before saving.

Keep descriptions:

• Concise: Focus on what the flow does, not implementation details
• Business-focused: Explain the business purpose
• Up-to-date: Update when flow functionality changes

Element Descriptions

• Add descriptions to complex Decision elements explaining the business logic
• Document any "magic numbers" or hardcoded values with business justification

Anti-Patterns to Avoid

❌ DO NOT:

• Create multiple Record-Triggered Flows on same object without using Flow Trigger Explorer
• Place SOQL or DML inside loops
• Use hardcoded IDs
• Add fault paths to every element systematically (only when business exception handling is needed)
• Leave flows without descriptions
• Create overly complex single flows (50+ elements)
• Use Process Builder or Workflow Rules (migrate to Flow)
• Use single emails instead of Email Alerts (unless hitting limits)
• Create multiple asynchronous flows on the same object
• Use scheduled paths on Lead object with long time offsets
• Build custom LWC when screen flows can achieve the requirement

Security, Sharing, Access Management Guidelines

Definition and scope

Security solutions and Access Management processes must be designed and implemented according to the IS Security Policies and compliance guidelines. 

Security refers to system permissions, objects and fields access, data access and user management guidelines.

Security is divided into 3 aspects:

• Security Model: access to Objects and Fields + System and User permissions (profile,  permission sets and permission set groups management)
• Visibility/Sharing Model: access to Data/Records related to business visibility guidelines. It includes queue, public groups, team sharing management, sharing rules
• Access management (User Management Lifecycle): guidelines and procedures.

Safeguards

• System Administrator profile must not be assigned in Production, except if it has been approved by Syensqo Lead.
• System Administrator or System Admin (lite) cannot be assigned to non IT users even if they request it.
• Integration profiles should have access to nothing, profiles to Use ‘No Access’ or ‘API Only System Integrations’  (no object, no system permission…) , to provide access to objects and fields for a certain Integration, a specific permission set must be created.

General Guidelines for Profile/Permission Set Groups/Permission Sets

Detailed security principles and guidelines can be found part of the Salesforce Application Architecture (Application Security section) 

Custom Permissions

Delegated Administration

• Delegated Administration can be used to provide ‘Super User’ Access to some our GBU users
• Delegated Admin groups should be created by GBU and another one for IT.

Queue and Public group management

• Since Queues management is not possible to delegate, the guidelines is to create a public group each time a queue is created
• Each time a new public group is created, it needs to be added to the Delegated Administration group of the GBU, and IT. Without doing this step, GBU Data steward or IT will not have the rights to update the group members.

Queue Naming convention: The first thing to do when creating a queue is to determine which will be the queue’s name.

A queue name must follow this nomenclature:

<gbu code>-<process>-<queue name>

• The <gbu code> refers to the Annex III
• The <process> refers mainly to where this queue will be used (Sample, Customer Request, Leads…), Annex I
• Do note that a queue label and API Name cannot have more than 36 characters as the last 4 characters are required for a public group creation as will be explained further in the document.

Public group creation: Once a label has been determined for the new queue the next step is to create a Public Group. This will be where the users required to access the queue will be added and managed.

When creating the group the label will be:

QUE-<corresponding queue name>

The 4 characters used to label the public group are why the queue name cannot have more than 36 characters.

Additional Steps: Once the queue is created the following action must be taken to ensure the correct working of the queue and the security around it:

• Adding the users to the public group you created in Step 2.
• A case list view is automatically generated when you create a queue. To avoid security issues, edit the list view sharing by removing “All Internal Users” (added by default), adding the public group you created and make sure the Visibility is set to “Visible to certain groups of users”. 
• Adding the public groups to the corresponding Delegated Administration groups (CGI + the related GBU)

Mass Data Management Guidelines

Mass Data Management might be required in several situations, like data migrations, data transformation, data updates, data creation due to several reasons, projects needs, roll-out needs, carve-out needs or simply as validation rules creation/updates, new fields creation, fields type changes, etc.

We have currently 3 ways to change data:

• Using apex Script
• Using apex batch
• Using Loading files
• External tools, like Talend

Below you find the guidelines for when is recommend to use each approach:

For UAT and PROD environments, all data updates must be executed under a specific User: <user to be created>

Environments and Data Loading Users to use:

IT Technical Users

• Data Loading User- <to include the user name> - to be used for data loading Activities
• System - <to include the user name> - to be used for Apex batch schedule, system defaults, system monitoring notifications.

Reports and Dashboards Guidelines

<we will need to define if the reports and dashboards will be included into Git repository>

Customization Guidelines (code)

Our Main guideline is NO CODE: Before moving into a Custom Solution, you will need to justify why, so please always consider Standard point and Click, low code solutions and appexchange solution first, this is also valid if you are requested to update existing code, here you have several options to justify the need to use code:

• Impossible with Standard: share the limitations of the platform, highlight risks of reaching governor limits, highlight the risks on performance and scalability.
• Partially Implemented with code: your solution will be a mix between point and click and code, you will need to justify why code is needed.
• Use of managed package: the usage of managed package will be accepted, if the package supplier provides support, if it is free (if not free Syensqo will need to initiate a purchasing process), please note that unmanaged packages where we will need to perform maintenance are considered as code, so therefore not accepted as alternative for code. 
• Create Technical Debt: while updating existing code, due to workload reasons, you can propose a temporary implementation with code, and creation of technical debt for migration to standard.

Please refer to this link for Development Guidelines related to Customization. 

Integrations

Technical Architects will need to be informed about all integration needs. The following topics will be defined by Technical architect, nevertheless below you can find generic guidelines: 

• All Integrations must be listed into file CRM Integrations List, maintained by Technical Architect or Tech Analyst.
• For new Integration the authentication method should be OAuth 2.0 JWT token flow, if not supported, an exception must be created (contact Technical Architect or Tech Analyst). 
• Integration User should be defined by System/Middleware that we are directly integrating with (1 user for webmethods, 1 user for SAP, 1 user for Gensuite, etc), instead of one user per data flow.
• Integration User should have ‘API Only System Integrations’, profile with Permission set Licence: ‘Salesforce API Integration’ , if no licence available or not supported, profile ‘No Access’ should be granted instead.
• Data Flow Diagrams should be created in Stored in this folder:
• Each specific dataflow access (needed system permissions, Objects, FLS, apex classes, etc) should be granted via specific permission set, NOT via profile.
• Monitoring: Detailed design of each integration should cover the monitoring approach

Release Management

CRM Release Management guide can be found at our Wiki, please make sure that you read the information available as well to understand the overall environment strategy, org strategy and follow the process.  

Responsibilities in Salesforce Development and Release Validation

When engaging in any development activity in Salesforce, developers are responsible for ensuring the quality and integrity of the code by following these key practices.

•     Execution of Test Classes:
  If a developer is making changes to any existing code, the developer needs to ensure that he runs the associated test classes before he starts the development to ensure all the existing code is working as desired. And once he is done with his development the developer must execute all related test classes associated with the development again.This step is crucial to verify that the new code or changes do not introduce any issues into the existing system. 

•     Error Resolution:
  If any errors are encountered during the execution of these test classes post his development, it is the developer's responsibility to investigate and fix those errors promptly. This ensures that the code functions as expected and maintains system stability.

•     Release Validation:
  In the event of any errors encountered during the release validation process, it is the responsibility of the developer who is accountable for the specific development activity to address and resolve the errors. The developer must ensure that the release is error-free before it is finalised and deployed. The DevOps team will be sharing the build failure information in the common chat group (To be created for the intended use for Deployment communication and collaboration) which will have all the developers, tech leads, architects associated with that release. DevOps team will be tagging the developer responsible post which developer needs to fix the build error and update the same on the same chat group. 

• Code Review:
  Role : Developer

Primary goal: Deliver working code with minimal downstream failures and review churn. 

Responsibilities: 

• Complete development plus Unit Testing (UT) in the dev environment.
• Pre-validate changes against the Quality Assurance (QA) branch before opening a Pull Request (PR) to:
• Prevent avoidable Continuous Integration (CI) failures,
• Protect shared environments
• Improve release/merge throughput
• Reduce review churn so reviewers spend time on design/quality, not break-fix.
• Raise PR for Tech Lead review once validation passes.

Role : Tech Lead

Primary goal: Ensure the code is merge-ready, maintainable, and aligned to standards. 

Approval model: 

• If the change is Out-of-the-Box (OOTB) with no customization/complex logic → Tech Lead approval is sufficient to merge upward.
• If the change is customized/complex feature work → Tech Lead provides Approval #1, then routes for Technical Architect Approval #2.

Responsibilities: 

• Confirm the implementation follows the coding standards defined in your referenced document.
• Verify functional completeness and quality: key scenarios covered
• Test classes working and with “proper defined coverage” (as per standards
• No obvious regression risks.
• Ensure any required documentation is complete, accurate, and kept with the right artifacts (e.g., Pre and Post Deployment Steps).
• Ensure that if for any reason (e.g. timeline constraints) guidelines are not followed, Syensqo MUST be informed and a technical debt created.

Role : Technical Architect

Primary goal: Protect architecture integrity and long-term scalability for higher-risk changes.

When involved: Any PR with customization, complex logic, or complex feature behavior requiring two approvals. Also he can do periodic reviews just to ensure that best practices are being followed in other non-complex and non-customized implementations also.  

Responsibilities: 

• Perform architectural and design validation beyond line-by-line code review, alignment with platform/reference architecture, correct patterns and boundaries (e.g., layering, dependency direction),
• Non-functional requirements (performance, security, reliability), backward compatibility and extensibility.
• Confirm the change can be merged with higher environments from a system-impact perspective. 

•     Accountability:
  Each developer is directly accountable for the development tasks they work on. If an error arises as a result of their development during the release process, they must take ownership of fixing the error. Collaboration with relevant teams may be required to ensure the issue is resolved in a timely manner.

•       Pre/Post Deployment Step Manual Tasks: Developers are responsible for clearly detailing the manual tasks required in the Jira ticket respective fields, including the time estimation for the execution of these, so the release manager can estimate the total estimated time of manual work per release deployment. Manual tasks must be written in a way that a Release Manager without context of each ticket can understand step by step what has to be done. 

🛠In practice

In best practice, creating feature branches at the start of development ensures your work is isolated from the main codebase, preventing incomplete changes from affecting the main branch. It allows multiple developers to work on different features simultaneously without conflicts and provides a clear context for tracking progress and collaboration. This approach also enables early testing and continuous integration, helping catch issues early and making it easier to merge changes smoothly into the main branch.]

Step 1: Checkout and refresh integration branch

Before starting work on a new feature, create a feature branch from the integration branch (develop) using this naming convention feature/US-XXXX; replace XXXX` with your User Story or task ID. Make sure you are on the integration branch to start with and you pull the latest from your remote before creating the branch.

git fetch --all prune 

git checkout develop

git pull origin develop

git checkout -b feature/US-123

• Branch Types:
• Feature: feature/US-XXXX
• Bugfix: bugfix/US-XXXX
• Hotfix: hotfix/US-XXXX

Step 2: Ready to develop

You can now make your change locally (e.g.: classes) or in your dev sandbox. Once ready pull the latest changes from Salesforce using sf command.

sf project retrieve start -o myDevOrg -m "CustomObject:Account"

Step 3: Stage and Commit your changes

git add force-app/main/default/objects/Account

git commit -m "[US-123] My Account changes"

git push origin feature/US-123

You can repeat steps 3 & 4 until changes are complete and the feature is tested.

🔄 Validate Feature

After completing your development and testing locally, it's crucial to ensure that the feature works as expected in a collaborative environment(QA). This involves merging your changes back into the integration branch(develop), where they can be further tested and validated by the team. Follow these steps to validate your feature:

Step 4: Create a Pull Request (PR)

Open a PR to merge into the integration branch (develop). Consult your tech lead if you are unsure of the target branch.

• Pipeline Build Steps:
• Static Code Analysis: Automated with Apex PMD.
• Validation Build: Ensures code quality.
• Apex Tests: Runs only relevant tests.
• Inspect Build Reports:
• Validation Build: Check reports via the PR build link.
• Key Tabs:
• Tests: View failed tests.
• HTML Viewer: See static code analysis results.
• Code Coverage: Review coverage for changed classes.
• Handle Build Failures: If the build fails, fix issues before requesting a PR review.
• Review Process: If your build is successful, your reviewer will review and merge the PR into develop.

How to write a good pull request ?

A good pull request (PR) can make or break your code review game and streamline your project’s integration process. Here’s how to craft a PR that stands out and gets the job done:

1. Punchy Title and Insightful Description

• Title: Start with the user story number and a brief summary. For example, “[US-123] 🔧 Fix login page authentication bug” or “[US-456] ✨ Add user profile feature.”
• Description: Dive deep into what’s changed with:
• Context: Explain why these changes matter—whether it’s a bug fix, a shiny new feature, or some refactoring. 🛠️
• Changes Made: Give a quick rundown of what’s new, what’s improved, or what’s been removed. 📜
• Related Issues/Tickets: Link to any relevant issues or tickets so reviewers can dive deeper if needed. 🔗
• Testing: Outline how you’ve tested the changes or how they should be tested. If needed, add test cases or steps. ✅
• Screenshots or Examples: For visual changes, throw in some screenshots or GIFs to showcase the updates. 🖼️

1. Code Quality and Organization

• Clean Code: Make sure your code is polished—no stray comments, debug lines, or formatting issues. Stick to project coding standards. 
• Commits: Keep commits focused and meaningful. Each commit should handle one thing at a time. 

1. Documentation

• Code Comments: Comment on tricky parts of the code to help others (and your future self) understand your logic. 
• Documentation Updates: If your PR impacts documentation, update the relevant docs or note it in the PR description. 

1. Issue Tracking

• Issue Reference: Link to the related issue or work item in Jira, i.e.: US-123. . 

1. Approval and Sign-Off

• Functional Approval: Ensure all necessary reviews and functional approvals are in place before merging. As once merged, this will automatically deploy your components to the next inline environments (i.e.: QA). 
• Sign-Off: If your project requires formal sign-off, make sure to get it from the required team members or stakeholders. 

1. Review Requests

• The github pipeline will enforce certain approval gates for quality controls. Make sure everything is clean before you reach out to your tech lead. 
• Reviewers: In the pull request, tag the right Teach Lead reviewers—those who know the code or can offer valuable insights. 
• Any pull request that only contains declarative changes, then only a review from tech lead is enough. Otherwise if the pull request contains any code like apex or lwc, then will need proper rieview from an architect (i.e.: David, Stephane). 
• Review Notes: Point out any specific areas where you need feedback. 

1. Merge Considerations

• Merge Conflicts: Check for conflicts before requesting a review. Resolve any issues to ensure a smooth merge. 

Example of a Pull Request

Title: [US-789] ✨ Add user profile feature

Description:
This PR introduces a new user profile feature, enabling users to view and edit their profile information. Here’s a breakdown:

• Added a UserProfile component for displaying user details. 
• Implemented profile editing with validation. 
• Updated the user settings page to include profile management. 

Related Issues: Closes [US-789] 🔒

Testing:

• Verified correct loading of the profile page and display of user data. 
• Tested various scenarios for profile editing functionality. 
• Confirmed that all tests are passing. 

Tools

Communication Channels

<this section aims to include all communication channels, for example Jira comments, and google/microsoft team groups, first with the goal to support project, then after to be adjusted for maintenance>

Github Subscriptions

To integrate GitHub with Microsoft Teams, you'll primarily be using the GitHub for Teams app. This allows your team to stay updated on pull requests, issues, and deployments directly within your Teams channels.

Installation Steps:

1. Open Microsoft Teams: Go to the Apps icon in the bottom-left corner of the Teams sidebar.
2. Search for GitHub: Type "GitHub" into the search bar. Select the official GitHub app.
3. Add to a Team: Click the dropdown arrow next to "Add" and select Add to a team. Search for the specific channel where you want the notifications to appear.
4. Set Up Notifications: Once added, the GitHub bot will appear in the channel.
5. Sign In: Type @github signin in the message box. A window will pop up asking you to authorize the connection between your GitHub account and Microsoft Teams.

Basic Commands to Connect Repositories

Once installed, you need to "subscribe" to specific repositories to receive updates. Use these commands in the channel:

• Subscribe to a Repo: @github subscribe owner/repository-name
• Unsubscribe: @github unsubscribe owner/repository-name
• List Subscriptions: @github subscribe list

Generic Guidelines

In this section, we will briefly introduce some topics that each Admin or developer should know in order to provide support for Release identification, and to ensure the proper communication channel is used.  The Generic best practices should always be considered. If, for some reason, it is not possible, please discuss with your technical lead.

• Each Configuration/development will have an Accountable Process that will determine the naming conventions to be used (each section below will detail).
• Configuration solutions should be privileged over Customizations, if Customization is necessary, a justification why configuration is not used must be provided.
• NO hard-coding!
• Use custom settings, custom metadata, labels or custom permissions (associated to profiles or permission sets), in order to ease maintenance of the functionalities:
• Custom settings: useful for configurations that differ from sandbox to sandbox/ Org. E.g. URLs for external apps.
• Custom metadata: useful for configurations that don’t change between sandboxes and PROD.
• Labels: it’s not a best practice to use labels for complex configurations, 
• For  CRM, never use hard-coded references to GBUs. Even if you are requested to implement a requirement for only 1 GBU, please implement in a way that is simple to extend to other GBUs in the future:
•  You can also use a label to store the list of GBUs that use the functionality, for example).
• It is recommended to use custom settings and metadata that store attributes related to GBUs.
• Custom permission: useful for configurations that depend on a certain profile or permission set.
• Every component should be built in a way to make maintenance simple, and in case maintenance is needed, an Operational Procedure must be created.
• Please take some time to have a clear understanding of Salesforce Order Of Execution Diagram
• Here the link to some Useful Salesforce Cheat Sheet
• Salesforce Apex Code Cheat Sheets
• SF formula Cheat Sheet
• REST API Cheat Sheet
• Record Locking Cheatsheet

Technical Documentation

While leveraging naming convention within a project in a consistent manner is a must have, the below is a proposition of convention but should not be considered as the only option. Each project team can decide on their own conventions considering the context.

Annex I - Naming Convention Suffix

Annex II - GBU Codes