Adding Post-Install Scripts To Second-Gen Managed Packages

Aug 29, 2025 by Marco 59 views

Hey everyone, let's dive into a common challenge when building second-generation managed packages: the post-install script. If you're anything like me, you've probably scratched your head trying to figure out the best way to run some code after your package is installed. It's super important, right? Think about tasks like setting up configurations, seeding data, or even just sending a welcome email to the new user. Well, I've got you covered, and we're going to walk through the process of getting a post-install script up and running in your second-gen managed package. We will also address those common questions you have like "How do I add a post-install script?" and "How do I make it work?"

Understanding the Role of Post-Install Scripts

Post-install scripts are your secret weapon for automating setup tasks after your managed package is installed in a customer's Salesforce org. They're like a welcome wagon, automatically getting things ready for the user. This helps ensure a smooth experience, reducing manual steps and potential errors. Think of them as the final touch, the last piece of the puzzle that makes everything work perfectly. Without them, you might have to instruct users to manually configure things, which can lead to errors or, let's be honest, just a bad user experience. So, what kind of stuff can you automate with a post-install script?

Configuration Setup: This is where you set up the main settings for your app. Stuff like configuring custom settings, enabling features, or setting up integrations.
Data Seeding: Need some initial data to get your app going? Post-install scripts can load in some baseline records. This is great for setting up default values or sample data.
User Management: You can automatically assign permission sets, create users, or update user profiles based on the installation org's needs. This automates a lot of the tedious work.
Notifications: Send a welcome email, or let the user know everything is set up. Great for keeping users informed and improving satisfaction.

Getting your post-install script working is a game-changer. It makes the user experience a lot smoother and reduces the chance of errors. Plus, it saves time for both you and your users. A well-crafted script is a sign of a professional, well-thought-out package. It's like a secret handshake between your app and the user, making sure everything is just right from the start. So, now, let's get into the nitty-gritty of how to set one up in your second-generation managed package.

Setting Up Your Post-Install Script: A Step-by-Step Guide

Alright, let's roll up our sleeves and build this thing. Here's a detailed, step-by-step guide to get you started with your post-install script in a second-generation managed package. We'll cover everything from the basics to some advanced tips and tricks. Ready? Let's go!

Create Your Apex Class: Your post-install script is essentially an Apex class that implements the InstallHandler interface. This interface has a single method, onInstall(InstallContext context). This is where your script's magic happens. When the package is installed, this method will be executed. This is where you'll put all the logic needed to configure and set up the org after installation.
Implement the InstallHandler Interface: In your Apex class, make sure it implements the InstallHandler interface. This is what tells Salesforce, "Hey, this is my post-install script." The interface enforces that you have an onInstall() method, where the real work occurs. The interface looks something like this:
```
global interface InstallHandler {
    global void onInstall(InstallContext context);
}
```
In your Apex class, it'll look like this:
```
global class MyPostInstallScript implements InstallHandler {
    global void onInstall(InstallContext context) {
        // Your post-install logic here
    }
}
```
Write Your Post-Install Logic: Within the onInstall() method, you'll write all of the code that needs to run. This could include DML operations, SOQL queries, setting custom settings, or whatever else you need. The InstallContext object provides information about the installation, like the org ID and the package version. The InstallContext will give you a variety of functions that will allow you to know important information like whether it is a new install or an upgrade. This is particularly useful if you want to make sure that you only execute your code once per install. This can also be helpful if you want to execute different behavior depending on how a package is installed. Here are a few common use cases:
- Setting up Custom Settings: Use CustomSetting.getOrgDefaults() to set initial values.
- Creating Records: Use DML operations (insert, update, delete) to create sample data or configurations.
- Assigning Permission Sets: Use PermissionSetAssignment to assign permission sets to users or profiles.
Package.xml Configuration: In your package.xml, you need to declare your Apex class as a component. This tells Salesforce to include your script in the package. Make sure the types section of your package.xml includes:
```
<types>
    <members>MyPostInstallScript</members>
    <name>ApexClass</name>
</types>
```
Replace MyPostInstallScript with the actual name of your Apex class.
Testing Your Script: Always, always test your script in a sandbox environment first. Install the package, and verify that everything works as expected. Check the logs, make sure records are created, and all configurations are set up correctly. Testing in a sandbox is crucial to identify and fix any potential issues before deploying to production. Without testing, you could break something for your customers. Make sure you test for both new installs and upgrades.

Advanced Techniques and Best Practices

Now that we have the basics down, let's explore some advanced techniques and best practices to make your post-install scripts even better. These tips can help you create more robust, user-friendly packages.

Error Handling: Always include robust error handling. Use try-catch blocks to catch any exceptions that may occur during the installation process. Log errors to a custom object or a debug log, so you can troubleshoot any issues that come up. Display helpful messages to the user. No one likes a mysterious failure!
Idempotency: Make your script idempotent, meaning it can be run multiple times without unintended side effects. Check if configurations already exist before creating them. This prevents errors and ensures your script works correctly during upgrades or re-installs. Idempotency is super important for ensuring that your post-install script works correctly in any situation.
Context Awareness: The InstallContext object gives you some useful info. Use it to determine if the package is being installed for the first time, or if it is an upgrade. This can help you run different logic based on the situation. This is helpful if you need to run certain operations on new installs, but not during an upgrade.
Asynchronous Operations: If your script needs to perform long-running operations, use asynchronous Apex (e.g., future methods, Queueable or Batchable Apex). This prevents your post-install script from timing out during installation.
User Notifications: Keep the user informed. After your post-install script is complete, consider sending a welcome email or displaying a custom message on a Visualforce page or Lightning Component to provide instructions or next steps.
Version Control: Version control your code. Keep your post-install script under version control with all the rest of your package components. Use a tool like Git to track changes, collaborate with others, and easily revert to previous versions if something goes wrong.

Common Issues and Troubleshooting

Even with the best planning, you might encounter some issues. Here's how to address some common problems.

Timeout Errors: Post-install scripts have a governor limit of 10 minutes. If your script takes longer, break it down into smaller parts using asynchronous Apex.
Permission Issues: Make sure your Apex class runs in the system context to avoid permission issues. Also, ensure your script has the necessary permissions to access and modify the Salesforce data.
Deployment Errors: Check the debug logs for any errors during deployment. Pay attention to any SOQL query limits, DML limits, or other governor limits that could be causing the problem.
Installation Failures: If the installation fails, check the Setup Audit Trail for details. Review the debug logs, and try to identify the cause of the failure. Try installing your package in a sandbox or developer org before pushing it out to the world.

Putting it all together

Let's walk through a quick, practical example. Here's a very basic example of a post-install script that creates a custom setting and populates it with some default values.

global class MyPostInstallScript implements InstallHandler {
    global void onInstall(InstallContext context) {
        // Check if custom setting exists, otherwise, create it
        MyCustomSetting__c setting = MyCustomSetting__c.getOrgDefaults();
        if (setting == null) {
            setting = new MyCustomSetting__c();
            setting.Name = 'DefaultSetting';
            setting.SomeField__c = 'Default Value';
            insert setting;
        }
    }
}

In this example:

We implement the InstallHandler interface.
The onInstall method runs when the package is installed.
We check if the custom setting already exists using getOrgDefaults() to prevent duplicates and ensure idempotency.
If the setting doesn't exist, we create and populate it.

This is a simple example, but it shows the basic structure. You can adapt this to create records, assign permission sets, and more.

Conclusion

Adding a post-install script to your second-generation managed package is a great way to create a great user experience and automate setup tasks. It's an awesome way to reduce manual steps and potential errors. So, embrace the power of post-install scripts, and make your managed packages shine. Remember to test thoroughly, handle errors gracefully, and always put the user first. If you have any questions, feel free to ask away! Happy coding!