Get CDM - Grouping and Mapping

Grouping and Mapping

Download API definition:

This API is a Technical Preview and is available for testing purposes only. Do not use in production.

GET https://dev-api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/{mappingId}/extractions/{extractionId}/cdm

Gets the data model of extracted data in Common Data Model (CDM) format.

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

Request

Request parameters

mappingId

Yes

The mapping Id.

extractionId

Yes

The extraction Id.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response

Response 200 OK

json

{
    "name": "Insights_and_Reporting_Extractor",
    "version": "1.0",
    "entities": [{
        "$type": "LocalEntity",
        "name": "Beam",
        "attributes": [{
                "name": "ECInstanceId",
                "dataType": "string"
            },
            {
                "name": "ECClassId",
                "dataType": "string"
            },
            {
                "name": "UserLabel",
                "dataType": "string"
            },
            {
                "name": "BBoxLow",
                "dataType": "string"
            },
            {
                "name": "BBoxHigh",
                "dataType": "string"
            }
        ],
        "partitions": [{
            "name": "part00000",
            "location": "Beam/part00000.csv"
        }]
    }]
}

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 resource was not found.

json

{
    "error": {
        "code": "MappingNotFound",
        "message": "Requested Mapping is not available.",
        "target": "mappingId"
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

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

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

Common Data Model (CDM)

A Common Data Model (CDM) which describes the extracted data, metadata and locations.

name

String

The model name.

version

String

The model schema version (currently must be 1.0).

entities

CDMEntity[]

The model entities.

json

{
    "title": "Common Data Model (CDM)",
    "type": "object",
    "description": "A Common Data Model (CDM) which describes the extracted data, metadata and locations.",
    "properties": {
        "name": {
            "type": "string",
            "description": "The model name."
        },
        "version": {
            "type": "string",
            "description": "The model schema version (currently must be 1.0)."
        },
        "entities": {
            "type": "array",
            "description": "The model entities.",
            "items": {
                "$ref": "#/components/schemas/CDMEntity"
            }
        }
    },
    "required": [
        "name",
        "version",
        "entities"
    ],
    "additionalProperties": false
}

CDM Entity

An entity is a collection of attributes and metadata that defines a concept.

$type

String

Type of entity being defined in this model. Always set to LocalEntity.

name

String

The entity name.

attributes

CDMAttribute[]

The attributes within the entity. Each entity must have at least one.

partitions

CDMPartition[]

The entity physical partitions (data files).

json

{
    "title": "CDM Entity",
    "type": "object",
    "description": "An entity is a collection of attributes and metadata that defines a concept.",
    "properties": {
        "$type": {
            "type": "string",
            "description": "Type of entity being defined in this model. Always set to `LocalEntity`."
        },
        "name": {
            "type": "string",
            "description": "The entity name."
        },
        "attributes": {
            "type": "array",
            "description": "The attributes within the entity. Each entity must have at least one.",
            "items": {
                "$ref": "#/components/schemas/CDMAttribute"
            }
        },
        "partitions": {
            "type": "array",
            "description": "The entity physical partitions (data files).",
            "items": {
                "$ref": "#/components/schemas/CDMPartition"
            }
        }
    },
    "required": [
        "$type",
        "name",
        "attributes",
        "partitions"
    ],
    "additionalProperties": false
}

CDM Attribute

Attributes are the fields within an entity that correspond to data values within the data file.

name

String

The attribute name.

dataType

String

The data type of the attribute. One of 'string', 'int64', 'double', 'dateTime', 'dateTimeOffset', 'decimal', 'boolean', 'GUID', or 'JSON'.

annotations

CDMAnnotation[], null

Array of optional model annotations - non-essential key/value pairs that contain contextual information that can be used to store additional context.

json

{
    "title": "CDM Attribute",
    "type": "object",
    "description": "Attributes are the fields within an entity that correspond to data values within the data file.",
    "properties": {
        "name": {
            "type": "string",
            "description": "The attribute name."
        },
        "dataType": {
            "type": "string",
            "description": "The data type of the attribute. One of 'string', 'int64', 'double', 'dateTime', 'dateTimeOffset', 'decimal', 'boolean', 'GUID', or 'JSON'."
        },
        "annotations": {
            "type": "array",
            "description": "Array of optional model annotations - non-essential key/value pairs that contain contextual information that can be used to store additional context.",
            "nullable": true,
            "items": {
                "$ref": "#/components/schemas/CDMAnnotation"
            }
        }
    },
    "required": [
        "name",
        "dataType"
    ],
    "additionalProperties": false
}

CDM Annotation

Optional, non-essential contextual information (key/value pairs) that can be used to store additional context about a property in the model.

name

String

Name of the annotation.

value

String, null

Value of the annotation.

json

{
    "title": "CDM Annotation",
    "type": "object",
    "description": "Optional, non-essential contextual information (key/value pairs) that can be used to store additional context about a property in the model.",
    "properties": {
        "name": {
            "type": "string",
            "description": "Name of the annotation."
        },
        "value": {
            "type": "string",
            "description": "Value of the annotation.",
            "nullable": true
        }
    },
    "required": [
        "name"
    ],
    "additionalProperties": false
}

CDM Partition

The partition array indicates the name and location of the actual data that correspond to the entity definition. Currently all partitions store data in CSV format.

name

String

The partition name.

location

String

The partition location.

json

{
    "title": "CDM Partition",
    "type": "object",
    "description": "The partition array indicates the name and location of the actual data that correspond to the entity definition. Currently all partitions store data in CSV format.",
    "properties": {
        "name": {
            "type": "string",
            "description": "The partition name."
        },
        "location": {
            "type": "string",
            "description": "The partition location."
        }
    },
    "required": [
        "name",
        "location"
    ],
    "additionalProperties": false
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

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.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "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.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?