Table of contents
Saved Views

Extensions

Download API definition:

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:

1. PerModelCategoryVisibility

PerModelCategoryVisibility - Schema

[
   {
   "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
            }            
         ]
      }
   }
]

PerModelCategoryVisibility - Example

{
  "perModelCategoryVisibilityProps": [
    {
      "modelId": "0x20000000079",
      "categoryId": "0x2000000003e",
      "visible": true
    },
    {
      "modelId": "0x20000000079",
      "categoryId": "0x2000000004e",
      "visible": false
    }
  ]
}

2. EmphasizeElements

EmphasizeElements - Schema

[
   {
   "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"
               }
            ]
         }
      ]
   }
]

EmphasizeElements - Example

{
  "emphasizeElementsProps": {
    "neverDrawn": [
      "0x20000003865",
      "0x20000003864",
      "0x200000055e4",
      "0x200000055e3",
      "0x200000039af",
      "0x200000039ae"
    ]
  }
}

3. VisibilityOverride

VisibilityOverride - Schema

[
   {
      "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"
                }
              ]
            }
          ]
        }
      ]
   }
]

VisibilityOverride - 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 savedviews:modify.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request parameters

Name
In
Required?
Description
savedViewId
template
Yes

Id of the saved view to create an extension for.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with scope savedviews:modify

Accept
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

Name
Type
Required?
Description
extensionName
String
No

Name of the extension.

data
String
No

Payload of extension.

Example

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

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

Name
Description
retry-after

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

CreateExtension

TableSchema
Name
Type
Description
extensionName
String

Name of the extension.

data
String

Payload of extension.

CreateExtensionResponse

TableSchema
Name
Type
Description
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.

TableSchema
Name
Type
Description
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
Name
Type
Description
error

Error information.