This endpoint is used to create CombineIModels configuration.

Combine IModels transformation combines the source iModel with iModels provided in transformation parameters. This is done by importing each source iModel into the target iModel sequentially. IModels are imported into the target in the same order that they were provided in (configuration.sourceIModel, configuration.transformParameters.iModels[0], configuration.transformParameters.iModels[1], etc.).

For every source iModel a BisCore:Subject is created in the target iModel. Each source iModel's contents are exported under their corresponding subject in the target. Subjects are named after their source iModels. Any possible naming conflicts are resolved by appending a number to the subject's name if needed (ex. Duplicate name 2).

Also, a new definition partition is created under new subject to persist all ViewDefinitions from source iModels, even if they have conflicting codes. This means that all ViewAttachment, ViewDefinition, ModelSelector, DisplayStyle and CategorySelector elements that are scoped under the dictionary model (id '0x10'), will be remapped under this newly created definition partition.

Element conflicts can occur when merging iModels (e.g. 2 subCategories with the same Element Code have different appearance props). In this case, every iModel in the import chain will keep overwriting the conflicting element effectively preserving the last value that was found. This means that the last iModel in the transformParameters.iModels list will take precedence. Only elements whose scoping hierarchy ultimately reaches elements with ids 0x10 (dictionaryId) and 0xe will be able to conflict with each other (most common cases are DefinitionElements). Any other elements that are ultimately scoped by the root subject will be imported under a new subject as mentioned above and cannot conflict (because their scope becomes unique).

The first Geo location that is found will be applied onto the target iModel. For example, if merging three iModels in this order:

1. iModel A (not geo located)
2. iModel B (geo location is BB)
3. iModel C (geo location is CC)

Target iModel will have geo location set to BB.

Configuration specific properties explained:

iModels - list of iModels to combine the source iModel with.
    - iModelId - id of iModel
    - projectId - id of project that iModel belongs to

Limitations:

• This API does not support combining iModels that have conflicting dynamic ECSchemas. Conflicting ECSchemas are two ECSchemas that have the same name, but have at least one difference such as: different aliases or any difference between EC object items (EC schema contents). For example, "CustomSchema" in iModel "A" has an ECClass "MyClass", while "CustomSchema" in iModel "B" doesn't have an ECClass "MyClass". In case of ECSchema conflict, transformation will fail with an error message. Those error messages might vary depending on the conflict that was encountered. Transformation status and it's error message can be retrieved by sending GET transformation request.

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": {
        "iModels": [{
            "projectId": "00000000-0000-0000-0000-000000000000",
            "iModelId": "00000000-0000-0000-0000-000000000000"
        }]
    }
}

{
    "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": "CombineIModels",
        "transformParameters": {
            "iModels": [{
                "_links": {
                    "iModel": {
                        "href": "https://api.bentley.com/imodels/00000000-0000-0000-0000-000000000000"
                    },
                    "project": {
                        "href": "https://api.bentley.com/itwins/00000000-0000-0000-0000-000000000000"
                    }
                }
            }]
        },
        "_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."
    }
}