Skip to main content

Dassault 3DExperience CATIA Module Name Change Migration Guide

Overview​

As of the January 2026 release (module version 1.3.2), the Dassault 3DExperience CATIA (v6) module has been renamed for improved clarity and consistency:

  • Old Module Name: @istari:dassault_3dexperience
  • New Module Name: @istari:dassault_3dexperience_catia

This guide walks IT administrators through the migration process to deprecate the old module and enable the new one for users.

Why This Change?​

The new naming convention better reflects the specific tool being integrated (CATIA within the 3DExperience platform) and aligns with Istari Digital's standardized module naming patterns.

Impact​

  • Existing Jobs: Jobs using the old module name will continue to work until the module is deprecated
  • User Permissions: Users will need to be granted permissions for the new module name
  • Configuration: Module configurations using the old name in istari_digital_config.yaml should be updated to use the new name

Migration Steps​

Prerequisites​

Before beginning the migration, ensure you have:

  • Istari Digital CLI version latest installed
  • Administrator access to the Istari Digital Platform
  • Appropriate credentials for the Istari Digital CLI (see CLI Setup Guide)

Step 1: Deprecate the Old Module​

Use the CLI to deprecate the old module version or the entire module.

Option A: Deprecate a Specific Version​

To deprecate only the current version (allows users on older versions to continue):

stari client deprecate-module-version "@istari:dassault_3dexperience" "1.3.2" "Replaced by @istari:dassault_3dexperience_catia" --yes

To deprecate the entire module and all its versions:

stari client deprecate-module "@istari:dassault_3dexperience" "Module retired - use @istari:dassault_3dexperience_catia instead" --yes
tip

The --yes (or -y) flag skips the interactive confirmation prompt. Remove it if you want to review the deprecation details before confirming.

Step 2: Install the New Module​

Install the replacement module from the customer Artifactory repository:

stari module install @istari:dassault_3dexperience_catia --repository customer-istari-modules

Install Specific Version​

To install a specific version (e.g., 1.3.2):

stari module install @istari:dassault_3dexperience_catia --repository customer-istari-modules --version 1.3.2

Step 3: Update Module Configuration (If Applicable)​

If you have centralized module configurations in istari_digital_config.yaml, update the module key:

Old Configuration:

agent:
  istari_digital_agent_module_configurations:
    "@istari:dassault_3dexperience":
      "dassault_3dexperience_install_dir": "C:\\Program Files\\Dassault Systemes\\B428"
      "dassault_3dexperience_product_attr_name": "PLM_ExternalID"

New Configuration:

agent:
  istari_digital_agent_module_configurations:
    "@istari:dassault_3dexperience_catia":
      "dassault_3dexperience_install_dir": "C:\\Program Files\\Dassault Systemes\\B428"
      "dassault_3dexperience_product_attr_name": "PLM_ExternalID"
info

Configuration parameters remain the same - only the module key name changes.

Step 4: Grant User Permissions​

After installing the new module, grant users permission to use it:

  1. Navigate to the Admin Users page:
    Go to https://your-instance.istari.app/admin/users

  2. Find the user who needs access to the module

  3. Click the three dots menu (⋮) on the right side of the user row

  4. Select the module dassault_3dexperience_catia and check the functions the user should have access to:

    • @istari:extract
    • @istari:extract_geometry
    • @istari:extract_parameters
    • @istari:extract_publications
    • @istari:update_parameters
    • @istari:macro_execute
    • @istari:batch_execute
    • @istari:variable_sweep

  5. Save the changes

Bulk Permission Grant

You can select the parent module checkbox to grant access to all functions at once.

Step 5: Notify Users​

Inform your users about the module name change. They will need to update any SDK scripts or API calls that reference the old module name.

For SDK Users:

# Old
extraction_job = client.add_job(
    model_id=model.id,
    function="@istari:extract",
    tool_name="dassault_3dexperience",  # OLD NAME
    tool_version="1.3.2",
)

# New
extraction_job = client.add_job(
    model_id=model.id,
    function="@istari:extract",
    tool_name="dassault_3dexperience_catia",  # NEW NAME
    tool_version="1.3.2",
)

For UI Users:

When running functions through the Istari Digital Platform UI, users should select "dassault_3dexperience_catia" from the Tool Name dropdown instead of "dassault_3dexperience".

Verification​

To verify the migration was successful:

  1. Check module installation:

    stari module list

    Verify dassault_3dexperience_catia appears in the list

  2. Verify deprecation:

    • Navigate to the Istari Digital Platform Admin panel
    • Check that the old module shows as deprecated

  3. Test a function:

    • Run a test extraction job using the new module name
    • Verify the job completes successfully

Troubleshooting​

Issue: "Module not found" Error​

Symptom: CLI returns an error stating the module doesn't exist

Cause: The module may not be published to the Artifactory repository yet, or you don't have access

Solution:

  1. Verify you're using CLI version 0.21.1 or higher: stari --version
  2. Check your Artifactory credentials are configured correctly
  3. Confirm the module version exists in Artifactory: https://istaridigital.jfrog.io/ui/repos/tree/General/customer-istari-modules/

Issue: Users Can't See New Module in UI​

Symptom: Users report the new module doesn't appear in the Tool Name dropdown

Cause: Permissions haven't been granted for the new module

Solution:

  1. Follow Step 4 above to grant user permissions
  2. Ask users to refresh their browser (hard refresh: Ctrl+Shift+R or Cmd+Shift+R)
  3. Verify the module is installed on the appropriate agent machine

Issue: Old Jobs Failing After Deprecation​

Symptom: Existing jobs using the old module name are failing

Cause: The old module was deprecated before users migrated their workflows

Solution:

  1. Temporarily undeprecate the old module using the CLI (contact Istari Digital support for instructions)
  2. Give users time to migrate their scripts and workflows
  3. Re-deprecate the old module after confirming all users have migrated

Getting Help​

If you encounter issues during migration:

Rollback Plan​

If you need to rollback the migration:

  1. Undeprecate the old module: Contact Istari Digital support for assistance
  2. Revert configuration changes in istari_digital_config.yaml
  3. Notify users to continue using the old module name
warning

Rollback should be a temporary measure. Plan to complete the migration during the next maintenance window.