Skip to main content

External proxy elements

Available in product editions: ArchitectProfessional

Introduction​

An external proxy element is a model element whose original data is managed in a system outside the workbench — for example an issue tracker or a wiki. You place it on the canvas so that information from that system can take part in the design: you can relate it to other elements, document what matters here, and let the Design Assistant use it as context.

The external proxy element is a representation in your model. It does not replace the object in the external system, and the workbench does not take ownership of that object.

External proxy element types are not a fixed catalogue shipped with the product. You declare them in an OML profile by setting baseType to external-proxy-element, then choose the properties and relationships the design actually needs.

What you can do​

  • Keep external objects in the model. Create instances like other model elements: on the canvas, from the model elements overview, or through the Design Assistant. They appear in overviews, details, and diagrams in the same way.
  • Define the types yourself. In the OML profile you decide which external concepts exist as element types and which properties they carry. That can follow the source closely (for example separate types for epic, story, and bug) or stay coarser (for example one requirement type that gathers several source items).
  • Point back to the original source. Link properties are a good fit on external proxy elements for fields that open the original object — for example a source property with the URL of the work item or page.
  • Connect them to the rest of the design. You can define relationship types between external proxy element types, and between external proxy element types and other element types, whenever those connections are needed for design work.
  • Use them with the Design Assistant. External proxy elements are first-class model elements. The assistant can read them, mention them, and take them into account when you ask it to extend or explain the design. Combined with MCP support, it can also fetch current information from a connected system and write the relevant fields onto an external proxy element.
  • Store them with the project. Each external proxy element is persisted in Git with the properties defined on its type, like any other model element.

Define external proxy element types​

Add element types to your OML profile with baseType: "external-proxy-element". Properties, style, layer, and status work the same way as for default-model-element. A link property is a good fit for pointing to the original source of the proxy (URL plus optional label); in the workbench it is shown as a clickable hyperlink.

elementTypes:
  - id: "ext.jira-story"
    name: "Jira story"
    description: "A Jira story that is relevant for this design. The original work item is managed in Jira."
    descriptionDetailed: "Use this type for a single Jira story that should appear in the model. Do not use it for epics, or for a requirement that gathers several Jira items."
    baseType: "external-proxy-element"
    layer: "business"
    propertiesSchema:
      - "jira-story-fields"

propertyGroups:
  - id: "jira-story-fields"
    name: "Jira story fields"
    properties:
      - fieldName: "source"
        displayName: "Source"
        description: "Opens the original Jira work item."
        type: "link"

The same profile can also define a coarser type, such as a requirement that accumulates data from more than one source item. Choose the types that match how you design, not necessarily how the external tool is structured. For a complete Jira walkthrough — Rovo MCP, the Basic Authorization header, and these proxy types in chat — see the Jira integration example.

For the field list and other baseType values, see the OML configuration reference.

Relationships​

Relationship types may include external proxy element types as source, as target, or both. Type mappings, cardinality, and style follow the same rules as for other element types.

Use this when the design needs an explicit connection — for example that a domain entity realises a requirement represented as an external proxy element, or that two external proxy elements depend on each other. If a connection is not needed for design, you do not have to model it.

See Relationships and relationship types in OML.

Design Assistant​

Because external proxy elements are ordinary model elements, the Design Assistant can:

  • Answer questions that involve them
  • Create, update, and delete instances in the current project
  • @ mention an external proxy element
  • Use them as context when you ask it to extend the design

Populating or refreshing an external proxy element from the external system is a design action, not a background job. Typical flow: @ mention the external system, ask the assistant to read the relevant items, and have it create or update external proxy elements with the properties your type defines.

Writing back to the external system is a separate MCP capability and is off by default. Editing an external proxy element in the workbench changes only the model.

Boundaries​

  • The source of truth for the original object remains the external system. The external proxy element holds the subset of information you chose to model.
  • There is no live replica. An external proxy element is Git-backed design data. It is not kept in lockstep with the source unless you (or the Design Assistant) update it.
  • Changing an external proxy element does not change the external system. Updates in the other direction require MCP write tools, which run only if your administrator allows them. See MCP support.
  • The product does not ship a ready-made vocabulary for a particular tool. Jira, Confluence, or any other system appear as external proxy element types only if your OML profile defines them.
  • You choose how much to represent. Unused source fields simply stay out of the model; several source items can be represented as one element if that is what the design needs.
  • External proxy element types are available in a project only when the project's baseline includes a profile that defines them.
  • MCP is not required to create or edit external proxy elements by hand. It is required if you want the Design Assistant to read the connected system while filling them.
  • A link property stores a URL (and optional label) in the model. Opening it goes to that URL; it does not refresh the element's other fields from the source.