Run extraction of data from an iModel. This operation has two optional request body parameters: changesetId and ecInstanceIds. If ecInstanceIds are provided, only the ECInstances specified will be extracted. You can provide changesetId to run the extraction on a specific changeset.

If you do not provide the optional request body parameters:

• latest changeset will be used for extraction
• all ECInstances will be extracted that are selected by the group queries

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.

Notes

---

Data will not be extracted for a mapping if that mapping was already extracted from a newer changeset. If you wish to "go back in time" with a mapping and extract data from an older changeset, you will need to copy the mapping and run extraction on the copy.

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.

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",
    "changesetId": "f525c4c77f22f44b694dcce8c86462b10bd9725f",
    "mappings": [{
        "id": "ebbdb3eb-1c0c-4f9f-abd1-5dac8df4ec02"
    }],
    "ecInstanceIds": [
        "0x1",
        "0x2",
        "0x3"
    ]
}

{
    "extraction": {
        "id": "40f71ed2-31a3-45d3-bce0-5c9f3f112c03",
        "state": "Queued",
        "startedOn": "2022-09-10T13:44:56+00:00",
        "_links": {
            "status": {
                "href": "https://api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/extractions/40f71ed2-31a3-45d3-bce0-5c9f3f112c03"
            },
            "logs": {
                "href": "https://api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/extractions/40f71ed2-31a3-45d3-bce0-5c9f3f112c03/logs"
            }
        }
    }
}

{
    "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 run Extraction.",
        "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."
    }
}