Run Extraction - Reporting

REST API Overview

Reference

Changelog

API Keys

Reporting

Download API definition:

Run Extraction

POST https://api.bentley.com/insights/reporting/datasources/imodels/{imodelId}/extraction/run

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

Request

Request parameters

imodelId

template

Yes

The iModel Id.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

Extraction Run Request

changesetId

String

Optional ChangesetId to run the new extraction run against. If provided, extraction will be run against the given changeset. If not provided, extraction will be run against the newest changeset.

mappings

Extraction_Request_Mapping[]

An optional list of Mappings to extract during new extraction run. If provided, extraction will extract only the provided Mappings even if those Mappings have extractionEnabled flag set to false. If not provided, extraction will extract all Mappings for the given iModel.

ecInstanceIds

String[]

An optional list of ECInstanceIds to extract during new extraction run. If provided, extraction will only extract rows with ECInstanceId value that is in the provided list. If not provided, extraction will extract all rows without any filtering.

Example

json

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

Response

Response 200 OK

Started an Extraction Run successfully.

json

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

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

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

Response 404 Not Found

Specified ExtractionRun was not found.

json

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

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

json

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

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json

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

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

Link

Hyperlink container.

TableSchema

href

String

Hyperlink to the specific entity.

Extraction Run Request

Configuration for a manual extraction run.

TableSchema

changesetId

String

Optional ChangesetId to run the new extraction run against. If provided, extraction will be run against the given changeset. If not provided, extraction will be run against the newest changeset.

mappings

Extraction_Request_Mapping[]

An optional list of Mappings to extract during new extraction run. If provided, extraction will extract only the provided Mappings even if those Mappings have extractionEnabled flag set to false. If not provided, extraction will extract all Mappings for the given iModel.

ecInstanceIds

String[]

An optional list of ECInstanceIds to extract during new extraction run. If provided, extraction will only extract rows with ECInstanceId value that is in the provided list. If not provided, extraction will extract all rows without any filtering.

Extraction Request Mapping

Mapping configuration for a manual extraction run.

TableSchema

String

Mapping Id.

Extraction Run

Metadata associated with a data extraction run.

TableSchema

run.id

String

Unique Identifier for the Extraction Run. Use this to check run status.

run._links.status

Link

URL pointing to the related Report.

Error

Contains error information.

TableSchema

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String

The target of the error.

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

TableSchema

error

Error

Error information.