This endpoint is used to create a configuration for a CreateFork transformation.

CreateFork transformation is used for establishing a (main <-> fork) relationship between 2 iModels and for synchronizing changes in the "forward" (main -> fork) direction.

The first time a CreateFork transformation is performed, a link is established between source (main) and the target (fork) iModels. The target iModel must be a clone of the source iModel. You can clone the existing iModel using iModels API's endpoints:

• Create iModel.
• Clone iModel.

Consecutive CreateFork transformations may be used to pull changes from the main iModel into the fork iModel.

To synchronize changes in the "reverse" (fork -> main) direction see MergeFork configuration.

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.

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.
• Forking and merging workflows do not support modifying the same entity in multiple iModels. There is no provided functionality to see conflicting changes or resolve them, so the transformation will use "last synchronization wins" strategy automatically. As a result, only the most recent synchronized changes made to an element will be retained, overwriting updates from earlier forks.

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"
}

{
    "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": "CreateFork",
        "_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."
    }
}