Understand the data model

Most integration workflows start with a repository, then select a model and the information associated with it.

Repositories and models#

A repository is the main container for modeling content and related configuration. Its UUID becomes the repositoryId in paths such as /repositories/{repositoryId}/models.

A model is a diagram or visualization. Model metadata describes its identity, type, localized titles, version, and workflow state. Its canvas describes the diagram's visual contents.

Symbols, vertices, relations, and edges#

A symbol represents an underlying modeled object. A vertex is an item placed on a model's canvas; it always references a symbol and carries layout information such as position and size.

An edge connects vertices on a model's canvas and carries visual information such as routing and labels. The edge implicitly defines the relation between the modeled objects. There is no separate relation entity in the database or API.

The distinction between symbols and vertices matters when an object appears in several models. Changing a vertex's placement is different from changing shared symbol data, and removing a vertex is not necessarily equivalent to deleting its symbol.

Use the canvas walkthrough to inspect these structures.

One object, two placements#

In our fictional Process library, Handle an order includes a Customer symbol. The same Customer is reused in Dispatch an order:

The vertices have different identifiers and positions, but their symbol values identify the same Customer. The edge's endpoints identify vertices, not symbols. This lets the same object appear differently in different diagrams. On a narrow screen, scroll the diagram sideways.

Breakdowns#

A breakdown links a modeled element to a more detailed model, for example a high-level process to its subprocess diagram. Use breakdowns to build drill-down navigation or understand model hierarchies. Follow the returned model identifiers within their repository context.

Descriptions and documents#

A field, also called a description type in the API, is a configured property used to describe model or symbol content. These names refer to the same concept. Fields can have different types; values in fields of type rich text are generally called descriptions. These values can contain HTML and localized content.

Document references connect model content to documents. A document source identifies a provider; a document key identifies a document within that source. Treat source IDs and document keys as opaque values, not as interchangeable model UUIDs.

Provider properties are key/value data addressed by a provider identifier and a property key. They are distinct from configured fields (description types).

The reference also exposes custom relations, which define scripts, and plugin relations, which belong to plugin data. These uses of “relation” are separate from the modeled connections implicitly defined by canvas edges.

A reference to an external document does not itself guarantee access to that document's contents. See the document workflow.

Configuration and accessors#

Repository configuration supplies fields (called description types in the API), lists, matrices, and languages.

Application-key access differs from user permissions; read Authentication and access before exposing API data to end users.

Languages and localized values#

Repositories have a default language and can contain additional languages. Titles and descriptions can be maps keyed by language UUID, rather than by locale codes such as en.

For example, a model's titles map contains a title for each returned language. Additional-language entries can include a translated flag; a default-language value may omit it. Do not assume that every language has translated content, or force every flag to true.

Use the repository's languages to interpret the keys, and preserve the documented field structure when writing localized data. See localized requests.