• Get Started
  • Documentation
  • Samples
  • Blog
  • Pricing
    • Table of contents
    Overview
    Samples
    Changelog
    Grouping and Mapping
    Download API definition:

    Grouping and Mapping API

    The Grouping and Mapping API is a tool for reimagining your iModel data in a more concise, precise, and optimized representation for any variety of downstream applications. Specific solutions built on top of iModels often do not require the full breadth of the contained data, and different solutions often require redundant configuration steps to filter iModel data down to the needed subset. With the Grouping and Mapping API you can define any number of Mappings, Groups, and Properties as a one-time, reusable configuration that codes a reduced view of the data which can then be reused as configuration across all applicable workflows.

    Mappings

    Mappings can be seen as logical containers for each ‘reduced view’ - a set of Groups - of iModel data you are interested in. For example, a Mapping could be a set of Groups organizing elements by material or discipline. A Mapping could be a set of Groups with properties crafted for EDP (Environmental Product Declarations) workflows like material and quantity. Mappings are transferable. Once a Mapping is defined, it can be shared across an organization, across all iModels.

    Groups

    Each Mapping can contain any number of Groups. Each Group defines a different subset of the iModel data. Revisiting the EPD workflow example, a Group can be made for all concrete elements with Properties defined for volume and concrete grade. Another Group can be made for all steel beams with Properties defined for section and length. Continuing this pattern, a generic set of iModel element Groups can be defined that creates an optimized representation of the iModel data for a particular set of use cases. The same Groups defined for EPDs could also be used for other workflows such as generating Procurement reports or whatever else – only limited by the creativity of the user. The tedious configuration task required to know what data to pull from the iModel can be performed once and shared across workflows with this convenient set of APIs.

    Properties

    If a Group is thought of as a Table of data, Properties are the Columns. The Grouping and Mapping APIs provide an interface to define a set of Properties for each Group. Properties come in several flavors.

    • Mapped Properties are the most basic. They are derived directly from property data in the iModel. For example, if the element contains a value for volume, it can be mapped to your Group using a Mapped Property.
    • Calculated Properties can be used to augment the iModel element data. If Group elements are missing various mass properties such as Volume, Area, Length, etc., a Calculated Property can be used which will augment your iModel data by calculating the value for you during Data Extraction.
    • Use Custom Calculations if there is a need for even more sophisticated data augmentation. Custom Calculations allow users to define new Properties by writing short code snippets that can use other Properties on the same Group as variables. For example, if a user have access to properties for volume and density, they could calculate ‘weight’ with a Custom Calculation.

    Note: Taking full advantage of Calculated Properties and Custom Calculations requires use of the iTwin Platform Reporting APIs and its Data Extraction workflows. The values of these Properties are not resolved until after Data Extraction is run.

    Typical Workflow

    Client Packages

    Open-source TypeScript packages are available for the Grouping and Mapping API:

    Media Links

    Additional information can be found here: