Skip to main content

Dassault Cameo

Note: Users must procure and maintain valid licenses to integrate this commercial DE tool with the Istari Digital platform. Please contact your local IT administrator for assistance.

Supported Functions:​

extract
update

Getting Started​

The Cameo integration provides support for Cameo Enterprise Architecture and Cameo Systems Modeler, allowing users to extract data from and modify .mdzip files or connect directly to Teamwork Cloud (TWC) projects via a metadata link or file.

Versions Supported​

info

Supported versions (2024x-refresh2, 2022x-refresh2 or 2021x-refresh2)

Exact functionality may vary by version, so please ensure you are using a compatible version of Cameo Enterprise Architecture or Cameo Systems Modeler. Istari Digital strives to maintain the same functionality across all supported versions, but some features may be version-specific.

Upload: Yes (local *.mdzip)​

Teamwork Cloud (TWC) Projects​

Istari Digital can now connect directly to projects stored in Dassault Teamwork Cloud. Two operations are available and behave exactly like their local-file counterparts:

FunctionDescription
@istari:twc_extractExtracts diagrams, blocks, requirements, stereotypes, etc. from a TWC project.
@istari:twc_update_tagsUpdates/clears/appends stereotype tagged-values inside a TWC project.

1.1 Choosing a Connection Method​

  1. Paste a TWC link in the Istari Web UI – the platform will create the required metadata file automatically, or
  2. Upload a metadata file (*.istari_teamwork_cloud_metadata_mdzip) that you create yourself (see next subsection).

1.2 Creating the metadata file manually​

Save the following JSON as
my_project.istari_teamwork_cloud_metadata_mdzip and upload it:

{
  "project_id": "twcloud:/ac084d05-6bc2-4447-aa9f-51c9aa8f4679/6fc8e2dd-755d-40de-943f-d9d1ff716a2b",
  "branch_name": "trunk",
  "version": "12",
  "server_name": "10.30.102.103"
}

Field requirements

  • project_id or project_name – at least one is required (use only one if possible).
  • server_name – required (IP or DNS of the TWC server).
  • branch_name – optional (defaults to the project’s main branch).
  • version – optional (omit to grab the latest).
info

Tip: If you copy a URL from the TWC Web app (mdel://...?projectID=twcloud:/...&projectName=...) change every + in the projectName= segment to a space before using it as project_name in the metadata file.

1.3 Authentication – auth_secret.json​

TWC uses BASIC authentication. Create a file named auth_secret.json on the same machine as the Istari Digital Client to create a Job.

{
  "username": "your_username",
  "password": "your_password"
}

Add it as an AuthSecret with the relationship identifier twc_auth_login.

from pathlib import Path
from istari_digital_client import FunctionAuthType, NewSource

def add_auth_source() -> NewSource:
    if not Path("auth_secret.json").exists():
        raise FileNotFoundError("auth_secret.json is missing")

    secret = client.add_function_auth_secret(
        path="auth_secret.json",
        function_auth_type=FunctionAuthType.BASIC,
    )

    return NewSource(
        revision_id=secret.revision.id,
        relationship_identifier="twc_auth_login",
    )

1.4 Using the TWC Functions​

To use the TWC functions, you need to run a Job with the appropriate function name and parameters.

# 1. Add (or link) the TWC model
model = client.add_model(
    "my_project.istari_teamwork_cloud_metadata_mdzip"
)

# 2. Launch an extract job
twc_extract_job = client.add_job(
    model_id=model.id,
    function="@istari:twc_extract",
    tool_name="dassault_cameo",
    tool_version="2022x Refresh2",
    operating_system="Windows 11",
    sources=[add_auth_source()],          # << authentication
)
print("Started TWC extract:", twc_extract_job.id)

1.5 Running @istari:twc_update_tags​

@istari:twc_update_tags works exactly like the local-file
@istari:update_tags function:

job = client.add_job(
    model_id=model.id,
    function="@istari:twc_update_tags",
    tool_name="dassault_cameo",
    tool_version="2022x Refresh2",
    operating_system="Windows 11",
    sources=[add_auth_source()],     # << required for TWC login
    parameters={"updates": updates}  # << same schema as in the Cameo example below
)

@istari:twc_update_tags is invoked identically to the existing update_tags example—just change the function name and ensure sources=[add_auth_source()] is supplied.

info

Result of an update on Teamwork Cloud

When you run @istari:twc_update_tags the updated project is committed back to Teamwork Cloud as a new version.
Istari then imports that commit as a new version of the same model ID— no separate “updated_model.mdzip” artifact is produced.

What this means for you • If you run another @istari:twc_extract job on the model, the extraction will operate on the freshly-committed version.
• There is nothing to download; simply re-fetch the model with updated_model = client.get_model(model.id) to work with the latest revision inside Istari.

info

Need a full example of the updates array? Scroll down to the section titled “Using the update_tags Function”—the JSON and Python samples there apply unchanged to Teamwork Cloud projects.

Files Supported​

The istari Digital Platform can extract from the following file types: .mdzip

All other Cameo file types not supported at this time. Please submit a feature request if an important file type is not supported.

Example Files​

Setup for Administrators​

info

Prerequisites & Setup steps for administrators to configure the Cameo integration with the Istari Digital Platform.

Ensure that Cameo Enterprise Architecture or Cameo Systems Modeler (support versions) is installed on a Virtual Machine (VM) or standalone server alongside the Istari Digital Agent and the appropriate Istari Digital software. Verify that the installation is up to date with the latest patches and updates from Dassault.

License Notes for Admins​

This integration supports both floating and node-locked licenses. For floating licenses, ensure that the license server is properly configured and accessible from the machine running the Istari Digital Agent. The integration will attempt to check out a license from the first available server in the server_hosts list specified in the module configuration file.

For node-locked licenses do not include the server_hosts key in module_config.json; the module will use the local license file instead of contacting a server.

Setup - Module (Version 3.0.0+)​

Deprecated Configuration

Starting with cameo-module 3.0.0 and istari-agent 9.8.0+, the old configuration variables (cameo_installation_path, server_hosts, lmutil_executable_path, license_name) are deprecated. While they remain supported for backward compatibility, we strongly encourage using the new standardized configuration variables and the centralized istari_digital_agent_module_configurations approach for module configuration.

The Istari Agent is configured via the file istari_digital_config.yaml. The Agent expects the file to be located at:

  • %LOCALAPPDATA%\istari_digital\ on Windows
  • ~/.config/istari_digital/ on RHEL/Ubuntu

Configure the Cameo module using the istari_digital_agent_module_configurations section. The agent will pass this centralized configuration to the module. Note that Cameo supports version-specific configuration:

agent:
  istari_digital_agent_module_configurations:
    "@istari:dassault_cameo":
      "2021x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2021x/installation/dir"
        "dassault_cameo_license_server_hosts": ["27000@localhost", "28000@secondary.server.com"] # optional
        "dassault_cameo_license_manager_executable_path": "/path/to/lmutil/executable" # optional
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt" # optional
      "2022x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2022x/installation/dir"
        "dassault_cameo_license_server_hosts": ["27000@localhost", "28000@secondary.server.com"] # optional
        "dassault_cameo_license_manager_executable_path": "/path/to/lmutil/executable" # optional
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt" # optional
      "2024x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2024x/installation/dir"
        "dassault_cameo_license_server_hosts": ["27000@localhost", "28000@secondary.server.com"] # optional
        "dassault_cameo_license_manager_executable_path": "/path/to/lmutil/executable" # optional
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt" # optional

Legacy Configuration (module_config.json)​

For backward compatibility, you can still use the legacy module_config.json file located at {istari_agent_dir}\istari_modules\dassault_cameo\cameo_module_{version}\app\resources\module_config.json:

{
  "dassault_cameo_install_dir": "/path/to/cameo/installation/dir",
  "dassault_cameo_license_server_hosts": ["27000@localhost", "28000@secondary.server.com"],
  "dassault_cameo_license_manager_executable_path": "/path/to/lmutil/executable", // optional
  "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt" // optional
}
caution

This file contains essential configuration parameters for the module to function correctly.

Configuration Parameters​

Each configuration parameter serves a specific purpose:

  • dassault_cameo_install_dir: Specifies the absolute path where Cameo is installed on the machine. This is required for the module to locate and interact with the Cameo software.
  • dassault_cameo_license_server_hosts: (Optional) An array of license server connection strings, each in the format "PORT@SERVER" (e.g., ["27000@localhost", "28000@secondary.server.com"]). If not provided, the module will use the default configured license server or node-locked license. The module will attempt to check out a license from the first available server in the list.
  • dassault_cameo_license_manager_executable_path: (Optional) Path to the lmutil executable for floating license management. If not provided, defaults to <dassault_cameo_install_dir>/lib/lmutil.exe.
  • dassault_cameo_license_name: (Optional) The license name to check out. If not provided, defaults to "CameoEnterpriseArchitectureEnt".

Function Coverage and Outputs​

The Cameo software can produce a number of artifacts extracted from the Cameo model. The table below describes each output artifact and its type.

info

New Enhancement: The @istari:extract function now includes Tags, Stereotypes, and Profiles for Blocks and Requirements. This helps users easily identify available tags and stereotypes for use with the update_tags function.

RouteCoverageArtifact Content Example
Function: @istari:extract:Yes
Extract all diagrams - PNG
Extract cameo blocks - JSON
Extract cameo requirements - JSON
Function: @istari:update_tags:Yes
Input - update_tags_input - JSON

Detailed SDK Reference​

Prerequisite: Install Istari Digital SDK and initialize Istari Digital Client per instructions here​

Step 1: Upload and Extract the File(s)​

Upload the file as a model​

model = client.add_model(
    path="example.mdzip",
    description="Cameo example model",
    display_name="Cameo Model Name",
)
print(f"Uploaded base model with ID {model.id}")

Extract once you have the model ID​

extraction_job = client.add_job(
    model_id  = model.id,
    function  = "@istari:extract",
    tool_name = "dassault_cameo",
    tool_version = "2022x Refresh2",
    operating_system = "Windows 10",
)
print(f"Extraction started for model ID {model.id}, job ID: {extraction_job.id}")

Please choose appropriate tool_name, tool_version, and operating_system for your installation of this software.
Above is an example of how to call the function

Step 2: Check the Job Status​

extraction_job.poll_job()

Step 3: Retrieve Results​

Example​

for artifact in model.artifacts:
    output_file_path = f"c:\\extracts\\{artifact.name}"

    if artifact.extension in ["txt", "csv", "md", "json", "html"]:
        with open(output_file_path, "w") as f:
            f.write(artifact.read_text())
    else:
        with open(output_file_path, "wb") as f:
            f.write(artifact.read_bytes())

Using the update_tags Function​

The update_tags function allows users to programmatically update, append, or clear stereotype tagged-values (attributes/metadata) on elements within Cameo models. This is particularly useful for digital thread workflows where results from Istari Digital Platform workflows need to be saved back into Cameo Enterprise Architecture.

Function Overview​

  • Function Name: @istari:update_tags
  • Tool Name: dassault_cameo
  • Supported Versions: 2021x Refresh2, 2022x Refresh2, 2024x Refresh2
  • Supported OS: Windows 10 / 11, Windows Server 2019 / 2022
info

Note: The update_tags function supports updating tags on all types of Cameo elements, including Requirements, Blocks, Diagrams, and more. When tags on these elements are updated, any diagrams referencing these elements will automatically reflect the updated tag values upon opening the updated model in Cameo.

Input JSON Schema​

The input JSON file specifies the elements and tags you want to update. Each JSON object in the array represents one element to update:

[
  {
    "element_id": "_2021x_2_38b206bc_1744829804820_164896_3864",
    "replace_existing": true,
    "tags": {
      "VerificationStatus": "Fail",
      "Logs": null
    }
  }
]

Schema Explanation:

  • element_id (string, optional): Internal Cameo element ID. Recommended when element names are not unique.
  • element_name (string, optional): Human-readable name of the element. Either element_id or element_name is required.
  • replace_existing (boolean, optional, default=true):
    • true: Overwrites existing tag values.
    • false: Appends to multi-valued tags without overwriting existing values.
  • tags (object, required): Key-value pairs representing the tags to update.
    • Set a tag value to null to clear it.

Example​

Here's a complete example of how to use the update_tags function with the Istari Digital SDK:​

Step 1: Upload the Cameo Model​

model = client.add_model(
    path="Table Example.mdzip",
)
print(f"Uploaded model with ID {model.id}")

Step 2: Define the Update Parameters​

updates = [
    # Example 1: Replace existing tags (default behavior)
    {
        # Using element_id for precise targeting
        "element_id": "_2024x_2_abc12345_1750033427003_556537_1234",
        "tags": {
            "VerificationStatus": "Verified",
            "Priority": "High",
            "Owner": "John Doe"
        }
    },

    # Example 2: Append to a multi-valued tag without overwriting existing values
    {
        # Using element_name for readability (ensure uniqueness)
        "element_name": "System Requirement - Battery Life",
        "replace_existing": False,  # explicitly set to False to append
        "tags": {
            "RelatedDocuments": "Battery_Specifications_v2.pdf"
        }
    },

    # Example 3: Clear existing tags by setting their values to null
    {
        "element_id": "_2024x_2_def67890_1750033427003_556537_5678",
        "tags": {
            "DeprecatedTag": None,  # clears the existing value
            "ObsoleteReference": None
        }
    },

    # Example 4: Mixed operation (replace some tags, clear others)
    {
        "element_name": "Subsystem Block - Navigation",
        "tags": {
            "Status": "In Progress",  # replaces existing value
            "LastReviewed": None      # clears existing value
        }
    },

    # Example 5: Append multiple values to multi-valued tags
    {
        "element_id": "_2024x_2_xyz98765_1750033427003_556537_4321",
        "replace_existing": False,
        "tags": {
            "Stakeholders": ["Alice Smith", "Bob Johnson"],  # appends multiple stakeholders
            "ReviewDates": ["2024-01-15", "2024-02-20"]      # appends multiple dates
        }
    }
]

Explanation of Examples:

  • Example 1 (Replace by Default):

    • Updates the tags VerificationStatus, Priority, and Owner. Existing values are overwritten.

  • Example 2 (Append):

    • Adds a new document reference to the multi-valued tag RelatedDocuments without removing existing references.

  • Example 3 (Clear Tags):

    • Clears the values of tags DeprecatedTag and ObsoleteReference by setting them explicitly to None.

  • Example 4 (Mixed Operation):

    • Updates the tag Status with a new value and clears the tag LastReviewed.

  • Example 5 (Append Multiple Values):

    • Appends multiple new entries to multi-valued tags Stakeholders and ReviewDates.

Step 3: Run the Update Job​

job = client.add_job(
    model_id=model.id,
    function="@istari:update_tags",
    tool_name="dassault_cameo",
    tool_version="2022x Refresh2",
    operating_system="Windows 11",
    parameters={"updates": updates}
)

print(f"Update job started, job ID: {job.id}")

Step 4: Check Job Status & Retrieve Results​

from time import sleep
from istari_digital_client import JobStatusName
# Wait for the job to complete
while True:
    job_status = client.get_job(job.id).status.name
    print(f"Current job status: {job_status}")
    if job_status in (JobStatusName.COMPLETED, JobStatusName.FAILED):
        break
    sleep(5)
# Retrieve final job status
job = client.get_job(job.id)
if job.status.name == JobStatusName.COMPLETED:
    print(f"Update job {job.id} completed successfully!")

    # Retrieve the updated model version created by the update_tags function
    updated_model = client.get_model(job.model.id)

else:
    print(f"Update job {job.id} failed with status: {job.status.name.value}")

Troubleshooting​

  1. For general Agent and Software Troubleshooting Click Here
  2. Missing Artifacts:
    • 2.1 requirements.json: Check source file, are there requirements in the file? If not, refer to the software's manual for defining appropriate requirements.
    • 2.2 diagram.png: Check source file, does it contain any diagram?
  3. Issues with update_tags function:
    • Ensure the element_id or element_name matches exactly what's in the Cameo model.
    • Verify that the tags, stereotypes, and profiles exist in the model.
    • Check the JSON schema carefully for syntax errors.
  4. TWC authentication errors
    • Verify auth_secret.json path and that it is attached with relationship_identifier="twc_auth_login".
    • Confirm the username/password by logging into TWC Web with the same credentials.
  5. Cannot find project
    • Double-check project_id or project_name and server_name in the metadata file.
    • If copied the project_name from URL, remember to convert + to spaces.

FAQ​

  • Is this usable for other versions of Cameo Enterprise Architecture?
  • Can I use update_tags to clear existing tags?
    • Yes. Set the tag value to null in your input JSON to clear the tag.