Common Errors and Resolutions in Omnistudio

1. Log in as a System Administrator.
2. From Setup, find and select Omnistudio.
3. Enable the Omnistudio permission for your org.

If you don't see the option, verify that your org has Omnistudio licenses. Contact your Salesforce Account Executive if licenses are needed.

Tip After enabling Omnistudio permissions, it may take a few minutes for the changes to propagate throughout your org. If you continue to see this error, try logging out and logging back in.

• Attempting to delete an active Omniscript
• Attempting to update structural fields on an active Omniscript
• Attempting to change Type, SubType, or Language on an active Omniscript

1. From App Launcher, find and select Omniscripts.
2. Locate the Omniscript you want to modify or delete.
3. Note the current version and warn users about the upcoming deactivation.
4. Deselect the Active checkbox to deactivate the Omniscript and save your changes.
5. Now you can make your desired changes or delete the Omniscript.
6. If you made changes, you can reactivate by selecting the Active checkbox again.

Warning Deactivating an Omniscript immediately affects all users and processes currently using it. Consider creating a new version instead of modifying the active one if you need to maintain service continuity.

• Another Omniscript with identical Type, SubType, and Language is already active
• Creating a new version without deactivating the previous version
• Multiple versions created and attempting to activate more than one

Make sure you have permissions to edit Omniscript records and complete these tasks.

1. From App Launcher, find and select Omniscripts.
2. Use filters or search for Omniscripts with matching Type and SubType.
3. Identify the currently active Omniscript with the same Type/SubType/Language.
4. Review both versions to determine which should remain active.
5. Open the Omniscript you want to deactivate.
6. Deselect the Active checkbox and save your changes.
7. Return to the new version and activate it.

Warning Before activating a new version, test it thoroughly in a preview or sandbox environment. When you’re ready to deploy, deactivate the old version and immediately activate the new one to minimize downtime.

• Type field is empty or null
• Subtype field is empty or null
• Language field isn't selected
• Attempting to save a new Omniscript without filling in all required fields

Make sure you have permissions to edit Omniscript records and complete these tasks.

1. From App Launcher, find and select Omniscripts.
2. In the Omniscript properties panel, locate the Type field.
3. Enter a descriptive Type name such as CustomerOnboarding or ClaimSubmission.
4. Locate the SubType field and enter a specific SubType name such as Residential or Commercial.
5. Select a Language from the dropdown.
6. Make sure all three fields are filled and save your changes.
7. Return to the new version and activate it.

Tip Choose meaningful Type and SubType names that clearly indicate the purpose of your Omniscript. These values become part of how you reference the Omniscript in your applications and can't be easily changed after they’re created.

• Type or Subtype fields contain spaces
• Type or Subtype fields contain underscores
• Type or Subtype fields contain unsupported special characters: !@#$%^&*, and so on
• Type or SubType fields contain hyphens or other punctuation

1. Review your Type and SubType values.
2. Remove any spaces - use UpperCamelCase (or PascalCase) instead. For instance, CustomerOnboarding.
3. Remove any underscores and replace them with UpperCamelCase (or PascalCase).
4. Remove any special characters.
5. Make sure that only letters (A-Z, a-z) and numbers (0-9) are used.
6. Save your changes.

Tip Use PascalCase (also called UpperCamelCase) for Type and SubType values. This improves readability without requiring spaces or underscores.

• Type value is too long.
• SubType value is too long.
• Combined Type + SubType + Language exceeds the character limit.

1. Review the error message to see the maximum allowed length.
2. Shorten your Type or SubType value.
3. Save your changes.

Tip Use abbreviations where needed. Remove redundant words. Use a shorter naming convention.

The Type or SubType field uses a reserved keyword. Common restricted keywords include: in, out, exc, cb, kt, vt, v, x785f, x5f

As suggested in the error message, replace the restricted keyword with a different value. See Reserved Words on the Omnistudio Naming Conventions page for more information.

• Attempting to add a new element to an active Omniscript.
• Attempting to modify an existing element on an active Omniscript.
• Attempting to delete an element from an active Omniscript.
• The Omniscript is active and in use.

Make sure you have permissions to edit Omniscript records and complete these tasks.

1. Verify if the Omniscript is currently active.
2. Consider creating a new version instead of modifying the active one.
3. To create new version: Click Clone on the Omniscript.
4. To modify existing: Deactivate by deselecting the Active checkbox and save your changes.
5. Now you can add, update, or delete elements.
6. Test your changes.
7. Activate the Omniscript when ready for use.

Warning It is recommended that you create a new version for significant changes rather than deactivating and modifying the active version. This allows you to test thoroughly before deploying and provides an easy rollback option if issues arise.

• Another element in the same Omniscript has the same name.
• Name collision between elements in different steps.
• The element was copied and name wasn't changed.

1. Review all elements in your Omniscript.
2. Identify the elements with the conflicting names.
3. Decide which element should keep the name.
4. Rename the other element with a unique name.
5. Consider using prefixes to indicate the step or section, for example, step1_firstName, step2_firstName.
6. Update any formulas or data mappings that reference the renamed element and save your changes.

• The Omniscript is from a managed package and you don't have permissions to modify or delete it.
• Attempting to update a packaged Omniscript from outside the package namespace.

1. Verify the if the Omniscript is from a managed package.
2. If you need to customize the Omniscript, clone it instead.
3. Rename the cloned version with your own Type/SubType/Language combination.
4. Make your desired modifications to the cloned version, save and activate your Omniscript.
5. Update any formulas or data mappings that reference the renamed element and save your changes.

Tip Contact the package provider or your Salesforce Administrator if you need to make changes to packaged components. They may provide configuration options or extension points that don't require modifying the packaged Omniscript directly.

• The Omniscript is reusable.
• The Omniscript contains Omniscript elements (embedded Omniscripts).
• Attempting to make an Omniscript reusable after adding embedded Omniscripts

1. Decide whether this Omniscript should be reusable or contain embedded Omniscripts.
2. Option 1: Keep it reusable - Remove all embedded Omniscript elements
3. Option 2: Allow embedding: Deselect the Reusable checkbox.
4. If you're removing embedded Omniscripts, consider using Integration Procedures instead. You can refactor the logic into Integration Procedures that can be called from the Omniscript.

Tip Use Integration Procedures for shared business logic instead of nesting reusable Omniscripts. This creates a cleaner architecture and avoids complexity in Omniscript dependencies.

• Another Flexcard with the same Name is already active.
• Attempting to activate a new version without deactivating the old one.

1. Search for Flexcards with the same Name field.
2. Review them to determine which should remain active.
3. Open the Flexcard you want to deactivate.
4. Deselect the Active checkbox to deactivate the Flexcard and save your changes.

Warning Deactivating a Flexcard immediately affects all users and processes currently using it. Consider creating a new version instead of modifying the active one if you need to maintain service continuity.

1. Verify the if the Flexcard is from a managed package.
2. If you need to remove it from use, deactivate it instead of deleting.
3. To do this, open the Flexcard and deselect the Active checkbox.
4. If you need a customized version of the Flexcard, clone it instead.

Tip Contact the package provider or your Salesforce Administrator if you need to make changes to packaged components. They may provide configuration options or extension points that don't require modifying the packaged Flexcard directly.

• The name of the child Flexcard name is misspelled.
• The child Flexcard exists but is not active.
• The child Flexcard was deleted.
• The child Flexcard is in a different namespace.

1. From App Launcher, find and select Note the child Flexcard name from the error message.
2. Search for the child Flexcard by name.
3. If found but inactive, activate it.
4. If not found, verify the correct name.
5. If name is incorrect, update the parent Flexcard configuration.
6. In the parent Flexcard, locate the child Flexcard reference.
7. Correct the name to match an existing, active Flexcard and save the parent Flexcard.

Note Child Flexcards must be activated before the parent Flexcard can reference them. Create and test child Flexcards first, then configure parent Flexcards to use them.

• The Omniscript’s Type/SubType/Language is incorrect.
• The Omniscript exists but is not active.
• The Omniscript was deleted.
• The Omniscript’s Type/SubType/Language was changed.

1. Note the Type, SubType, and Language from the error message.
2. Search for the Omniscript with matching Type and SubType.
3. Verify the Language matches.
4. If found but inactive, activate the Omniscript.
5. If not found, verify the correct Type/SubType/Language values.
6. Return to your Flexcard and update the Omniscript reference with the correct values.
7. Save your changes.

Tip Make sure that the referenced Omniscript is active before activating the Flexcard. If you're deploying both together, activate the Omniscript first.

• The name of the Data Mapper is misspelled.
• The Data Mapper exists but is not active.
• The Data Mapper was deleted.
• The Data Mapper’s name was changed.

1. Note the Data Mapper name from the error message.
2. Search for the Data Mapper by name.
3. If found but inactive, activate it.
4. If not found, verify the correct name.
5. Return to your Flexcard, update the Data Mapper reference with the correct name, and save your changes.

Tip Activate Data Mappers before activating Flexcards that reference them. Test the Data Mapper independently to make sure that it returns the expected data structure.

• The name of the Integration Procedure is incorrect.
• The Data Mapper exists but is not active.
• The Data Mapper was deleted.
• You’re using the wrong naming format (should use Type_SubType format).

1. Note the Integration Procedure name from the error message.
2. Search for the Integration Procedure.
3. Verify that it exists and note its Type and SubType.
4. If found but inactive, activate it.
5. Return to your Flexcard.
6. Update the Integration Procedure reference by using the format: Type_SubType, and save your changes.

Warning Integration Procedures are referenced using their OmniProcessKey, which follows the Type_SubType format. Make sure that you're using the correct format when configuring the Flexcard.

• Attempting to rename an existing Flexcard.
• Attempting to change the Author of an existing Flexcard.
• The UniqueName is used by other components and can't be changed.

1. If you need a different name or author, clone the Flexcard instead.
2. Locate your Flexcard and clone it.
3. Enter the new Name or Author.
4. Make any other necessary changes to the cloned version and activate your new Flexcard.
5. Update any components referencing the old Flexcard to use the new one.
6. Deactivate the old Flexcard once all references are updated.

• The Integration Procedure Name starts with FileBased.
• The Integration Procedure Type starts with filebased.
• The Integration Procedure SubType starts with FileBased.

1. Open your Integration Procedure.
2. Check the Name, Type, and SubType fields.
3. If any start with FileBased, choose a different prefix.
4. Consider using prefixes like File, Document, Data, or your organization name.
5. Update the error-prone fields and save your changes.

• The JSON input schema has nested objects deeper than 10 levels.
• The JSON output schema has nested objects deeper than 10 levels.

1. Review your JSON schema structure.
2. Identify deeply nested sections.
3. Flatten the structure by reducing nesting levels.
4. Consider moving deeply nested data to separate Integration Procedures.
5. Use arrays with flatter objects instead of deeply nested hierarchies.
6. Restructure to keep nesting under 10 levels.
7. Save the updated schema.

Integration Procedure JSON schemas have a maximum limit of 500 keys across the entire structure. This includes all keys at all nesting levels combined. Specifically:

• The JSON input schema contains more than 500 total keys.
• The JSON output schema contains more than 500 total keys.
• The schema includes large numbers of fields across multiple nested objects.

1. Review your JSON schema.
2. Count the total number of keys across all levels.
3. Identify sections with excessive keys.
4. Consider splitting the Integration Procedure into multiple smaller procedures.
5. Remove unused or redundant keys.
6. Use arrays to represent repeated structures instead of numbered keys.
7. Consolidate related fields into sub-objects.
8. Save the optimized schema.

Tip If you legitimately need more than 500 keys, consider breaking the process into multiple Integration Procedures that can be chained together.

• The selected sObject is not supported for Data Mapper operations.
• The selected sObject is a system object that doesn't support queries.
• The selected sObject doesn't have the necessary API support to work with Data Mappers.

1. Review the sObject you selected as the input type and check Salesforce Help for supported objects.
2. Consider using a different, related object that is supported.
3. If you need data from the unsupported object, use an Integration Procedure with custom Apex instead.
4. Update your Data Mapper configuration with a supported object and save your changes.

Note Most standard and custom objects are supported. If you encounter an unsupported object, consider whether you can restructure your data flow to use a supported alternative.

• OmniAnalytics for Omnistudio isn’t enabled.
• Your org hasn't been configured for OmniAnalytics.

1. Log in as a System Administrator and from Setup, search for Omnistudio Settings or Omni Interaction Configurations.
2. Locate the OmniAnalytics for Core setting and enable it.
3. Save your changes and wait a few minutes for the change to take effect.
4. Test if your analytics tracking works.

Note Verify that Decision Explainer is properly configured.

• The ID is not in valid Salesforce ID format, with 15 or 18 characters.
• The ID doesn't belong to the OmniTrackingComponentDef object.
• The tracking component definition was deleted.
• The ID is null or malformed.

1. Verify the component definition ID you're using.
2. Navigate to Setup > Omnistudio > Analytics Tracking and find the correct tracking component definition.
3. Copy the correct ID from the record.
4. Update your code or configuration with the correct ID.
5. If the definition was deleted, create a new tracking component definition. See Create a Tracking Group and Add Components to Track.
6. Test the tracking again.

Note Verify that Decision Explainer is properly configured.