This endpoint is used to create the Group And Map configuration.

The Group And Map transformation enables the creation of new custom EC schemas and is capable of remapping already existing elements to the new EC classes with new EC properties. The custom schema is constructed using grouping and mapping data. It is your responsibility to create a valid mapping for the source iModel through the Reporting API before starting the transformation. To learn more about EC schemas and classes, please see Base Infrastructure Schemas.

These are the logical relations from grouping and mapping data to EC schema:

Mapping -> EC schema
Group -> EC class
GroupProperty -> EC property

After the transformation all elements that were selected with the group query will be remapped to the corresponding EC class. These elements will also have all the new EC properties inserted. The newly inserted EC properties' values will be populated with the help of 'ecProperties' field taken from the respective GroupProperty which you configured beforehand.

POST configuration specific properties explained:

mappingId - source iModel mapping id.
groupOverrides - list of overrides for each group.
    - groupId - id of mapping group.
    - baseClass - base EC class that will be applied for elements selected by group.
        - ecSchemaName - EC schema name.
        - ecClassName - EC class name.
additionalEcSchemas - list of additional EC schemas that will be added to target iModel.
    - ecSchemaName - EC schema name.
    - ecSchemaVersion - EC schema version.

In addition to exported data, the transformer will also push some additional metadata. This metadata contains:

1. BisCore:RepositoryLink and BisCore:ExternalSource elements that mark the source where the data was imported from.
2. A "Scope" BisCore:ExternalSourceAspect that contains Synchronization changeset metadata that is needed by the transformation service to process any later changes correctly.
3. Element provenance information (BisCore:ExternalSourceAspects) for elements that do not have federation guids.

Note: Creating a configuration does not run the transformation. To run the transformation, please see transformations reference.

Authentication

---

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

---

You must have imodels_write assigned at the target project level and imodels_read assigned at the source project level within related configuration. If permissions at the project level are not configured, then you must have same assigned at the iModel level.

Alternatively, you must be an Organization Administrator for the Organization that owns a given project the iModel belongs to.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management see Bentley Communities Licensing, Cloud, and Web Services wiki page.

Rate limits

---

All iTwin Platform API operations have a rate limit. For more documentation on that visit Rate limits and quotas page.

{
    "transformName": "Example name",
    "sourceProjectId": "00000000-0000-0000-0000-000000000000",
    "sourceIModelId": "00000000-0000-0000-0000-000000000000",
    "targetProjectId": "00000000-0000-0000-0000-000000000000",
    "targetIModelId": "00000000-0000-0000-0000-000000000000",
    "comment": "Example comment",
    "transformParameters": {
        "mappingId": "00000000-0000-0000-0000-000000000000",
        "groupOverrides": [{
            "groupId": "00000000-0000-0000-0000-000000000000",
            "baseClass": {
                "ecSchemaName": "BisCore",
                "ecClassName": "PhysicalElement"
            }
        }],
        "additionalEcSchemas": [{
            "ecSchemaName": "BisCore",
            "ecSchemaVersion": "01.00.00"
        }]
    }
}

{
    "configuration": {
        "id": "00000000-0000-0000-0000-000000000000",
        "transformName": "Transformation name",
        "comment": "comment",
        "createdDateTime": "2022-05-20T14:51:33.6133333Z",
        "modifiedDateTime": "2022-05-20T14:52:33.6133333Z",
        "transformType": "GroupAndMap",
        "transformParameters": {
            "_links": {
                "mapping": {
                    "href": "https://api.bentley.com/insights/reporting/datasources/imodels/00000000-0000-0000-0000-000000000000/mappings/00000000-0000-0000-0000-000000000000"
                }
            },
            "groupOverrides": [{
                "_links": {
                    "group": {
                        "href": "https://api.bentley.com/insights/reporting/datasources/imodels/00000000-0000-0000-0000-000000000000/mappings/00000000-0000-0000-0000-000000000000/groups/00000000-0000-0000-0000-000000000000"
                    }
                },
                "baseClass": {
                    "ecSchemaName": "BisCore",
                    "ecClassName": "GraphicalElement3d"
                }
            }]
        },
        "_links": {
            "sourceIModel": {
                "href": "https://api.bentley.com/imodels/00000000-0000-0000-0000-000000000000"
            },
            "targetIModel": {
                "href": "https://api.bentley.com/imodels/00000000-0000-0000-0000-000000000000"
            },
            "sourceProject": {
                "href": "https://api.bentley.com/itwins/00000000-0000-0000-0000-000000000000"
            },
            "targetProject": {
                "href": "https://api.bentley.com/itwins/00000000-0000-0000-0000-000000000000"
            }
        }
    }
}

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

{
    "error": {
        "code": "IModelNotFound",
        "message": "Requested IModel is not available."
    }
}

{
    "error": {
        "code": "MissingRequestBody",
        "message": "Request body was not provided."
    }
}

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}