How to use a Salesforce managed package admin panel
Our trail on the “dos and don’ts of managed packages” suggested including a custom admin panel to give your users a central place for configuring your application.
Manuel Moya Ferrer is a highly skilled freelancer who serves as a technical architect, developer, and DevOps engineer. He specializes in Salesforce solutions, covering all technical aspects of their development lifecycle.
Matthias Rolke
Freelance DevOps Consultant
Matthias is a freelance DevOps consultant for the Salesforce platform and an advisor for Hutte. He loves open-source software and maintains a few SFDX-related tools.
Article Highlights
The admin panel is a centralized space for Salesforce admins to manage app setup, customization, and monitor end customers’ usage.
Emphasizes creating a single source of truth, keeping information up-to-date and searchable, and adhering to “DRY” (don’t repeat yourself) coding practices.
Recommends designing for at least two personas, a junior to mid-level admin new to the tool, and a mid to senior-level admin familiar with it, to ensure a smooth experience for all users.
In this part of the trek, we’ll:
Step into the details of what precisely an admin panel is
Share our design principles
Suggest build approaches
Reference some of our favorite examples.
What is an admin panel?
An admin panel is a page in your app dedicated to the person or team configuring your customer’s org.
Much of an admin’s work lives behind the scenes, yet it is critical to enabling the rest of the organization’s success.
An admin needs to:
Understand and carry out the steps to set up your app
Know how to customize it
Stay in the loop for updates
Keep track of your end customers' usage.
💬
The admin panel collects all the resources for the above needs and makes them accessible in a centralized space.
Salesforce admins often influence or decide which AppExchange solutions their org will implement. Any friction during the setup can deter Salesforce from choosing your app. Their ability to configure it can make or break your end customers' experience.
We strongly recommend investing in design and development to make it shine as much as the UI your end-customers see. Let’s start with the core principles that drive design decisions.
Design core principles
Provide a single source of truth
Give admins one place they trust will have the information they need for your app and can access the levers they need to configure it.
Admins rely on up-to-date and accurate information about the nuts and bolts spread across an org to succeed in their daily work. They need to keep up with Salesforce’s:
Release schedule
Configuration nuances between different teams
Level of risk of hitting governing limits
Custom applications have been built or installed over the years.
☝️
Salesforce often switches contexts between the above components within a day. When Salesforce context switches your app, make sure the admin panel is the first place they think of going to. Ensure you keep the information in your panel comprehensive, up-to-date, and searchable.
Keep it “DRY”
To balance the principle above, you must remember that providing a single source of truth for admins doesn’t necessarily mean building a custom UI for every aspect they can configure.
We emphasize ensuring ‘access’ to configuration features and taking note of “DRY” (don’t repeat yourself) coding practices.
For example, instead of building a custom UI to grant access to parts of your app – describe the permission sets or permission set groups an admin can use. You can additionally provide a link to Salesforce’s standard permissions management area.
🙌
If you have custom scripts that make metadata changes, include content about what the scripts do, links to the areas they update, and how the admin can achieve the same results manually.
Ensure you also include links to the page layout and Lightning Record Page sections for your app’s objects. These sections show admins where they can customize how end-users view a record.
Personas
We recommend designing with at least two personas in mind that represent your admin panel’s core users:
Persona one: A junior to mid-level admin that’s new to your tool
Persona two: A mid to senior-level admin familiar with it.
Including features for both types of admins provides a smooth experience for the range of admins setting up your app.
Wizards guide an admin through each stepand serve persona group one by ensuring they cover every part of the setup. It also learns about its configuration options along the way.
A dashboard UI with tabs and links to the configuration options serves persona group two. These admins already know what they need to change and require quick access to perform operations.
⚙️
A dashboard aims to remove UI friction that would slow admins down in accessing the levers they need to work with.
Salesforce’s Data Import Wizard and Data Loader exemplify two solutions that do the same thing for different personas. Data Import Wizard provides a step-by-step guide for a less experienced admin in persona group one. At the same time, Data Loader exposes the tools a power user in persona group two needs.
Flexibility
When you release version one of your app, your development team will have a backlog of fixes and improvements for the next release. These changes may include new ways to configure your app, leading to admin panel updates.
Keep this in mind when architecting your admin panel’s front end and designing the page to grow and change with newer versions.
For example, architect your LWCs or Aura components with single components foreach significant configuration aspect of your app in a 'parent admin panel.’
📄
This enables you to add or remove elements from the parent as features change. If the UI gets full, you can rearrange the configuration components into tabs, accordions, or separate pages.
ISVs also need to consider the differences between primary and patch releases. Major releases give more flexibility when adding and modifying code. These updates need an admin to install the release manually.
If you're an ISV having a Managed Package which has passed the AppExchange security review you can use the "Push Upgrade" feature to upgrade the package version in the orgs having installed your package. Warning: You should be confident to not break things and your customer should have agreed to this.
Matthias Rolke
Freelance DevOps Consultant
Patch releases are automatically installed, but they limit the changes you can make to code. To learn more about patch releases, refer to this in-depth article by Vimal Tiwari on Medium.
To expand on the example above, you can temporarily architect your LWCs for patch releases by creating a section in your ‘admin panel code' to park a new configuration UI component.
Patch releases can’t add new features, but they can change them. Make sure to include the new code in the temporary space with a process to migrate it to its component for the next major release.
In practice
While every app has its configuration needs, we’ve compiled a list of potential tools that could live in your admin panel to inspire you when designing your solution.
Configure metadata
Configuring your app may rely on custom metadata, settings, and objects to tweak features to meet your customers’ specific use cases.
Rather than requiring an admin to seek out each configurable parameter across different sections, consider exposing a UI to edit or access them directly in your admin panel.
A custom Lightning page can use ListView components to manage custom object records. You can use Salesforce’s Flow component or Apex to modify custom metadata in the UI.
As an example, Kanban’s custom UI configures metadata objects. It removes an admin’s need to memorize all the details about their org’s objects by providing a tailored input that dynamically searches an object’s fields.
Launch scripts
Scripts combined with metadata, tooling, and REST API are a great way to automate steps to configure your app. An admin panel is a fitting place for documentation and buttons to launch them.
We suggest including a description of the script's changes, a preview of the sample code or metadata updates, and instructions on how to undo the outcome.
For example, Declarative Lookup Roll-Up Summary’s script launcher deploys trigger code. It shows the changes it will make and gives you options to undo them.
Connect integrations
Methods to connect to external systems vary from app to app. That’s why admins need to remember how their org communicates with a range of tools at their company.
If your package needs to integrate with external systems, we recommend designing your admin panel to include the steps to connect and authenticate into them.
With security in mind, we recommend including a UI to disconnect and revoke access to and from an integration.
For example, Typeform’s admin panel includes a custom UI to guide an admin through connecting Salesforce to its external application.
Monitor usage
Monitoring your app’s usage helps it stay within Salesforce’s governing limits and inspires improvements. ISVs and admins can leverage information about how end-users interact with their app as input when requesting customer feedback or building a backlog of feature changes.
For example, Salesforce’s Lightning Usage App panel includes sections about page views, browsers, logins, and other helpful information to identify organizational improvements.
Contact support
Give your admins a quick way to ask your support team questions or provide feedback with contact information.
For example, Drive Connect’s “Contact Support” button on its admin panel opens a pop-upwith a form to send a message directly to its team.
The moral of the story
Admin panels serve as guided tours of your app’s configuration details for newbies and as a reference and toolkit for power users. It makes the discrete parts of your app accessible from one place.
We recommend investing in user experience to configure your app just as much as you put in the work to architect, design, and build its core features.
Spring Release Updates
OmniStudio Support
Managed Packages now support features from OmniStudio for Vlocity, such as XML publish options for FlexCards and tracking usage of OmniStudio components.
Migration Assistance
Provides tools for migrating all versions of OmniStudio components, aiding in the transition to newer Salesforce releases.
Managed Package Runtime
Introduces the Standard setting for Managed Package Runtime, which, when disabled, allows access to OmniStudio features previously exclusive to Vlocity.
Enhanced Functionality
Managed Packages continue to enhance Salesforce’s robust portfolio of products, enabling more efficient development and deployment of applications.
Harald is the Co-Founder of Hutte, bringing his vision of no-code DevOps to life. His passion enables teams and individuals to focus on what matters most – bringing value to the users they build for.
