/
DRAFT -- Open Guide to SF Solution Packaging (P1)

DRAFT -- Open Guide to SF Solution Packaging (P1)


This page is used to make notes for new material as it is being drafted. For completed text see the parent page -- Open Guide to SF Solution Packaging (1GP)

Table of Contents

Contributor Guidelines

Salesforce is a massive platform – designed by human beings.

  • Mistakes were made and mistakes will continue to be made.
  • But despite all of that, Salesforce is an awesome platform.

As Open Guide contributors, we don't need to be orthodox – we do need to be positive.

  • If we're not making it better, then we're making it worse.

The Open Guide is not a place for bitterness, sarcasm, or 20:20 hindsight.

  • It's a church of scars where we can help each other through the dark waters.

Like map makers of old, we're warning others: "Here be dragons".


(tick) To volunteer, see our Individual Contributor License Agreement.

Please also review the Trailhead Writing Style module.

As a general reference, please observe the Salesforce Style Guide for Documentation and User Interface Text.


Welcome

"Learn to plan, build, distribute, market, sell, and support solutions that run on the Salesforce platform."

...


Quick Start

"Get ready to build and sell solutions on AppExchange by completing short tutorials.

Tips 

  • For a Large Solution, Consider a Partner Development Outsourcer - https://partners.salesforce.com/s/education/general/Product_Development_Outsourcer
  • Enabling Person Accounts in Developer Edition Orgs is a two step process. Usually, you click a checkbox and file a case.
    • Developer Editor orgs have an issue with one of the profiles, and Support needs to clear that issue before you can check the box.
    • Do everything up to checking then box, and then file the case. When you do check the box, here's the email Salesforce sends.
    • (TBD)

Caveats

  • ...


Design and Build Your App

"Discover the architectural concepts that influence AppExchange solution design. Learn how to plan, build, and package your solution for customers."

Basics 

  • A Salesforce solution is assembled using a set of components that are distributed together in a package. 
    • There are over a hundred components available and most can be packaged. 
    • Packages come in three flavors: unmanaged, managed, and unlocked., 
      • Unmanaged packages are intended to be used for toolkits that are heavily customized and never upgraded. 
        • Unmanaged packages are generally example "lab" or "starter" solutions. 
      • Managed packages included a mix of components that can and cannot be upgraded. 
        • The trade-off is that upgradeable components cannot be customized by the customer (or "subscriber").
        • Managed packaged are intended to be distributed through the AppExchange by Salesforce partners.
      • Unlocked packages are a hybrid in that they can be customized and also upgraded but customizations may be overwritten.
        • Unlocked packages are intended to be used by in-house developers. 
        • Technically, unlocked packages are part of Second Generation Packaging but included here for completeness.
  • Controlling who sees what. Originally, Salesforce was designed for sales teams, and keeping users out of each other's business is a prime concern. 
    • Salesforce offers a rich permission scheme ... 
    • Permission Sets and Profiles ....
  • SObjects, Lightning, Flows ...
    • Open Data Schema ...
    • External IDs ...
  • Apex Code and Apex Unit Tests ...
    • Trigger Frameworks ...
    • Global API Design ...
    • Align Test Classes and Test Methods with the classes and methods under test.
      • Use "Test" as a file name suffix, so that it Begins with the same name as the class under test.
      • Test the class and not the story or the platform.
    • Selenium/Nightwatch test4s ...
  • Feature Management. ...
  • Package Documentation ...
  • Extension Packages ...

Tips - Design 

Tips - Architecture

Tips - Build

  • Use a Enterprise Password Solution, Like LastPass. ...
    • Establish a Naming Convention for Org Users ...
  • For shared remote access, use a Google Voice number and text though Slack ...
  • Use Version Control and an Issue Tracker. ...
    • Indicate an Issue Tracker ID in every commit. ...
    • For packages with patch orgs, prepare for multiple master branches ..
    • Use Naming Conventions to Link Jira Projects with Bitbucket Repositories. 
      • For Naming Conventions, Publish Early and Publish Often. 
    • For packages, version control must be the source of truth. Avoid direct changes to the packaging org. Limit access to key personnel. 
      • If you are not  using DX, deleting a packaged component from source doesn't delete it from the packaging org ...
      • Depending on the component, deleting it from the pakaging org might not delete it from the subscriber org. 
  • Consider using the Agile Accelerator ...
    • Alternatively, the Atlassian Suite is a comprehensive Agile platform. Jira, Bitbucket, and Confluence work well together and do a surprising amount of auto-wiring. ...
  • Don't enable Critical Updates in your packaging org ... (Internal NimbleUser Link)
    • Not all updates are presented in all orgs ...
  • Level 3 Permission Set Packaging Restrictions. If you'd like to keep the profiles simple, another approach is to create an unmanaged permission set with the Record Type and System Permissions that we can't package. You can then direct deploy the permission set, and patch it in future releases.

Tips - Test

  • ApexLink is a SFDX CLI plugin & Java library for static analysis of Salesforce Apex code aimed at improving developer productivity. The core library is useful for any number of analysis problems while the CLI plugin acts as a demo of capability while the features of the library are built out.
  • Parallel Unit Testing. This custom SFDX CLI command first runs the tests in parallel and then mops up any of those tests that fail with the infamous UNABLE_TO_LOCK_ROW by running them again.
  • Apex Cov. Maintaining a well-tested codebase is mission-critical. apexcov generates public Apex test coverage reports for your Force.com open-source projects.

Caveats

  • Apex Test Tour. ...Here's an idea to squash the bugger. (TBD)
  • Retrieving Profiles .. Managed and Unmanaged ...
  • Permission Sets cannot be removed from a package or edited by subscribers.
    • System Permissions and RT Visibility cannot be packaged, and so have to be set in some other way.
  • Permission Sets, before and after v40 ...
  • Packaging Base Permissions in an Extension Package ...
    • Profile merging ...
  • LX Gaps are still a thing - https://help.salesforce.com/articleView?id=lex_gaps_limitations.htm


Package and Test Your Solution

"Learn how to package, upload, and install a beta version of your solution as part an iterative development approach. After your beta is up and running, learn how to test, fix, extend, and uninstall the solution."

Tips

  • Deleting in Git is one thing, deleting in an org is another ...
  • Review New Components Before Upload. 
    • Review From Git. ...
    • Review From Package Details. ... 
  • Review New Dependencies After Upload.
    •  (TBD)
  • Use SFDX to automate as much as possible. (Don't be seduced by point-and-click!) ...
  • Use SFDX with P1 Packaging by Converting Metadata during a Build ...
  • Custom Labels are implicitly packaged. Depending on the context,  you may need to build a class that references your custom labels explicitly to be sure they are included. (TBD)
  • Selenium and Nightwatch ...
  • Be flexible with Namespace transformations ... VF Upper, LWC lower.
  • Removing components ...
    • L3: A related approach is to change the label on the component to indicate it's deprecated and otherwise leave it be.
  • Use Company Name to indicate role of a test org. ...

Caveats

    • Betas are not Upgradeable ... Refresh and redeploy data ...
      • Can't be installed in Trials ...
    • Beta Packages and Extension Packages. Not supported ...
    • Audit the Audit Trail ...


Pass the Security Review

"At Salesforce, nothing is more important than the security and success of our customers. To distribute a solution on AppExchange, it must pass our comprehensive security review. Learn how to design a solution security strategy and prepare for the security review."

Basics 

  • ...

Tips 

  • ...

Caveats

  • ...
  • Security Scans ...


Publish Your Offering on the AppExchange

"You turned an idea into a solution and are ready to get it in front of customers. To publish your solution on AppExchange, use the AppExchange publishing console. The publishing console is where you create a listing for your solution, connect orgs, manage license settings, and view analytics for your published listings."

Basics 

  • ...
  • On an ongoing basis, Salesforce indicates that "(TBD)".

Tips

  • ...

Caveats

  • ...


Manage Orders

"Create, manage, and submit orders to the Partner Operations team with the Channel Order App (COA). "

Basics 

  • ...

Tips 

  • ...

Caveats

  • ...


Manage Licenses

"Learn how to use the License Management App (LMA) to manage leads and licenses for your AppExchange solutions, and how to provide administrative support for your customers."

Basics 

  • ...

Tips 

  • ...
  • Link the License Record to your customer's Account Record...
  • Subscriber Console ...

Caveats

  • ...
  • Community Licensing ...


Provide a Free Trial of your Solution 

"Maximize customer adoption by offering free trials of your solution on AppExchange. Explore the types of trials available and determine the best type for your solution."

Basics 

  • ...

Tips 

  • Trialforce blackout ...
  • Adjust Sample Data to Follow the Trialforce Date Arithmetic ...
    • You might want to provision more than one TSO on the same day, in case you need to replace it, or want another one for a different purposes. In this way, you can share the same date-orientated data.
  • Use Trialforce for Customer Sales Demos. ...

Caveats

  • TSO Limits.
    • (TBD)
  • Trialforce Pivot Date. ... See this Idea for more (TBD)


Support Your AppExchange Customers

"After you publish a solution on AppExchange, you’re responsible for the end user support. Even when you’ve built the best solution the world has ever seen, customers need your help from time to time."

Basics 

  • ...

Tips 

  • ...
  • Patching Profiles and Permission Sets ...
  • Handling Uncaught Exception Emails. ...
  • (L3)
    • Consider Trialforce for Customer Org Jumpstarts ...
    • Consider Metadata Backups ...
    • Consider Nightly Apex Test Runs ...
    • Consider direct support for sample data in your custom objects ...
    • NimbleLand ...

Caveats

  • ...


Update Your Solution

"Your packaged solution is ready for an update. Learn how to fix small issues with patches and make major changes with upgrades."

Basics 

  • ...
  • Retain Backwardly Compatibility. 
    • Required fields 
      • (TBD) Back-filling defaults with an installation script.

Tips 

  • Deprecation. ...
  • Production upgrades are more strict that sandbox upgrades. In your deployment jobs to production, you can't specify certain settings, such as TestMode=NoTestRun, and you have to specify others, such as rollBackOnError=TRUE.
  • Document Admin User for Internal Orgs in the Organization Name. Many of us use various standing orgs for development and testing purposes. If naming conventions can vary, you can document the username in the Organization field on the Company Information page. You can then see this field from the Environment Hub. (See also All Trials and TSO Orgs Expire.)

Tips - Patch Versions

  • Confirm Patches with an Affected Customer. Fixes that we patch out to the current release are usually created using internal development environments. If the fix is reported by a specific customer, it can be useful to upgrade that customer's environment, or staging environment first – just to be sure the fix actually resolves the issue. 

Tips - Upgrade Previews

  • L3 Upgrade Sandbox Orgs and Apex Hammer Testing ...

Tips - Push Upgrade Alternatives

  • Upgrade Button - Invokes a pull upgrade via metadara API ...
  • L3 Connected App - Schedule pull upgrades via connected app  ...

Tips - Updates

  • Layout changes ...
  • Picklist changes ...

Caveats

  • Compact layouts are upgradeable AND subscriber editable ...


Roles in the Application Lifecycle

This guide covers the entire lifecycle of a package application, so some of the topics might not be relevant to you. The following list has TLD topic suggestions by role.

  • As a product developer, you'll want to see the following pages:
    • ...
  • As a product owner or scrum masteryou'll want to see the following pages:
  • As a solution architect or implementation consultantyou'll want to see the following pages:
    • ...
  • As a release engineeryou'll want to see the following pages:
    • ...




From 

As a new ISV moving into Salesforce, are there any resources which gives a broad overview of what the end result should be? There's so much material for Salesforce that I find it hard to even sort through it all. If not, here's an explanation of our current understanding. Maybe some generous soul can help enlighten us a bit? :)

From what I've gathered, the end setup would look something like us having:

- An Env Hub org for managing our various orgs (is this our partner org?)

- A Dev Hub org for managing scratch orgs (done).

- Plenty of scratch orgs that are created and destroyed frequently, used for development only.

- A Sandbox org (what’s the purpose of this when we have scratch orgs?)

- A Packaging org for creating a namespace and managing packages, including betas and releases.

-  A License Management org (not sure of the purpose?).

- A GitLab CI (we use GitLab) setup for testing and deploying to the Packaging org.

- A managed package project that can be developed and previewed on Scratch orgs, that can be deployed to the Packaging org, and can be submitted to AppExchange.

- Anything else I might have missed?

... and what is the convention when you start working on a new package? Do you create a managed package immediately, or do you start with an unmanaged and convert it to a managed one upon finalizing the package?

Finally, is the most efficient way to develop features for a package to spin up a scratch org, then push the source, then add a Lightning component to a page, then work on the feature in the developer console, and then pull the source back?

We're using the Falcon CLI, but open for any suggestions to change.

Thanks in advance for any help! It is highly appreciated!

Best regards, Jesper


Working with Support

Even when you’ve built the best solution the world has ever seen, you need help from Salesforce from time to time."

Basics 

  • Available forums ...
  • Known Issues ...
  • Routine cases ...
  • If you are not a partner ...

Tips

  • Ask questions the smart way ...
  • The simplest example that can possibly break ...
  • Let the Success Agent close the case. When resolving the case, the Success Agent can indicate a specific resolution code that can be lost if your close the case yourself.


Related content

Open Guide to SF Solution Packaging (1GP)
Open Guide to SF Solution Packaging (1GP)
More like this
Open Guide to Salesforce Home
Open Guide to Salesforce Home
More like this
Individual Contributor License Agreement
Individual Contributor License Agreement
More like this
Welcome
More like this

DreamOps Content and Source Code is licensed under the Apache License 2.0 (https://opensource.org/licenses/Apache-2.0).
Linked content and images are the property of the respective copyright holders.