Manually run extraction of data from an iModel.

For the iModel data source, data must be extracted first before it can be used in your reports.

Manual extraction allows you to choose optional request body parameters such as changesetId, mappings, and ecInstanceIds. You can specify the mappings list you want to extract, also you can filter ecInstanceIds or choose on which changesetId to run the new extraction. You can provide any combination of these request body parameters when you send a request.

If you do not provide a request body:

• latest changeset will be used for extraction
• all mappings on this iModel with extractionEnabled flag set to true will be extracted
• all ECInstances will be extracted that are selected by the group queries

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. To see the extracted mapping's data from an older changeset in your report, you will need to update report mappings accordingly.

Automatic Extraction

---

For all mappings with extractionEnabled set to true, iModel data extraction is executed automatically when there are new changes (see ChangesetGroupCompletedEvent) to the iModel which are ready to be processed.

If an iModel contains mappings that have extractionEnabled set to true, do not call this API on a scheduled basis or after making changes to an iModel. Only call this API after creating or changing an iModel mapping, group, group property, calculated property, or custom calculation. Note: Multiple automatic Extractions can be triggered for a single Synchronization job.

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.

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

{
    "changesetId": "f525c4c77f22f44b694dcce8c86462b10bd9725f",
    "mappings": [{
            "id": "ebbdb3eb-1c0c-4f9f-abd1-5dac8df4ec02"
        },
        {
            "id": "3c933071-9b26-49ea-b436-52f7cd35ebde"
        }
    ],
    "ecInstanceIds": [
        "0x1",
        "0x2",
        "0x3"
    ]
}

{
    "run": {
        "id": "40f71ed2-31a3-45d3-bce0-5c9f3f112c03",
        "_links": {
            "status": {
                "href": "https://api.bentley.com/insights/reporting/datasources/extraction/status/40f71ed2-31a3-45d3-bce0-5c9f3f112c03"
            }
        }
    }
}

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

{
    "error": {
        "code": "ExtractionRunNotFound",
        "message": "Requested ExtractionRun is not available.",
        "target": "id"
    }
}

{
    "error": {
        "code": "InvalidInsightsRequest",
        "message": "Required properties are missing or invalid.",
        "target": "mappings[0].id"
    }
}

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