This endpoint is used to create a configuration for an ImportIModel transformation.

Import iModel transformation imports data from source iModel to the specified target iModel. This data can either be the whole iModel, or data that is associated to a RepositoryLink element.

During the transformation a BisCore:Subject element is created. The subject's CodeValue is set to the source iModel's id and the UserLabel is set to the source iModel's name. All data from the source iModel is imported under the newly created subject. Because of this, multiple iModels can be imported into the same target iModel effectively combining them while avoiding most of the conflicts between the sources.

Element conflicts can occur when importing an iModel. In this case, elements of the iModel being imported overwrite the target elements. 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).

Importing the whole iModel

---

To import the entire source iModel into the target omit the transformParameters property from your request body.

Importing data associated to a RepositoryLink element

---

To import only the data that is associated to a RepositoryLink add the repository link's federation guid to the transformParameters.fedGuidsOfRepositoriesToExport array in the request body.
A RepositoryLink element represents a link to an external repository (e.g. a design file).
A federation guid identifies a real-world entity that the element represents and "federates" the element to its external meaning. It is used as a stable identifier that external systems can utilize to reference the element. More about federation guids here.

Transformations service relies on the correct provenance structure in the source iModel in order to process it correctly.

1. ExternalSourceAspects must reference ExternalSource elements by their Source navigation properties.
2. ExternalSource elements must reference their RepositoryLink elements by their Repository navigation properties.

Any elements that do not have an ExternalSourceAspect related to a RepositoryLink are considered "shared" between all repositories and are always imported. More information about provenance in bis can be found here.

Configuration specific properties explained:

fedGuidsOfRepositoriesToExport - federation guids of RepositoryLink elements.

Limitations:

• Only one repository link's federation guid per configuration is supported at this time.
• 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": {
        "fedGuidsOfRepositoriesToExport": ["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": "ImportIModel",
        "transformParameters": {
            "fedGuidsOfRepositoriesToExport": ["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."
    }
}