How To Use A Salesforce Managed Package Admin Panel

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.

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.

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.

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 step and 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.

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 for each significant configuration aspect of your app in a 'parent admin panel.’

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.

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.

A monitoring section can include the following:

• The number of API calls used in an external service
• Remaining licenses
• The number of records created for your app’s custom objects
• A page view counts if you include a component on your Lightning Record Pages to log user visits.

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-up with 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.