Creates a mapping for an iModel. There are two ways to create a mapping.

Create an empty mapping

---

To create an empty mapping do not provide the sourceMappingId property. This will create a new mapping that does not have any groups.

Create a mapping from an existing mapping

---

To create a mapping from another mapping provide the sourceMappingId property. The server will create a new mapping and copy over all of the groups with their properties from the mapping referenced by the sourceMappingId property. User must have imodels_read permissions to the iModel containing the source mapping. Changing source mapping, groups, or their properties will not change the copies of them.

Provided mappingName, description, extractionEnabled request body properties will overwrite the properties on the copied mapping.

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

---

User must have imodels_write permission(s) assigned at the iTwin level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin or iModel.

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 please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Extraction Triggers & Configuration

---

Mappings can be configured with extractionEnabled set to true or false. true means that extractions will be automatically executed for the given mapping when a ChangesetGroup is completed (see ChangesetGroupCompletedEvent). Note: Multiple ChangesetGroups can be completed for a single Synchronization job which will result in multiple automatic extractions.

If extractionEnabled is set to false, the automatic extractions are disabled. However, extractions can still be executed for a specific mapping manually using the Run Extraction operation and the mappings request body parameter. To have a better control over extractions, it is recommended to set extractionEnabled to false and manually trigger an extraction when a mapping's extracted data is stale and needs to be refreshed.

Rate limits

---

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

"Try it out" Limitations

---

When you run an Extraction with the "Try it out" function on a mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

{
    "iModelId": "70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a",
    "mappingName": "Mapping_name",
    "description": "This will overwrite the description when copying a mapping.",
    "sourceMappingId": "f1fe5959-35ab-467e-83b8-a679b722d80f"
}

{
    "iModelId": "70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a",
    "mappingName": "Mapping_name",
    "description": "Mapping schema for iModel",
    "extractionEnabled": false
}

{
    "mapping": {
        "id": "f1fe5959-35ab-467e-83b8-a679b722d80f",
        "mappingName": "Mapping_name",
        "description": "Mapping schema for iModel",
        "extractionEnabled": true,
        "createdOn": "2021-09-03T10:48:45+00:00",
        "createdBy": "john.doe@example.com",
        "modifiedOn": "2022-01-10T13:44:56+00:00",
        "modifiedBy": "john.doe@example.com",
        "_links": {
            "iModel": {
                "href": "https://api.bentley.com/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a"
            }
        }
    }
}

{
    "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": "InvalidGroupingAndMappingRequest",
        "message": "Cannot create Mapping.",
        "details": [{
            "code": "InvalidValue",
            "message": "Provided 'iModelId' value is not valid. Requested iModel is not available.",
            "target": "iModelId"
        }]
    }
}

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