8.2 Deploying Prompt Templates from Sandbox to Production
Key Takeaways
- By default, prompt templates deployed with change sets arrive inactive, and you must activate them manually in the target org.
- The Deploy Prompt Templates setting in Einstein Setup auto-activates versions that are active in the source org, and it applies only to change set deployments.
- A change set deploys all template versions unless the Deploy Only the Active Template Version setting is enabled.
- Published versions are immutable, can't be modified by a deployment, and templates can't be deleted with a change set.
- Einstein Search retrievers aren't included in change sets or Metadata API deployments, and a custom LLM configuration must exist in the target org under the same name.
8.2 Deploying Prompt Templates from Sandbox to Production
Quick Answer: Prompt templates move between orgs as GenAiPromptTemplate metadata through change sets, the Salesforce CLI (Metadata API), or packages. Deployment doesn't automatically activate templates unless the Deploy Prompt Templates setting is on, and that setting affects change sets only. Published (activated) versions are immutable, all versions deploy by default, referenced flows aren't auto-activated, retrievers don't travel with the template, and a custom LLM configuration must exist by name in the target org.
Activation Behavior with Change Sets
| Setting in Einstein Setup | Default | When enabled |
|---|---|---|
| Deploy Prompt Templates (Activate Prompt Templates on Deploy) | Disabled | Templates active in the source are automatically activated in the target; inactive ones deploy inactive. Change sets only, not CLI or package deployments |
| Deploy Only the Active Template Version | Disabled | Only each template's active version is deployed and inactive versions are skipped. The deployment fails if a template has no active version. Doesn't apply to managed packages |
With both settings disabled (the default), all deployed templates arrive inactive, and all versions (active or inactive) are included. Activate them manually in the target org.
How the two settings combine:
| Deploy Prompt Templates | Deploy Only Active Version | Result |
|---|---|---|
| Off | Off | All versions deploy; nothing auto-activates |
| On | Off | All versions deploy; versions active in source are activated |
| Off | On | Only the active version deploys; not auto-activated |
| On | On | Only the active version deploys and is auto-activated |
When Deploy Only Active Version is on and the version already exists in the target: a draft version's content is updated and activated, a published version's content isn't modified (only activation changes), and a new version is created if it doesn't exist. Existing versions in the target are never deleted.
Version and Lifecycle Rules During Deployment
- Activating a version changes its status from Draft to Published, and a published version can't return to draft.
- Published versions can't be modified. A deployment that tries to change one skips it.
- A version can't be deactivated while the template is in use unless another version is active, and an active version in use can't be deleted.
- Templates can't be deleted with a change set.
- If a template is overridden, users can't override it again with a change set, CLI, or Connect API.
- For CLI and package deployments, a template needs at least one version.
Dependencies That Commonly Break Deployments
| Dependency | Rule | What to do |
|---|---|---|
| Flows used for grounding (template-triggered prompt flows) | Flows aren't auto-activated by deploying the template. Running a template with an inactive flow errors at run time. Flows with Automatic Inputs make a deployment fail if a template references them | Build these flows with Manual Inputs, deploy the flow and template together, and if the deployment fails, deploy the flow first and then the template. Activate the flow in the target |
| Apex | Classes must exist in the target. In packages, Apex classes used by templates must be global | Include the classes in the deployment |
| Einstein Search retrievers and search indexes | Not included in change sets or Metadata API deployments | Manually create the retriever in the destination org before deploying (or use Data 360 data kits) |
| Custom LLM configuration | The target org must have a model with the same name, or the deployment fails | Create or confirm the model configuration in the target first |
| Resources in the change set | Salesforce advises adding all resources and then their dependencies | Use View/Add Dependencies in the change set |
| Flex template artifacts | Prompt Builder limitations say flex templates don't support importing or exporting flex-related metadata, including change sets that move flex-related artifacts | Validate the plan in a sandbox; use supported deployment methods and rebuild where needed |
Packaging Considerations (Partners and ISVs)
| Rule | Detail |
|---|---|
| Include published versions | Drafts can be added but aren't installed in subscriber orgs for managed packages. Don't package a template with no published version, or installation fails |
| Published versions are locked | Future changes to a published version are skipped during upgrade |
| Auto-activation | A published, active version that differs from the current one is auto-activated in the subscriber org |
| Custom models | Templates with custom models can't be packaged |
| Retrievers and data graphs | Not in packages. They're part of data kits in Data 360 |
| Einstein generative AI | Must be activated in the subscriber org, or installation fails |
| Overridable templates | Publishers can set <overridable>true</overridable> so subscribers create local override versions. Once installed, this setting can't be undone |
| Lightning pages | Packaging pages that reference templates needs Manage Prompt Templates, or the template is left out |
| 2GP builds | Assign the Prompt Template Manager permission set (EinsteinGPTPromptTemplateManager) to the build user |
Scenario Practice
| Scenario | Correct explanation or action |
|---|---|
| A change set deploys a template, but users can't run it in production | Templates arrive inactive by default. Activate manually, or enable Deploy Prompt Templates before the next change set |
| A CLI deployment doesn't auto-activate even though Deploy Prompt Templates is on | That setting applies only to change sets |
| A template runs in production but errors at run time | The grounding flow wasn't activated in the target |
| Deployment fails for a template that uses a flow with Automatic Inputs | Rebuild the flow with Manual Inputs, or deploy the flow first |
| Deployment fails with a model error | The target lacks a model with the same name as the custom LLM configuration |
| A retriever-grounded template deploys but returns no knowledge | The retriever wasn't created in the target org |
| A team wants to deploy only the version that's live today | Enable Deploy Only the Active Template Version |
Exam Traps
- Default change set behavior deploys all versions, inactive.
- "Deploy Prompt Templates" doesn't affect CLI or packages.
- Deployments never modify published versions or delete target versions.
- Retrievers and custom models are prerequisites in the target org, not deployment passengers.
A team deploys an active prompt template with a change set, and it arrives inactive in production. Which setting would have activated it automatically?
Which statement about the Deploy Prompt Templates activation setting is accurate?
A template grounded with an Einstein Search retriever is deployed to production with a change set. What must be done for grounding to work?
A prompt template deployment fails because it references a template-triggered prompt flow. What does Salesforce recommend?