This endpoint is used to create a configuration for align iModel data transformation.

Align iModel data transformation provides the capability of remapping element EClasses and their ECProperties, and performing modifications on dynamic ECSchemas. Dynamic schema modifications include the removal of unused ECClasses and merging multiple ECClasses into a single ECClass.

Configuration specific properties explained:

schemaOptimizationOptions - options that will modify ECSchemas.
    - removeUnusedClasses - if `true` ECClasses that have 0 elements will be removed from all **dynamic** ECSchemas.
    - classMergingGroups - array of ECClass merging group objects.
        - sourceECClasses - array of ECClass objects. Classes in this array will be merged into a single target ECClass. All class elements will also be remapped into the target ECClass.
            - ecClassName - ECClass name.
            - ecSchemaName - ECSchema name.
        - targetECClass - target ECClass. all sourceECClasses will be merged into this ECClass.
            - ecClassName - ECClass name.
            - ecSchemaName - ECSchema name.
dataRemappingOptions - options for data remapping.
    - additionalECSchemas - array of Bentley defined ECSchemas that will be imported into the target iModel
        - ecSchemaName - ECSchema name.
        - ecSchemaVersion - ECSchema version.
    - elementGroups - array of element group objects. Each object in the array defines a collection of elements to be mapped into a single target ECClass.
        - targetECClass - a target class for the elements selected by the `elementPropertyQuery` to be remapped into.
            - ecClassName - ECClass name.
            - ecSchemaName - ECSchema name.
        - elementPropertyQuery - ECSql query that selects element ECInstanceIds and any additional properties.

Target ECClass

---

If targetECClass does not exist in the source iModel its schema must be imported using the additionalECSchemas property.

Element Property query

---

The elementPropertyQuery must be a valid ECSql statement. The only requirement for the query is that it must select ECInstanceId column. Elements with these ids will be remapped into the targetECClass. Any additional column the query returns is treated as an additional property. Given that the additional property's column name and an ECProperty in the targetECClass name match, its value will be carried through and will be exported as that ECProperty's value in the target iModel. Column names for ECProperties are case insensitive.

Example

---

ArchitecturalPhysical.Door ECClass has 3 ECProperties defined - OverallHeight, OverallWidth and Description. To remap all Generic.PhysicalObject elements that have "door" in their UserLabel to an ArchitecturalPhysical.Door ECClass, a valid elementPropertyQuery would be:

• SELECT ECInstanceId, 'This element was remapped from PhysicalObject' as Description, 15 as OverallHeight FROM Generic.PhysicalObject WHERE UserLabel LIKE '%door%'

Remapped elements in the target iModel would have the following properties:

• Description: 'This element was remapped from PhysicalObject'
• OverallHeight: 15
• OverallWidth: NULL
• ...

Original properties will be carried through from the original element and any properties that do not exist in the target class will be lost.

To change already existing element property, select an already existing column. The following query will change all BisCore.PhysicalObject class element's user labels to 'Updated user label': SELECT ECInstanceId, 'Updated user label' as UserLabel FROM Generic.PhysicalObject

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.

Transformations service creates an Editing Channel with key IModelTransformations. All source iModel data is exported under a channel root subject named IModelTransformationsChannel. Read more about Editing Channels here.

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": {
        "dataRemappingOptions": {
            "additionalECSchemas": [{
                "ecSchemaName": "ArchitecturalPhysical",
                "ecSchemaVersion": "01.00.01"
            }],
            "elementGroups": [{
                "targetECClass": {
                    "ecSchemaName": "ArchitecturalPhysical",
                    "ecClassName": "Door"
                },
                "elementPropertyQuery": "SELECT ECInstanceId, 'remapped element' AS Description FROM Generic.PhysicalObject WHERE UserLabel LIKE '%door%'"
            }]
        },
        "schemaOptimizationOptions": {
            "removeUnusedClasses": true,
            "classMergingGroups": [{
                "targetECClass": {
                    "ecSchemaName": "DynamicSchema1",
                    "ecClassName": "GasPipe"
                },
                "sourceECClasses": [{
                    "ecSchemaName": "DynamicSchema2",
                    "ecClassName": "Gas_Pipe"
                }]
            }]
        }
    }
}

{
    "configuration": {
        "id": "00000000-0000-0000-0000-000000000000",
        "transformName": "Transformation name",
        "comment": "comment",
        "createdDateTime": "2021-08-02T14:51:33.6133333Z",
        "modifiedDateTime": "2021-08-02T14:52:33.6133333Z",
        "transformType": "AlignIModelData",
        "transformParameters": {
            "dataRemappingOptions": {
                "additionalECSchemas": [{
                    "ecSchemaName": "ArchitecturalPhysical",
                    "ecSchemaVersion": "01.00.01"
                }],
                "elementGroups": [{
                    "targetECClass": {
                        "ecSchemaName": "ArchitecturalPhysical",
                        "ecClassName": "Door"
                    },
                    "elementPropertyQuery": "SELECT ECInstanceId, 'remapped element' AS Description FROM Generic.PhysicalObject WHERE UserLabel LIKE '%door%'"
                }]
            },
            "schemaOptimizationOptions": {
                "removeUnusedClasses": true,
                "classMergingGroups": [{
                    "targetECClass": {
                        "ecSchemaName": "DynamicSchema1",
                        "ecClassName": "GasPipe"
                    },
                    "sourceECClasses": [{
                        "ecSchemaName": "DynamicSchema2",
                        "ecClassName": "Gas_Pipe"
                    }]
                }]
            }
        },
        "_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."
    }
}