Skip to content
This repository has been archived by the owner on Feb 18, 2024. It is now read-only.

Latest commit

 

History

History
217 lines (143 loc) · 10.3 KB

getting-started-1.md

File metadata and controls

217 lines (143 loc) · 10.3 KB
Raw

On your Salesforce Org

To enable modular package development, there are a few configurations in Salesforce as a System Administrator that needs to be turned on to be able to create Scratch Orgs and Unlock Packages.

A. Enable Dev Hub

Enable Dev Hub in your Salesforce org so you can create and manage scratch orgs and second-generation packages. Scratch orgs are disposable Salesforce orgs to support development and testing.

  1. Navigate to the Setup menu
  2. Go to Development > Dev Hub
  3. Toggle the button to on for Enable Dev Hub

B. Enable Unlocked Packages and Second-Generation Managed Packages

Unlocked packages help organize your existing metadata, package an app, extend an app that you’ve purchased from AppExchange, or package new metadata.

  1. Navigate to the Setup menu
  2. Go to Development > Dev Hub
  3. Toggle the button to on for Enable Unlocked Packages and Second-Generation Managed Packages

C. Create Service Account for Deployment

For auditing purposes, it is best practice to create a separate service account to manage deployments to your Salesforce instance. The separation of user owned accounts and service accounts ensures traceability to your metadata and configuration changes.

  1. Navigate to the Setup menu
  2. Go to Users > Users
  3. Click on New User button
  4. Enter CICD for First Name and User for Last Name
  5. Enter in a Email address and Username
  6. Set User License to Salesforce
  7. Set Profile to System Administrator
  8. Scroll down and click on Save

{% hint style="info" %} Only certain editions of Salesforce has API Access. It's best to create a new Profile or Permission Set and configure the System Permissions and enable the API Enabled and Api Only User permission. {% endhint %}

{% hint style="warning" %} Future requirements to enable MFA across all users will require a special user permissions to be assigned to the Service Account. Details will be provided in the future and updated in the above steps to implement. {% endhint %}

D. Authenticate to DevHub via CLI

Authorize your production instance and/or Developer Edition Org using the web login flow. The example below uses "DevHub" as the alias for the instance where you will use it to create Unlock Packages and manage Scratch Orgs.

sf  auth web login -a DevHub -r https://login.salesforce.com

E. Install sfpowerscripts Scratch Org Pooling Unlocked Package in DevHub

The Scratch Org Pooling Unlocked Package adds additional custom fields, validation rules, and workflow to the standard object "ScratchOrgInfo" in the DevHub to enable associated scratch org pool commands to work for the pipeline.

sf package install -p 04t1P000000katQQAQ -o DevHub -r -a package -s AdminsOnly -w 30

F. Install sfpowerscripts-artifact Unlocked Package in DevHub and Lower Existing Sandboxes

The sfpowerscripts-artifact package is a lightweight unlocked package consisting of a custom setting SfpowerscriptsArtifact2__c that is used to keep a record of the artifacts that have been installed in the org. This enables package installation, using sfpowerscripts, to be skipped if the same artifact version already exists in the org.

sfdx package install --package 04t1P000000ka9mQAA -o <OrgAlias> --securitytype=AdminsOnly --wait=120

G. Authenticate to Lower Sandbox Environments via CLI

The template assumes you are following the environment strategy defined in our DX@Scale Guide. The following sandboxes are recommended to be created and authenticated first prior to running the pipeline.

  • SHAREDDEV (Shared Development)
  • ST (System Test)
  • SIT (System Integration Test)
  • UAT (User Acceptance Test)
  • PROD (Production)

{% hint style="info" %} Assuming that Production is also your Dev Hub, we still recommend creating multiple CLI entries to segregate the connections. {% endhint %}

Additional environments and customization can be made once you are familiar with the scripts.

{% tabs %} {% tab title="Sandbox" %}

sf  auth web login -a <orgAlias> -r https://test.salesforce.com

{% endtab %}

{% tab title="Production" %}

sf auth web login -a <orgAlias> -r https://login.salesforce.com

{% endtab %} {% endtabs %}

H. Generate SFDX auth URL for Pipeline Authentication

In order for the GitHub pipeline to authenticate to the DevHub and other environments, SFDX auth URL is the preferred method over JWT Bearer Flow. For each environment, execute the following command on a previously authenticated environment and save the sfdxAuthUrl for use in future pipeline configuration steps.

sf org display -o <orgAlias> --verbose --json > authFile.json
cat authFile.json
> {
  "status": 0,
  "result": {
    "id": "XXXXYYY",
    "accessToken": "00D8G0000009g7h!uhuRfGKbvPeubTZKztmFWgrykDuuVdxbffzjjVTqjMyRcV{wb+2JtxsevgKfGiGXRz02jY83uNBsD4CuWHwv.b21KZdFxbTi",
    "instanceUrl": "https://your.salesforce.com",
    "username": "[email protected]",
    "clientId": "PlatformCLI",
    "connectedStatus": "Connected",
    "sfdxAuthUrl": "force://PlatformCLI::Cq$QLeQvDxpvUoNKgiDkoTqyVHdeoMupiZvkgHYcdVHsfMaDpqKJNbg#[email protected]",
    "alias": "SharedDev"
  }
}

{% hint style="info" %} Save only the following part of the sfdxAuthUrl for each environment

force://PlatformCLI::Cq$QLeQvDxpvUoNKgiDkoTqyVHdeoMupiZvkgHYcdVHsfMaDpqKJNbg#[email protected] {% endhint %}

I. Public Group and Sharing Rules Creation for Developer Access to Scratch Org Pools

For developers (who are on limited access license) to access scratch orgs created by the CI service user, for their local development, a sharing setting needs to be created on the ScratchOrgInfo object. The sharing setting should grant read/write access to the ScratchOrgInfo records owned by a public group consisting of the CI service user and a public group consisting of the developer users.

  1. Create Public Groups (Setup > Users > Public Groups)

    • CI Users (Admin users/ CI users who creates scratch orgs in pool)

    Public Group: CI Users

    • Developers (developers who are allowed to fetch scratch orgs from pool)\

    Public Group: Developers

  2. Create Sharing Rule "ScratchOrgInfo RW to Developers" (Setup > Security > Sharing Settings)

    • Grant Read/Write access to the ScratchOrgInfos records owned by the CI Users to Developers

    Sharing Rule

  3. Assign Users to Public Groups (Setup > Security > Sharing Settings)

    • CI Users
    • Developers

    Public Group: User Assignment

J. Permission Set Creation for Developer Access to ScratchOrgInfo Object

The developers must also have object-level and FLS permissions on the ScratchOrgInfo object. One way to achieve this is to assign a permission set that has Read, Create, Edit and Delete access on ScratchOrgInfos, as well as Read and Edit access to the custom fields used for scratch org pooling: Allocation_status__c, Password__c, Pooltag__c and SfdxAuthUrl__c

Permission Set Name: "Scratch Org Developer"

Object: Scratch Org Info

  1. Object Permissions
    • Read, Create, Edit and Delete
  2. Field Permissions

    • Read, Edit for Custom Fields

      • Allocation_status__c
      • Password__c
      • Pooltag__c
      • SfdxAuthUrl__c

      Permission Set: Object/Field Permissions

System Permissions:

  • API Enabled = True
  • API Only User = False
  • Create and Update Second-Generation Packages = True

Permission Set: System Permissions

K. Profile and Permission Set Assignment for Developers in Production

To onboard new developers, the following Profiles and Permission Set will need to be assigned to the new Developer User Account in Salesforce.

Profile (Choose 1 Only)

  1. Minimum Access - Salesforce
    • Licence Type - Salesforce
  2. Limited Access User
    • Licence Type - Salesforce Limited Access - Free

Permission Set

  • Scratch Org Developer

Public Groups

  • Developers - Add Users to "Developers" Group

Frequently Asked Questions (FAQs)

  1. Unable to fetch scratch org from Dev Pool even though there are available scratch orgs in DevHub.

    ERROR running sfpowerscripts:pool:fetch: No scratch org available at the moment for dev, try again in sometime.

    Possible Solutions:
    - Check that you have added the Developer User to the Public Group prior to fetching the scratch org from the pool
    - Confirm the tag is correct for the scratch org pool that you are fetching from