Upgrading Unlocked Agentforce Packages

This guide outlines important considerations for existing users who need to upgrade their Bullhorn Agentforce unlocked package to a newer version. Agentforce is used in our AI offerings, like Amplify Screener.

Before you upgrade your Agentforce Packages, ensure that you have Installed & Configured Agentforce. For more details, see Getting Started: Installing & Configuring Agentforce.

Key Considerations Before Upgrading

When upgrading to a newer version of an unlocked package, it's critical to understand how your existing customizations will be affected.

  • Topics and Custom Actions: These components are not versioned. This means that if you have modified any of the topics or actions included in the package, the upgrade process will overwrite your changes. It is essential to back up your customizations before performing any upgrade.
  • Prompt Templates: Unlike topics, prompt templates are versioned. When you upgrade the package, the active version of a prompt template will be replaced by the one included in the new installation.

How to Back Up Your Customizations

Before you begin an upgrade, you must back up your modified Topic Instructions and Actions. Several methods are available for this:

  • Manual Backup: Manually copy and paste the instructions from any topics you have modified into a separate text editor.
  • Salesforce CLI: A developer can use the Salesforce Command Line Interface (CLI) to retrieve the package metadata from the org.
    • Copy

      Shell

      sf project retrieve start –packages “BHRC Agentforce for Professionals”
  • Workbench: You can use Workbench to export data.
  • Salesforce Inspector or Data Loader: You can use tools like Salesforce Inspector or Data Loader to export and back up the SObjects where the data is stored. The most important objects to back up are:
    • GenAiPluginDefinition: Stores the main Topic Definition, excluding the instructions.
    • GenAiFunctionDefinition: Stores the Action definitions.
    • GenAiPluginInstructionDef: Stores the Topic Instructions.

How to Resolve Common Upgrade Issues

This section helps you resolve common issues that may occur during or after the upgrade process.

  • If your active prompt template changed to a default version: The upgrade process automatically sets the newly installed prompt template as the active version. Your previous custom version should still be available but will be inactive.
  • If the package upgrade fails with a permissions error: Ensure the administrator performing the upgrade has all the necessary permissions. While the document mentions the Prompt Template Manager permission set is required for uninstalling, it's a logical prerequisite for managing package components during an upgrade as well.

If you encounter additional problems, our guide to Troubleshooting Agentforce Responses can help.

FAQ

This section answers frequently asked questions about the Agentforce upgrade process.

Q: Do I need to back up my customizations before upgrading?

A: Yes, this is a critical step. Because topics and custom actions are not versioned, any modifications you've made will be overwritten by the upgrade. Backing them up is essential.

Q: What's the difference between how Topics and Prompt Templates are handled during an upgrade?

A: Topics and actions are not versioned, so they are completely replaced by the new package version. Prompt Templates are versioned, so the upgrade simply installs a new version and sets it as the active one, while your older custom versions are typically retained.

Q: How can I back up my custom topics and actions?

A: You can perform a manual backup by copying and pasting your topic instructions into a text editor. For more comprehensive backups, a developer can use Salesforce CLI or you can use tools like Workbench, Salesforce Inspector, or Data Loader to export the SObjects where this data is stored.