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.

  • Published 04 Jun 2024
  • 8 mins read
How to use a Salesforce managed package admin panel
Table of contents

Hutte Expert Panel

Manuel Moya
Manuel Moya
Salesforce DevOps Consultant & Application Architect
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
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 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.

⚙️
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 for each 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.

Image Source: Kanban

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.

Image Source: Salesforce 

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.

Image Source: Typeform

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.
Image Source: Typeform
🌩️
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.

Image Source: Drive Connect 

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.


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.

Last updated: 11 Jul 2024