Building Blocks
As you work with the Data Exchange REST APIs, you may come across the following terms. These outline how we refer to the Data Exchange building blocks, permissions, processing, revision management, and more.
Terminology
| Term | Definition |
|---|---|
| Collection | A group of data related to a particular customer or project. Collection ID is used to get data you have access to. |
| Exchange | A container that stores information about the data available within it. |
| Contract | Specification of how data is to be exchanged. |
| Host | The cloud environment where the exchange can be accessed. |
| Source | The document location from which the data is extracted for the exchange. |
| Fulfillment | A transaction where a data exchange is set up and performed, resulting in an exchange snapshot and version snapshot. |
| ExchangeSnapshot | Specification of what data is included in a given fulfillment, like a Git commit. |
| VersionSnapshot | The history of the exchange indicating what data was modified in a given version. |
| Asset | A data model object that represents the data being exchanged (example, instance asset, design asset, binary asset). |
| Relationship | A data model object that relates two or more assets to each other. |
| Component | A data model object that represents properties of an asset or relationship. |
| ModelStoreSpace | A storage location where assets and relationships are uploaded and versioned, like a Git repository. |
Architecture
Here is a high-level architectural diagram of the Data Exchange service.
In Detail
When working with Data Exchanges through our REST APIs, you may run into more specific terms and rich data types. These add onto the building blocks outlined above – assets, relationships, and components.
Assets
| Term | Definition |
|---|---|
| Instance Asset | Represents a Revit element |
| Design Asset | Represents a Revit element type, like a Wall type (can be used to store geometry) |
| Geometry Asset | Represents a geometry entity (BRep, Mesh, Line, Arc) |
| Binary Asset | Represents binary data, used to store the BRep and Mesh data |
| Group Asset | Represents Category / Family / Type classification |
| Render Style Asset | Represents color and transparency information - no material textures |
Relationships
| Term | Definition |
|---|---|
| Containment | Used for asset composition. Indicates the “From” asset, contains the “To” asset. |
| Reference | Used for entity association. Indicates the “From” asset, uses or, requires the “To” asset. |
Components
| Term | Definition |
|---|---|
| Base | Carries an ID, label, and revision from the source (Revit) application |
| Color | Includes RGBA information for diffuse color |
| Geometry | Indicates if a binary asset is a BRep or Mesh - or carries Forge Lines / Arc geometry |
| Parameter | Conveys the Forge parameter information |
| Transform | Fetches a Forge transformation matrix when duplicate instances are used |
| Unit | Bears a Forge unit schema (i.e., length, angle, and display units) |
| Hints: | The following components are added to relationships: |
| Hint - Model Structure | Indicates the child to be part of the model structure |
| Hint - Type | Indicates the child carries parameter information for the parent type |
| Hint - Sub asset | Indicates the child is used indirectly (i.e., a Geometry asset with a BRep binary asset depends on a render asset) |
Here is a view of how we represent the Data Exchange data model in the cloud, with many of the specific terms outlined above.
