Create Extension - Saved Views

REST API Overview

Overview

Samples

Reference

Changelog

Saved Views

Download API definition:

Create Extension

PUT https://api.bentley.com/savedviews/{savedViewId}/extensions

Creates an extension that contains custom data in a saved view.

Extensions allow a saved view to be enhanced with custom data. The extensions have to be defined in a proprietary .JSON schema file. For now, only three extensions are available:

Extension Schemas

The following extensions are available and are shown below in the details sections. The details sections contain the schema followed by an example of that schema.

Per Model Category Visibility - Schema

Per Model Category Visibility Details

``` [ { "type": "array", "name": "perModelCategoryVisibilityProps", "required": true, "items": { "type": "object", "required": true, "properties": [ { "name": "modelId", "type": "Id64String", "required": true }, { "name": "categoryId", "type": "Id64String", "required": true }, { "name": "visible", "type": "boolean", "required": true } ] } } ] ``` Per Model Category Visibility - Example ``` { "perModelCategoryVisibilityProps": [ { "modelId": "0x20000000079", "categoryId": "0x2000000003e", "visible": true }, { "modelId": "0x20000000079", "categoryId": "0x2000000004e", "visible": false } ] } ```

### Emphasize Elements - Schema

Emphasize Elements Details

``` [ { "type": "object", "name": "emphasizeElementsProps", "required": true, "properties": [ { "name": "neverDrawn", "type": "array", "required": false, "items": { "type": "Id64String" } }, { "name": "alwaysDrawn", "type": "array", "required": false, "items": { "type": "Id64String" } }, { "name": "isAlwaysDrawnExclusive", "type": "boolean", "required": false }, { "name": "alwaysDrawnExclusiveEmphasized", "type": "array", "required": false, "items": { "type": "Id64String" } }, { "name": "defaultAppearance", "type": "object", "required": false, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] }, { "name": "appearanceOverride", "type": "array", "items": { "type": "object", "properties": [ { "name": "overrideType", "type": "integer" }, { "name": "color", "type": "number" }, { "name": "ids", "type": "array", "items": { "type": "Id64String" } } ] } }, { "name": "wantEmphasis", "type": "boolean" }, { "name": "unanimatedAppearance", "type": "object", "required": false, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] } ] } ] ``` Emphasize Elements - Example ``` { "emphasizeElementsProps": { "neverDrawn": [ "0x20000003865", "0x20000003864", "0x200000055e4", "0x200000055e3", "0x200000039af", "0x200000039ae" ] } } ```

### Visibility Override - Schema

Visibility Override Details

``` [ { "name": "visibilityOverrideProps", "type": "object", "required": true, "properties": [ { "name": "subCategoryOverrides", "type": "array", "items": { "type": "object", "properties": [ { "name": "ids", "type": "array", "required": true, "items": { "type": "Id64String" } }, { "name": "app", "type": "object", "required": true, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] } ] } }, { "name": "modelOverrides", "type": "array", "items": { "type": "object", "properties": [ { "name": "ids", "type": "array", "required": true, "items": { "type": "Id64String" } }, { "name": "app", "type": "object", "required": true, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] } ] } }, { "name": "catEmphasizeOverride", "type": "object", "properties": [ { "name": "ids", "type": "array", "required": true, "items": { "type": "Id64String" } }, { "name": "app", "type": "object", "required": true, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] } ] }, { "name": "modelEmphasizeOverride", "type": "object", "properties": [ { "name": "ids", "type": "array", "required": true, "items": { "type": "Id64String" } }, { "name": "app", "type": "object", "required": true, "properties": [ { "name": "rgb", "type": "object", "properties": [ { "name": "r", "type": "number", "required": true }, { "name": "g", "type": "number", "required": true }, { "name": "b", "type": "number", "required": true } ] }, { "name": "weight", "type": "number" }, { "name": "transparency", "type": "number" }, { "name": "viewDependentTransparency", "type": "boolean" }, { "name": "linePixels", "type": "integer" }, { "name": "ignoresMaterial", "type": "boolean" }, { "name": "nonLocatable", "type": "boolean" }, { "name": "emphasized", "type": "boolean" } ] } ] } ] } ] ``` Visibility Override - Example ``` { "visibilityOverrideProps": { "subCategoryOverrides": [ { "ids": [ "0x200000009e5", "0x20000000a45" ], "app": { "rgb": { "r": 12, "g": 12, "b": 107 }, "transparency": 0.46 } }, { "ids": [ "0x20000007771", "0x20000007810" ], "app": { "rgb": { "r": 12, "g": 12, "b": 107 }, "transparency": 0.46 } } ] } } ```

Later on, consumers of the API will be allowed to define their own extensions.

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.

Request

Request parameters

savedViewId

Yes

Id of the saved view to create an extension for.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Payload of the extension that includes the extension name and the data.

Request body

CreateExtension

extensionName

String

Name of the extension.

data

String

Payload of extension.

Example

json

{
    "extensionName": "MyExtensionName",
    "data": "{\"myExtensionData\": 123}"
}

Response

Response 201 Created

Created extension.

json

{
    "extension": {
        "extensionName": "My Extension",
        "markdownUrl": "https://github.com/iTwin/saved-views-extensions/my-extension/my-extension.md",
        "schemaUrl": "https://github.com/iTwin/saved-views-extensions/my-extension/my-extension-schema.json",
        "data": "{ \"myExtensionData\": 123 }",
        "_links": {
            "iTwin": {
                "href": "https://api.bentley.com/iTwins/c6b0bf8d-033d-4291-9931-9b20f2135111"
            },
            "project": {
                "href": "https://api.bentley.com/projects/c6b0bf8d-033d-4291-9931-9b20f2135111"
            },
            "imodel": {
                "href": "https://api.bentley.com/imodels/b2db2e65-24a5-4958-abf5-91a60b94e8a5"
            },
            "savedView": {
                "href": "https://api.bentley.com/savedviews/AB2ckLPpC-REkuTK99srqHONv7DGPQORQpkxmyDyE1ERZS7bsqUkWEmr9ZGmC5TopQ"
            },
            "self": {
                "href": "https://api.bentley.com/savedviews/AB2ckLPpC-REkuTK99srqHONv7DGPQORQpkxmyDyE1ERZS7bsqUkWEmr9ZGmC5TopQ/extensions/Extension_Name"
            }
        }
    }
}

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 403 Forbidden

The user has insufficient permissions for the requested operation.

json

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 404 Not Found

Requested savedview is not available.

json

{
    "error": {
        "code": "SavedViewNotFound",
        "message": "Requested savedview is not available."
    }
}

Response 422 Unprocessable Entity

Cannot create group.

json

{
    "error": {
        "code": "InvalidSavedviewsRequest",
        "message": "Cannot update extension.",
        "details": [{
            "code": "InvalidRequestBody",
            "message": "extensionName must be a string.",
            "target": "extensionName"
        }]
    }
}

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

CreateExtension

extensionName

String

Name of the extension.

data

String

Payload of extension.

CreateExtensionResponse

extension.extensionName

String

extension.markdownUrl

String

extension.schemaUrl

String

extension.data

String

extension._links.iTwin.href

String

extension._links.project.href

String

extension._links.imodel.href

String

extension._links.savedView.href

String

extension._links.self.href

String

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.

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.