Reducing Manual Setup Steps for AppExchange Apps
Many apps on AppExchange require users to go through lengthy post-installation instructions and documentation to configure the app across various Salesforce UI sections.
Since Salesforce and its setup capabilities are very verbose, end users often need to complete multiple manual steps to configure an app.
In this post, I’ll share some tips on minimizing post-installation steps and making them easier for customers.
Package Everything You Can
This is obvious, but I must mention it. If something is packageable, include it in the package. Period. To check whether specific metadata can be packaged, reference the Salesforce Metadata Coverage Report, which is updated every release.
Post-Install Script
You can run Apex logic when a customer installs or upgrades your package. This is useful for tasks such as:
- Scheduling jobs
- Populating default values for custom settings
- Resetting or setting feature parameters
- Assigning permissions automatically
You can also implement version-specific logic. For example, if your app starts collecting data in a new custom field from version 3.0, your script can migrate data from the old field to the new one – only if the upgrade is from a version lower than 3.0.
Note: The Post-Install Script runs in the context of a special system user representing your package, not the user who initiated the installation.
Post-Install Script Limitations
Key limitations of post-install scripts:
- They can’t access session IDs.
- They can’t call Apex classes that use
with sharingorinherited sharing. - They can only perform callouts asynchronously (e.g., via a
@Futuremethod).
For more details, see this Salesforce documentation article.
How to Create and Specify the Post-Install Script
- Create an Apex class that implements the
InstallHandlerinterface. Place your logic in theonInstallmethod. See this example for reference. - For second-generation (2GP) packages, specify your post-install script class name in the
sfdx-project.jsonfile. See an example here.
For first-generation (1GP) packages, specify it in Setup → Package Manager.
Prepare a Dedicated Setup UI
PDF documents attached to an AppExchange listing may be sufficient for the MVP phase.
However, If you have development capacity, consider creating a Setup page in your app that guides the customer through post-installation steps and tracks their completion. It’s much easier for admins to see everything in-app rather than scrolling through separate instruction documents.
Here’s an example from our ISV Analytics app:
The UI might look complex to build, but it’s not! SLDS includes ready-to-use utility CSS classes for the Setup Assistant component – check them out here.
Save Completion State
Add "Mark as Complete" and "Mark as Incomplete" buttons near setup steps to track completion. Use a custom setting in your package to store this status.
You can take this a step further by automatically verifying whether a step has been completed. For example, you can check if at least one user has been assigned your packaged permission set to confirm the Permissions Assignment step is complete. However, this requires more development effort and may not be feasible for all steps.
Use Rich Text with Links
Instead of plain text instructions like:
"Go to Setup → Permission Sets and select the XYZ permission set",
use lightning-formatted-rich-text to display formatted instructions with clickable links to relevant Salesforce Setup pages (e.g., for Permission Sets, use "/lightning/setup/PermSets/home").
This reduces clicks and improves the admin experience.
Generate Dynamic Links
You can further improve the experience by dynamically generating links to specific metadata.
For example, instead of instructing admins to: "Go to Setup → Permission Sets → XYZPermset and click ‘Manage Assignments’",
generate a direct link to the permission set assignment page: /lightning/setup/PermSets/permsetId/PermissionSetAssignment/home
Query the permission set ID, construct the URL, and provide a button on your setup page. Now, the instruction simplifies to:
"Click the button below to assign the XYZ permission set to users."
This reduces admin effort and minimizes confusion.
Automate What You Can
If you have development bandwidth, automate as many manual steps as possible.
For example, instead of asking admins to manually create a Named Credential, create it programmatically.
Or, instead of directing them to Setup → Custom Setting → YourCustomSetting → Edit, provide an input field and save the value in a custom setting automatically.
I’m sure you get the idea. 😉
Utilize In-App Guidance
Although not strictly related to reducing manual steps, In-App Guidance minimizes documentation and helps onboard customers within the app itself.
Starting with the Spring ’25 Release, In-App Guidance prompts can be included in second-generation managed packages (they’re already available for 1GP). No excuses now! 😉
Here’s an example from our app:
To learn how to create In-App Guidance, see this documentation.
Flow Templates
Sometimes, customers need to create a Flow after installation to get value from your app, but you can’t include this Flow in your package since it’s org- and use-case-specific.
To save admins time, provide a Flow Template in your package.
This is just a Flow saved as a template – it includes common logic and placeholders for customer-specific details.
Admins can then start with your template instead of building a Flow from scratch.
Conclusion
There are several ways to reduce the number of manual steps required for managed package configuration.
While eliminating them entirely may not always be possible, we can at least improve the user experience.
Use the techniques in this article to make setup smoother for your customers.
That’s it for today. If you have any questions related to Salesforce AppExchange, don’t hesitate to contact me directly (https://linkedin.com/in/bartosz-suchocki) or anyone on our amazing team (https://linkedin.com/company/beyondtheclouddev).
