Creates a Mapping for an iModel. Each Mapping represents a collection of tables (Groups) of data that can be consumed in a Report.

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 Project 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 Project 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 either a new ChangesetGroup is created (see ChangesetGroupCompletedEvent) or when the Run Extraction operation is executed without the optional mappings parameter. Note: Multiple ChangesetGroups can be created for a single Synchronization job which will result in multiple automatic Extractions.

If extractionEnabled is set to false, all of the above mechanisms are disabled. However, Extractions can still be executed for a specific Mapping manually using the Run Extraction operation and the optional mappings parameter. To have better control over Extractions, it is recommended to set extractionEnabled to false and manually trigger Run 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}.

{
    "mappingName": "Mapping_name",
    "description": "Mapping schema for iModel",
    "extractionEnabled": true
}

{
    "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": "hanson.deck@cohesivecompanies.com",
        "modifiedOn": "2021-09-03T10:48:45+00:00",
        "modifiedBy": "hanson.deck@cohesivecompanies.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": "MappingNotFound",
        "message": "Requested Mapping is not available.",
        "target": "id"
    }
}

{
    "error": {
        "code": "InvalidInsightsRequest",
        "message": "Error message."
    }
}

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}