├── Images ├── Topology1.png ├── Topology2.png └── Topology3.png ├── LICENSE ├── README.md └── Schemas ├── Collaboration ├── Action │ ├── comment_actions.json │ ├── project_actions.json │ ├── topic_actions.json │ └── viewpoint_actions.json ├── Comment │ ├── comment_GET.json │ ├── comment_POST.json │ └── comment_PUT.json ├── Document │ └── document_GET.json ├── DocumentReference │ ├── document_reference_GET.json │ ├── document_reference_POST.json │ └── document_reference_PUT.json ├── Events │ ├── comment_event_GET.json │ ├── event_action.json │ └── topic_event_GET.json ├── File │ ├── file_GET.json │ ├── file_PUT.json │ ├── project_file_display_information.json │ ├── project_file_information.json │ └── project_files_information_GET.json ├── RelatedTopic │ ├── related_topic_GET.json │ └── related_topic_PUT.json ├── Topic │ ├── bim_snippet.json │ ├── topic_GET.json │ ├── topic_POST.json │ └── topic_PUT.json └── Viewpoint │ ├── bitmap_GET.json │ ├── bitmap_POST.json │ ├── clipping_plane.json │ ├── coloring.json │ ├── coloring_GET.json │ ├── component.json │ ├── component_list.json │ ├── components.json │ ├── direction.json │ ├── line.json │ ├── location.json │ ├── orthogonal_camera.json │ ├── perspective_camera.json │ ├── point.json │ ├── selection_GET.json │ ├── snapshot_GET.json │ ├── snapshot_POST.json │ ├── view_setup_hints.json │ ├── viewpoint_GET.json │ ├── viewpoint_POST.json │ ├── visibility.json │ └── visibility_GET.json ├── Project ├── extensions_GET.json ├── project_GET.json └── project_PUT.json ├── User └── user_GET.json └── error.json /Images/Topology1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/buildingSMART/BCF-API/701e5ceb3548b2feec73f4ec56f5a1d6112bd16f/Images/Topology1.png -------------------------------------------------------------------------------- /Images/Topology2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/buildingSMART/BCF-API/701e5ceb3548b2feec73f4ec56f5a1d6112bd16f/Images/Topology2.png -------------------------------------------------------------------------------- /Images/Topology3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/buildingSMART/BCF-API/701e5ceb3548b2feec73f4ec56f5a1d6112bd16f/Images/Topology3.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | (c) buildingSMART International Ltd. 2 | 3 | This work is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License. 4 | To view a copy of this license, visit http://creativecommons.org/licenses/by-nd/4.0/ 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Official repository by buildingSMART International](https://img.shields.io/badge/buildingSMART-Official%20Repository-orange.svg)](https://www.buildingsmart.org/) 2 | [![This repo is managed by the BCF Implementers Group](https://img.shields.io/badge/-BCF%20Implementers%20Group-blue.svg)](https://img.shields.io/badge/-BCF%20Implementers%20Group-blue.svg) 3 | 4 | # BCF REST API 5 | ![](https://raw.githubusercontent.com/BuildingSMART/BCF/master/Icons/BCFicon128.png) 6 | 7 | **BCFv3.0** is based on BCFv2.1. 8 | 9 | [BCF XML GitHub repository](https://github.com/BuildingSMART/BCF-XML) 10 | 11 | [Version 1.0 of the OpenCDE Foundation API specification is available here](https://github.com/BuildingSMART/foundation-API/tree/v1.0) 12 | 13 | [Version 1.0 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v1.0) 14 | 15 | [Version 2.1 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v2.1) 16 | 17 | **Swagger / OpenAPI Specification** 18 | [BCF-API on SwaggerHub](https://app.swaggerhub.com/apis/buildingSMART/BCF/3.0) 19 | > The Swagger / OpenAPI specification is offered as a reference for implementers. The BCF group may update it and fix issues as necessary at any time. 20 | 21 | # Contributing 22 | 23 | The Open CDE workgroup develops the BCF standard. The group meets every second Monday at 11am CET. To join the fortnightly meeting please email [opencde@buildingsmart.org](mailto:opencde@buildingsmart.org). 24 | 25 | **Table of Contents** 26 | 27 | 28 | 29 | - [1. Introduction](#1-introduction) 30 | * [1.1 OpenCDE Foundation API](#11-opencde-foundation-api) 31 | * [1.2 Authorization](#12-authorization) 32 | + [1.2.1 Per-Entity Authorization](#121-per-entity-authorization) 33 | + [1.2.2 Determining Authorized Entity Actions](#122-determining-authorized-entity-actions) 34 | * [1.3 Units of Numeric Values](#13-units-of-numeric-values) 35 | - [2. Topologies](#2-topologies) 36 | * [2.1 Topology 1 - BCF-Server only](#21-topology-1---bcf-server-only) 37 | * [2.2 Topology 2 - Colocated BCF-Server and Model Server](#22-topology-2---colocated-bcf-server-and-model-server) 38 | - [3. BCF Services](#3-bcf-services) 39 | * [3.1 Project Services](#31-project-services) 40 | + [3.1.1 GET Projects Service](#311-get-projects-service) 41 | + [3.1.2 GET Project Service](#312-get-project-service) 42 | + [3.1.3 PUT Project Service](#313-put-project-service) 43 | + [3.1.4 GET Project Extension Service](#314-get-project-extension-service) 44 | + [3.1.5 Expressing User Authorization Through Project Extensions](#315-expressing-user-authorization-through-project-extensions) 45 | - [3.1.5.1 Project](#3151-project) 46 | - [3.1.5.2 Topic](#3152-topic) 47 | - [3.1.5.3 Comment](#3153-comment) 48 | * [3.2 Topic Services](#32-topic-services) 49 | + [3.2.1 GET Topics Service](#321-get-topics-service) 50 | + [3.2.2 POST Topic Service](#322-post-topic-service) 51 | + [3.2.3 GET Topic Service](#323-get-topic-service) 52 | + [3.2.4 PUT Topic Service](#324-put-topic-service) 53 | + [3.2.5 DELETE Topic Service](#325-delete-topic-service) 54 | + [3.2.6 GET Topic BIM Snippet Service](#326-get-topic-bim-snippet-service) 55 | + [3.2.7 PUT Topic BIM Snippet Service](#327-put-topic-bim-snippet-service) 56 | + [3.2.8 Determining Allowed Topic Modifications](#328-determining-allowed-topic-modifications) 57 | + [3.2.9 Topic Identifiers](#329-topic-identifiers) 58 | * [3.3 File Services](#33-file-services) 59 | + [3.3.1 GET Project Files Information Service](#331-get-project-files-information-service) 60 | + [3.3.2 GET Files (Header) Service](#332-get-files-header-service) 61 | + [3.3.3 PUT Files (Header) Service](#333-put-files-header-service) 62 | * [3.4 Comment Services](#34-comment-services) 63 | + [3.4.1 GET Comments Service](#341-get-comments-service) 64 | + [3.4.2 POST Comment Service](#342-post-comment-service) 65 | + [3.4.3 GET Comment Service](#343-get-comment-service) 66 | + [3.4.4 PUT Comment Service](#344-put-comment-service) 67 | + [3.4.5 DELETE Comment Service](#345-delete-comment-service) 68 | + [3.4.6 Determining allowed Comment modifications](#346-determining-allowed-comment-modifications) 69 | * [3.5 Viewpoint Services](#35-viewpoint-services) 70 | + [3.5.1 GET Viewpoints Service](#351-get-viewpoints-service) 71 | + [3.5.2 POST Viewpoint Service](#352-post-viewpoint-service) 72 | - [3.5.2.1 Point](#3521-point) 73 | - [3.5.2.2 Direction](#3522-direction) 74 | - [3.5.2.3 Orthogonal camera](#3523-orthogonal-camera) 75 | - [3.5.2.4 Perspective camera](#3524-perspective-camera) 76 | - [3.5.2.5 Line](#3525-line) 77 | - [3.5.2.6 Clipping plane](#3526-clipping-plane) 78 | - [3.5.2.7 Bitmap](#3527-bitmap) 79 | - [3.5.2.8 Snapshot](#3528-snapshot) 80 | - [3.5.2.9 Components](#3529-components) 81 | - [3.5.2.10 Component](#35210-component) 82 | * [Optimization rules](#optimization-rules) 83 | - [3.5.2.11 Coloring](#35211-coloring) 84 | * [Optimization rules](#optimization-rules-1) 85 | - [3.5.2.12 Visibility](#35212-visibility) 86 | * [Optimization rules](#optimization-rules-2) 87 | - [3.5.2.13 View setup hints](#35213-view-setup-hints) 88 | + [3.5.3 GET Viewpoint Service](#353-get-viewpoint-service) 89 | + [3.5.4 GET Viewpoint Snapshot Service](#354-get-viewpoint-snapshot-service) 90 | + [3.5.5 GET Viewpoint Bitmap Service](#355-get-viewpoint-bitmap-service) 91 | + [3.5.6 GET selected Components Service](#356-get-selected-components-service) 92 | + [3.5.7 GET colored Components Service](#357-get-colored-components-service) 93 | + [3.5.8 GET visibility of Components Service](#358-get-visibility-of-components-service) 94 | + [3.5.9 DELETE Viewpoint Service](#359-delete-viewpoint-service) 95 | + [3.5.10 Determining allowed Viewpoint modifications](#3510-determining-allowed-viewpoint-modifications) 96 | * [3.6 Related Topics Services](#36-related-topics-services) 97 | + [3.6.1 GET Related Topics Service](#361-get-related-topics-service) 98 | + [3.6.2 PUT Related Topics Service](#362-put-related-topics-service) 99 | * [3.7 Document Reference Services](#37-document-reference-services) 100 | + [3.7.1 GET Document References Service](#371-get-document-references-service) 101 | + [3.7.2 POST Document Reference Service](#372-post-document-reference-service) 102 | + [3.7.3 PUT Document Reference Service](#373-put-document-reference-service) 103 | * [3.8 Document Services](#38-document-services) 104 | + [3.8.1 GET Documents Service](#381-get-documents-service) 105 | + [3.8.2 POST Document Service](#382-post-document-service) 106 | + [3.8.3 GET Document Service](#383-get-document-service) 107 | * [3.9 Topics Events Services](#39-topics-events-services) 108 | + [3.9.1 GET Topics Events Service](#391-get-topics-events-service) 109 | + [3.9.2 GET Topic Events Service](#392-get-topic-events-service) 110 | * [3.10 Comments Events Services](#310-comments-events-services) 111 | + [3.10.1 GET Comments Events Service](#3101-get-comments-events-service) 112 | + [3.10.2 GET Comment Events Service](#3102-get-comment-events-service) 113 | 114 | 115 | 116 | # 1. Introduction 117 | 118 | BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via HTTP query parameters and JSON bodies. Every resource described in this API has a corresponding JSON schema (schema version draft-03). 119 | URL schemas in this README are relative to the BCF servers' base URL unless absolute values are provided. 120 | 121 | For security reasons, all API Http traffic should be sent via TLS/SSL over Https connection. Clients and Servers should both enforce secure connections and disallow unsafe connections. 122 | 123 | An example of a client implementation in C# can be found here: 124 | [https://github.com/rvestvik/BcfApiExampleClient](https://github.com/rvestvik/BcfApiExampleClient) 125 | 126 | ## 1.1 OpenCDE Foundation API 127 | 128 | BCF API is a member of the OpenCDE API family. All OpenCDE APIs are united by a shared common API called [OpenCDE Foundation API](https://github.com/buildingSMART/foundation-API). 129 | The foundation API specifies a small number of services and a few conventions that are common to all OpenCDE APIs. All BCF API implementations must implement the Foundation API and follow its conventions and guidelines. 130 | Implementers should start by implementing the Foundation API and only then continue to implement the BCF API. 131 | 132 | ## 1.2 Authorization 133 | 134 | API implementors can optionally choose to restrict the actions a user is allowed to perform on the BCF entities 135 | via the API. The global default authorizations for all entities are expressed in the project extensions schema and can 136 | be locally overridden in the entities themselves. 137 | 138 | ### 1.2.1 Per-Entity Authorization 139 | 140 | Whenever a user requests an update-able entity with the query parameter `includeAuthorization` equal to `true` the 141 | server should include an `authorization` field in the entity containing any local variations from the global 142 | authorization defaults for that entity. Using this information clients can decide whether to, for example, include an 143 | "Edit" button in the UI displaying the entity depending on the actions permitted for the user or suggest only the 144 | options available to the user for choice fields such as topic status. 145 | 146 | ### 1.2.2 Determining Authorized Entity Actions 147 | 148 | The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from 149 | the project extensions, then replacing any keys defined in the entity's `authorization` map with the values specified 150 | locally. The meaning of each of the authorization keys is outlined in 151 | [3.1.5 Expressing User Authorization through Project Extensions](#315-expressing-user-authorization-through-project-extensions). 152 | 153 | **Example Scenario (Topic)** 154 | 155 | This scenario assumes the topic status is set to `open`. 156 | 157 | _In the Project Extensions_ 158 | 159 | { 160 | "topic_actions": [], 161 | "topic_status": [ 162 | "open", 163 | "closed", 164 | "confirmed" 165 | ] 166 | } 167 | 168 | Indicating that by default: 169 | 170 | * no modifications can be made to Topics 171 | * Topics can be placed in `open`, `closed` or `confirmed` status 172 | 173 | _In the Topic_ 174 | 175 | { 176 | "authorization": { 177 | "topic_actions": [ 178 | "update", 179 | "createComment", 180 | "createViewpoint" 181 | ], 182 | "topic_status": [ 183 | "open", 184 | "closed" 185 | ] 186 | } 187 | } 188 | 189 | Indicating that for this topic, the current user can: 190 | 191 | * update the Topic, or add comments or viewpoints 192 | * place the Topic into `closed` status 193 | * leave the Topic `open` or place the topic back into `open` status after closing it 194 | 195 | ### 1.3 Units of Numeric Values 196 | 197 | Numeric values in this specification are all in fixed units - meters for length and degrees for angle. 198 | 199 | ---------- 200 | 201 | # 2. Topologies 202 | 203 | ## 2.1 Topology 1 - BCF-Server only 204 | 205 | Model collaboration is managed through a shared file server or a network file sharing service like Dropbox. The BCF-Server handles the authentication and the BCF-Issues. 206 | 207 | ![Topology1](Images/Topology1.png) 208 | 209 | ## 2.2 Topology 2 - Colocated BCF-Server and Model Server 210 | 211 | BCF and model server are co-located on the same hosts. 212 | 213 | ![Topology3](Images/Topology3.png) 214 | 215 | ---------- 216 | 217 | # 3. BCF Services 218 | 219 | ## 3.1 Project Services 220 | 221 | For compatibility with the project structure of existing systems, the `project_id` property of `project` resources is **not forced to be a guid but may be any string**. 222 | 223 | ### 3.1.1 GET Projects Service 224 | 225 | **Resource URL** 226 | 227 | GET /bcf/{version}/projects 228 | 229 | [project_GET.json](Schemas_draft-03/Project/project_GET.json) 230 | 231 | Retrieve a **collection** of projects where the currently logged on user has access to. 232 | 233 | **Example Request** 234 | 235 | GET /bcf/3.0/projects 236 | 237 | **Example Response** 238 | 239 | Response Code: 200 - OK 240 | Body: 241 | [{ 242 | "project_id": "F445F4F2-4D02-4B2A-B612-5E456BEF9137", 243 | "name": "Example project 1", 244 | "authorization": { 245 | "project_actions": [ 246 | "createTopic", 247 | "createDocument" 248 | ] 249 | } 250 | }, { 251 | "project_id": "A233FBB2-3A3B-EFF4-C123-DE22ABC8414", 252 | "name": "Example project 2", 253 | "authorization": { 254 | "project_actions": [] 255 | } 256 | }] 257 | 258 | ### 3.1.2 GET Project Service 259 | 260 | **Resource URL** 261 | 262 | GET /bcf/{version}/projects/{project_id} 263 | 264 | [project_GET.json](Schemas_draft-03/Project/project_GET.json) 265 | 266 | Retrieve a specific project. 267 | 268 | **Example Request** 269 | 270 | GET /bcf/3.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414 271 | 272 | **Example Response** 273 | 274 | Response Code: 200 - OK 275 | Body: 276 | { 277 | "project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414", 278 | "name": "Example project 3", 279 | "authorization": { 280 | "project_actions": [ 281 | "update" 282 | ] 283 | } 284 | } 285 | 286 | ### 3.1.3 PUT Project Service 287 | 288 | **Resource URL** 289 | 290 | PUT /bcf/{version}/projects/{project_id} 291 | 292 | [project_PUT.json](Schemas_draft-03/Project/project_PUT.json) 293 | 294 | Modify a specific project. This operation is only possible when the server returns the `update` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) 295 | 296 | **Example Request** 297 | 298 | PUT /bcf/3.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414 299 | Body: 300 | { 301 | "name": "Example project 3 - Second Section" 302 | } 303 | 304 | **Example Response** 305 | 306 | Response Code: 200 - OK 307 | Body: 308 | { 309 | "project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414", 310 | "name": "Example project 3 - Second Section", 311 | "authorization": { 312 | "project_actions": [ 313 | "update" 314 | ] 315 | } 316 | } 317 | 318 | ### 3.1.4 GET Project Extension Service 319 | 320 | **Resource URL** 321 | 322 | GET /bcf/{version}/projects/{project_id}/extensions 323 | 324 | [extensions_GET.json](Schemas_draft-03/Project/extensions_GET.json) 325 | 326 | Retrieve a specific projects extensions. 327 | Project extensions are used to define possible values that can be used in topics and comments, for example topic labels and priorities. They may change during the course of a project. The most recent extensions state which values are valid at a given moment for newly created topics and comments. 328 | 329 | **Example Request** 330 | 331 | GET /bcf/3.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414/extensions 332 | 333 | **Example Response** 334 | 335 | Response Code: 200 - OK 336 | Body: 337 | { 338 | "topic_type": [ 339 | "Information", 340 | "Error" 341 | ], 342 | "topic_status": [ 343 | "Open", 344 | "Closed", 345 | "ReOpened" 346 | ], 347 | "topic_label": [ 348 | "Architecture", 349 | "Structural", 350 | "MEP" 351 | ], 352 | "snippet_type": [ 353 | ".ifc", 354 | ".csv" 355 | ], 356 | "priority": [ 357 | "Low", 358 | "Medium", 359 | "High" 360 | ], 361 | "users": [ 362 | "Architect@example.com", 363 | "BIM-Manager@example.com", 364 | "bob_heater@example.com" 365 | ], 366 | "stage": [ 367 | "Preliminary Planning End", 368 | "Construction Start", 369 | "Construction End" 370 | ], 371 | "project_actions": [ 372 | "update", 373 | "createTopic", 374 | "createDocument" 375 | ], 376 | "topic_actions": [ 377 | "update", 378 | "updateBimSnippet", 379 | "updateRelatedTopics", 380 | "updateDocumentReferences", 381 | "updateFiles", 382 | "createComment", 383 | "createViewpoint" 384 | ], 385 | "comment_actions": [ 386 | "update" 387 | ] 388 | } 389 | 390 | ### 3.1.5 Expressing User Authorization Through Project Extensions 391 | 392 | Global default authorizations for the requesting user can be expressed in the project schema. The actions authorized 393 | here will apply to any entities that do not override them locally. The complete set of options for the BCF entities are 394 | listed below. 395 | 396 | #### 3.1.5.1 Project 397 | 398 | The 'project_actions' entry in the project extensions defines what actions are allowed to be performed 399 | at the project level. The available actions include: 400 | 401 | * *update* - The ability to update the project details (see [3.1.3 PUT Project Service](#313-put-project-service)) 402 | * *createTopic* - The ability to create a new topic (see [3.2.2 POST Topic Service](#322-post-topic-service)) 403 | * *createDocument* - The ability to create a new document (see [3.8.2 POST Document Service](#382-post-document-service)) 404 | 405 | #### 3.1.5.2 Topic 406 | 407 | The 'topic_actions' entry in the project extensions defines what actions are allowed to be performed at the topic 408 | level by default (i.e. unless overridden by specific topics) The available actions include: 409 | 410 | * *update* - The ability to update the topic (see [3.2.4 PUT Topic Service](#324-put-topic-service)) 411 | * *updateBimSnippet* - The ability to update the BIM snippet for topics (see [3.2.7 PUT Topic BIM Snippet Service](#327-put-topic-bim-snippet-service)) 412 | * *updateRelatedTopics* - The ability to update the collection of related topics (see [3.6.2 PUT Related Topics Service](#362-put-related-topics-service)) 413 | * *updateDocumentReferences* - The ability to update the collection of document references (see [3.7.3 PUT Document Reference Service](#373-put-document-reference-service)) 414 | * *updateFiles* - The ability to update the file header (see [3.3.3 PUT Files (Header) Service](#333-put-files-header-service)) 415 | * *createComment* - The ability to create a comment (see [3.4.2 POST Comment Service](#342-post-comment-service)) 416 | * *createViewpoint* - The ability to create a new viewpoint (see [3.5.2 POST Viewpoint Service](#352-post-viewpoint-service)) 417 | 418 | #### 3.1.5.3 Comment 419 | 420 | The 'comment_actions' entry in the project extensions defines what actions are allowed to be performed at the comment level by 421 | default (i.e unless overridden by specific comments). The available actions include: 422 | 423 | * *update* - The ability to update the comment (see [3.4.4 PUT Comment Service](#344-put-comment-service)) 424 | 425 | --------- 426 | 427 | ## 3.2 Topic Services 428 | 429 | ### 3.2.1 GET Topics Service 430 | 431 | **Resource URL** 432 | 433 | GET /bcf/{version}/projects/{project_id}/topics 434 | 435 | [topic_GET.json](Schemas_draft-03/Collaboration/Topic/topic_GET.json) 436 | 437 | Retrieve a **collection** of topics related to a project (default sort order is `creation_date`). 438 | 439 | **Odata filter parameters** 440 | 441 | |parameter|type|description| 442 | |---------|----|-----------| 443 | |creation_author|string|userId of the creation author (value from extensions)| 444 | |modified_author|string|userId of the modified author (value from extensions)| 445 | |assigned_to|string|userId of the assigned person (value from extensions)| 446 | |stage|string|stage this topic is part of (value from extensions)| 447 | |topic_status|string|status of a topic (value from extensions)| 448 | |topic_type|string|type of a topic (value from extensions)| 449 | |creation_date|datetime|creation date of a topic| 450 | |modified_date|datetime|modification date of a topic. The modification date of a server's topic should be the latest value of when the topic has been modified or when the latest [comment](#34-comment-services) has been updated or when a "floating viewpoint" (a [viewpoint](#35-viewpoint-services) which is not associated with a comment) is added| 451 | |labels|array (string)|labels of a topic (value from extensions)| 452 | |priority|string|priority of a topic (value from extensions)| 453 | 454 | **Odata sort parameters** 455 | 456 | |parameter|description| 457 | |---------|-----------| 458 | |creation_date|creation date of a topic| 459 | |modified_date|modification date of a topic| 460 | |server_assigned_id|the [server_assigned_id](#329-topic-identifiers) of the topic| 461 | |index|index of a topic **This property is deprecated and will be removed in a future release**| 462 | 463 | **Example Request with odata** 464 | 465 | Get topics that are open, assigned to Architect@example.com and created after December 5th 2015. Sort the result on last modified 466 | 467 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=assigned_to eq 'Architect@example.com' and topic_status eq 'Open' and creation_date gt 2015-12-05T00:00:00+01:00&$orderby=modified_date desc 468 | 469 | Odata does not support list operators. To achieve list query, use the 'or' operator. 470 | Get topics that have at least one of the labels 'Architecture', 'Structural' or 'Heating' 471 | 472 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=labels/any(label: label eq 'Architecture') or labels/any(label: label eq 'Structural') or labels/any(label: label eq 'Heating') 473 | 474 | **Example Request** 475 | 476 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics 477 | 478 | **Example Response** 479 | 480 | Response Code: 200 - OK 481 | Body: 482 | [{ 483 | "guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 484 | "server_assigned_id": "ISSUE-00001", 485 | "creation_author": "Architect@example.com", 486 | "title": "Example topic 1", 487 | "labels": [ 488 | "Architecture", 489 | "Structural" 490 | ], 491 | "creation_date": "2013-10-21T17:34:22.409Z" 492 | }, { 493 | "guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414", 494 | "server_assigned_id": "ISSUE-00078", 495 | "creation_author": "Architect@example.com", 496 | "title": "Example topic 2", 497 | "labels": [ 498 | "Architecture", 499 | "Heating", 500 | "Electrical" 501 | ], 502 | "creation_date": "2014-11-19T14:24:11.316Z" 503 | }] 504 | 505 | ### 3.2.2 POST Topic Service 506 | 507 | **Resource URL** 508 | 509 | POST /bcf/{version}/projects/{project_id}/topics 510 | 511 | [topic_POST.json](Schemas_draft-03/Collaboration/Topic/topic_POST.json) 512 | 513 | Add a new topic. This operation is only possible when the server returns the `createTopic` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) 514 | 515 | **Parameters** 516 | 517 | JSON encoded body using the "application/json" content type. 518 | 519 | |Parameter|Type|Description|Required| 520 | |---------|----|-----------|--------| 521 | |guid|string|The desired guid. See OpenCDE Foundation section [1.5.1](https://github.com/buildingSMART/foundation-API#151-conflict-on-creation) when GUID already exists in target system.|false| 522 | |topic_type|string|The type of a topic (value from extension.xsd)|false| 523 | |topic_status|string|The status of a topic (value from extension.xsd)|false| 524 | |reference_links|array (string)|Reference links, i.e. links to referenced resources|false| 525 | |title|string|The title of a topic|true| 526 | |priority|string|The priority of a topic (value from extension.xsd)|false| 527 | |index|integer|The index of a topic **This property is deprecated and will be removed in a future release**|false| 528 | |labels|array (string)|The collection of labels of a topic (values from extension.xsd)|false| 529 | |assigned_to|string|UserID assigned to a topic (value from extension.xsd). UserIDs are recommended to be in email format as to uniquely identify users throughout multiple systems|false| 530 | |stage|string|Stage this topic is part of (value from extension.xsd)|false| 531 | |description|string|Description of a topic|false| 532 | |bim_snippet.snippet_type|string|Type of a BIM-Snippet of a topic (value from extension.xsd)|false| 533 | |bim_snippet.is_external|boolean|Is the BIM-Snippet external (default = false)|false| 534 | |bim_snippet.reference|string|Reference of a BIM-Snippet of a topic|false| 535 | |bim_snippet.reference_schema|string|Schema of a BIM-Snippet of a topic|false| 536 | |due_date|string|Until when the topics issue needs to be resolved|false| 537 | 538 | _Note: If "bim_snippet" is present, then all four properties (`snippet_type`, `is_external`, `reference` and `reference_schema`) are mandatory._ 539 | 540 | **Example Request** 541 | 542 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics 543 | Body: 544 | { 545 | "topic_type": "Clash", 546 | "topic_status": "open", 547 | "title": "Example topic 3", 548 | "priority": "high", 549 | "labels": [ 550 | "Architecture", 551 | "Heating" 552 | ], 553 | "assigned_to": "harry.muster@example.com", 554 | "bim_snippet": { 555 | "snippet_type": "clash", 556 | "is_external": true, 557 | "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB", 558 | "reference_schema": "https://example.com/bcf/1.0/clash.xsd" 559 | } 560 | } 561 | 562 | **Example Response** 563 | 564 | Response Code: 201 - Created 565 | Body: 566 | { 567 | "guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 568 | "server_assigned_id": "ISSUE-01462", 569 | "creation_author": "Architect@example.com", 570 | "creation_date": "2016-08-01T17:34:22.409Z", 571 | "topic_type": "Clash", 572 | "topic_status": "open", 573 | "title": "Example topic 3", 574 | "priority": "high", 575 | "labels": [ 576 | "Architecture", 577 | "Heating" 578 | ], 579 | "assigned_to": "harry.muster@example.com", 580 | "bim_snippet": { 581 | "snippet_type": "clash", 582 | "is_external": true, 583 | "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB", 584 | "reference_schema": "https://example.com/bcf/1.0/clash.xsd" 585 | } 586 | } 587 | 588 | ### 3.2.3 GET Topic Service 589 | 590 | **Resource URL** 591 | 592 | GET /bcf/{version}/projects/{guid}/topics/{guid} 593 | 594 | [topic_GET.json](Schemas_draft-03/Collaboration/Topic/topic_GET.json) 595 | 596 | Retrieve a specific topic. 597 | 598 | **Example Request** 599 | 600 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228 601 | 602 | **Example Response** 603 | 604 | Response Code: 200 - OK 605 | Body: 606 | { 607 | "guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228", 608 | "server_assigned_id": "ISSUE-00549", 609 | "creation_author": "Architect@example.com", 610 | "creation_date": "2016-08-01T17:34:22.409Z", 611 | "topic_type": "Clash", 612 | "topic_status": "open", 613 | "title": "Example topic 3", 614 | "priority": "high", 615 | "labels": [ 616 | "Architecture", 617 | "Heating" 618 | ], 619 | "assigned_to": "harry.muster@example.com", 620 | "bim_snippet": { 621 | "snippet_type": "clash", 622 | "is_external": true, 623 | "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB", 624 | "reference_schema": "https://example.com/bcf/1.0/clash.xsd" 625 | }, 626 | "authorization": { 627 | "topic_actions": [ 628 | "createComment", 629 | "createViewpoint" 630 | ] 631 | } 632 | } 633 | 634 | ### 3.2.4 PUT Topic Service 635 | 636 | **Resource URL** 637 | 638 | PUT /bcf/{version}/projects/{project_id}/topics/{guid} 639 | 640 | [topic_PUT.json](Schemas_draft-03/Collaboration/Topic/topic_PUT.json) 641 | 642 | Modify a specific topic, description similar to POST. This operation is only possible when the server returns the `update` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 643 | 644 | **Example Request** 645 | 646 | PUT /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228 647 | Body: 648 | { 649 | "topic_type": "Clash", 650 | "topic_status": "open", 651 | "title": "Example topic 3 - Changed Title", 652 | "priority": "high", 653 | "labels": [ 654 | "Architecture", 655 | "Heating" 656 | ], 657 | "assigned_to": "harry.muster@example.com", 658 | "bim_snippet": { 659 | "snippet_type": "clash", 660 | "is_external": true, 661 | "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB", 662 | "reference_schema": "https://example.com/bcf/1.0/clash.xsd" 663 | } 664 | } 665 | 666 | **Example Response** 667 | 668 | Response Code: 200 - OK 669 | Body: 670 | { 671 | "guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228", 672 | "server_assigned_id": "ISSUE-00037", 673 | "creation_author": "Architect@example.com", 674 | "creation_date": "2016-08-01T17:34:22.409Z", 675 | "modified_author": "Architect@example.com", 676 | "modified_date": "2016-08-02T13:22:22.409Z", 677 | "topic_type": "Clash", 678 | "topic_status": "open", 679 | "title": "Example topic 3 - Changed Title", 680 | "priority": "high", 681 | "labels": [ 682 | "Architecture", 683 | "Heating" 684 | ], 685 | "assigned_to": "harry.muster@example.com", 686 | "bim_snippet": { 687 | "snippet_type": "clash", 688 | "is_external": true, 689 | "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB", 690 | "reference_schema": "https://example.com/bcf/1.0/clash.xsd" 691 | } 692 | } 693 | 694 | ### 3.2.5 DELETE Topic Service 695 | 696 | **Resource URL** 697 | 698 | DELETE /bcf/{version}/projects/{project_id}/topics/{guid} 699 | 700 | Deletes a single topic. This operation is only possible when the server returns the `delete` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 701 | 702 | **Example Request** 703 | 704 | DELETE /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228 705 | 706 | **Example Response** 707 | 708 | Response Code: 200 - OK 709 | 710 | ### 3.2.6 GET Topic BIM Snippet Service 711 | 712 | **Resource URL** 713 | 714 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/snippet 715 | 716 | Retrieves a topics BIM-Snippet as binary file. 717 | 718 | ### 3.2.7 PUT Topic BIM Snippet Service 719 | 720 | **Resource URL** 721 | 722 | PUT /bcf/{version}/projects/{project_id}/topics/{guid}/snippet 723 | 724 | Puts a new BIM Snippet binary file to a topic. If this is used, the parent topics BIM Snippet property `is_external` must be set to `false` and the `reference` must be the file name with extension. This operation is only possible when the server returns the `updateBimSnippet` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 725 | 726 | ### 3.2.8 Determining Allowed Topic Modifications 727 | 728 | The global default Topic authorizations are expressed in the project schema and when Topic(s) are requested with the 729 | query parameter "includeAuthorization" equal to "true" Topics will include an "authorization" field containing any local 730 | overrides for each Topic. 731 | 732 | ### 3.2.9 Topic Identifiers 733 | 734 | Each topic has two identifiers: 735 | 1. `guid` - machine-friendly, randomly generated and universally unique identifier. Both clients and servers must generate 736 | a `guid` when creating a topic using an RFC 4122 compliant UUID generator. The `guid` should be used in all client-server 737 | interactions to identify topics.
738 | 739 | `guid` examples: 420b24db-921c-46d6-9629-d529d130307f, 5139a00f-5cbd-4760-9e44-16cc4826aa5a 740 | 2. `server_assigned_id` - a human-friendly identifier which is generated and controlled by the server. A `server_assigned_id` is project-unique: 741 | No two topics in a given server and project may have the same `server_assigned_id`. However, topics in different projects on a 742 | given server may have identical `server_assigned_id`s. `server_assigned_id`s can't be changed using the API; BCF clients should display 743 | `server_assigned_id`s to users to make it easier to locate and discuss topics.
744 | 745 | `server_assigned_id` examples: 003490, ISSUE-01 746 | 747 | ## 3.3 File Services 748 | 749 | This group of services corresponds to the BCF-XML [header](https://github.com/buildingSMART/BCF-XML/tree/release_3_0/Documentation#header) `Files` element. The files associated with a topic are the models that should be loaded when displaying the topic's viewpoints. 750 | 751 | ### 3.3.1 GET Project Files Information Service 752 | 753 | **Resource URL** 754 | 755 | GET /bcf/{version}/projects/{project_id}/files_information 756 | 757 | [project_files_information_GET.json](Schemas_draft-03/Collaboration/File/project_files_information_GET.json) 758 | 759 | Retrieve a **collection** of `project_file_information`s to support allowing users to choose which `File`s (models) 760 | to reference in the header of topics created on the server. 761 | 762 | Each [project_file_information](Schemas_draft-03/Collaboration/File/project_file_information.json) record contains 763 | `display_information` to allow users to associate the `File` with a server model. 764 | The `display_information` object is designed to support user interface rendering in tabular format. The 765 | servers are required to provide a consistent list of fields across all 766 | [project_file_information](Schemas_draft-03/Collaboration/File/project_file_information.json) objects. The following 767 | table demonstrates tabular rendering of the **Example Response** (below): 768 | 769 | | Model Name | Revision Date | 770 | |------------|---------------| 771 | | ARCH-Z100-051 | May 3 2020 | 772 | | MEP-Z100-015 | Apr 30 2020 | 773 | 774 | Each [project_file_information](Schemas_draft-03/Collaboration/File/project_file_information.json) also contains a 775 | [file_GET](Schemas_draft-03/Collaboration/File/file_GET.json) object that will be accepted by the server should the 776 | user choose to associate a topic with that `File`. 777 | 778 | **Example Request** 779 | 780 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/files_information 781 | 782 | **Example Response** 783 | 784 | Response Code: 200 - OK 785 | Body: 786 | [{ 787 | "display_information": [{ 788 | "field_display_name": "Model Name", 789 | "field_value": "ARCH-Z100-051" 790 | }, { 791 | "field_display_name": "Revision Date", 792 | "field_value": "May 3 2020" 793 | }], 794 | "file": { 795 | "ifc_project": "0J$yPqHBD12v72y4qF6XcD", 796 | "file_name": "OfficeBuilding_Architecture_0001.ifc", 797 | "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc" 798 | } 799 | }, { 800 | "display_information": [{ 801 | "field_display_name": "Model Name", 802 | "field_value": "MEP-Z100-015" 803 | }, { 804 | "field_display_name": "Revision Date", 805 | "field_value": "Apr 30 2020" 806 | }], 807 | "file": { 808 | "ifc_project": "3hwBHP91jBRwPsmyf$3Hea", 809 | "file_name": "OfficeBuilding_Heating_0003.ifc", 810 | "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a" 811 | } 812 | }] 813 | 814 | 815 | ### 3.3.2 GET Files (Header) Service 816 | 817 | **Resource URL** 818 | 819 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/files 820 | 821 | [file_GET.json](Schemas_draft-03/Collaboration/File/file_GET.json) 822 | 823 | Retrieve a **collection** of file references as topic header. 824 | 825 | *Implementer Note*: The `reference` property can either be an **Uri** or a **server specific id**. Uris are given as absolute paths to the model files while ids reference a custom id of the model file and require custom logic per server to retrieve it. This allows referencing of files on the server but requires clients to know how to retrieve files in a specific implementation. 826 | 827 | **Example Request** 828 | 829 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files 830 | 831 | **Example Response** 832 | 833 | Response Code: 200 - OK 834 | Body: 835 | [{ 836 | "ifc_project": "0J$yPqHBD12v72y4qF6XcD", 837 | "filename": "OfficeBuilding_Architecture_0001.ifc", 838 | "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc" 839 | }, { 840 | "ifc_project": "3hwBHP91jBRwPsmyf$3Hea", 841 | "filename": "OfficeBuilding_Heating_0003.ifc", 842 | "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a" 843 | }] 844 | 845 | > Note: In the above example, the second items reference is in a guid format and points to a model file that is located on the server. Servers don't have to use guid formats for their internal ids, so the expected format of the response can vary between servers. 846 | 847 | ### 3.3.3 PUT Files (Header) Service 848 | 849 | **Resource URL** 850 | 851 | PUT /bcf/{version}/projects/{project_id}/topics/{guid}/files 852 | 853 | [file_PUT.json](Schemas_draft-03/Collaboration/File/file_PUT.json) 854 | 855 | Update a **collection** of file references on the topic header. This operation is only possible when the server returns the `updateFiles` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications). Servers must always accept a [File](Schemas_draft-03/Collaboration/File/file_GET.json) reference returned by the [files_information](#331-get-project-files-information-service) endpoint. Servers may also accept other values such as a combination of fields from the header of the IFC file. 856 | 857 | **Example Request** 858 | 859 | PUT /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files 860 | Body: 861 | [{ 862 | "ifc_project": "0J$yPqHBD12v72y4qF6XcD", 863 | "filename": "OfficeBuilding_Architecture_0001.ifc", 864 | "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc" 865 | }, { 866 | "ifc_project": "3hwBHP91jBRwPsmyf$3Hea", 867 | "filename": "OfficeBuilding_Heating_0003.ifc", 868 | "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a" 869 | }] 870 | 871 | **Example Response** 872 | 873 | Response Code: 200 - OK 874 | Body: 875 | [{ 876 | "ifc_project": "0J$yPqHBD12v72y4qF6XcD", 877 | "filename": "OfficeBuilding_Architecture_0001.ifc", 878 | "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc" 879 | }, { 880 | "ifc_project": "3hwBHP91jBRwPsmyf$3Hea", 881 | "filename": "OfficeBuilding_Heating_0003.ifc", 882 | "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a" 883 | }] 884 | 885 | ## 3.4 Comment Services 886 | 887 | ### 3.4.1 GET Comments Service 888 | 889 | **Resource URL** 890 | 891 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments 892 | 893 | [comment_GET.json](Schemas_draft-03/Collaboration/Comment/comment_GET.json) 894 | 895 | Retrieve a **collection** of all comments related to a topic (default ordering is date). 896 | 897 | **Odata filter parameters** 898 | 899 | |parameter|type|description| 900 | |---------|----|-----------| 901 | |author|string|userId of the author (value from extensions)| 902 | |date|datetime|creation date of a comment| 903 | 904 | **Odata sort parameters** 905 | 906 | |parameter|description| 907 | |---------|-----------| 908 | |date|creation date of a comment| 909 | 910 | **Example Request with odata** 911 | 912 | Get comments that are created after December 5 2015. Sort the result on first created 913 | 914 | GET /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments?$filter=date gt 2015-12-05T00:00:00+01:00&$orderby=date asc 915 | 916 | **Example Request** 917 | 918 | GET /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments 919 | 920 | **Example Response** 921 | 922 | Response Code: 200 - OK 923 | Body: 924 | [{ 925 | "guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B", 926 | "date": "2016-08-01T12:34:22.409Z", 927 | "author": "max.muster@example.com", 928 | "comment": "Clash found", 929 | "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228", 930 | "authorization": { 931 | "comment_actions": [ 932 | "update" 933 | ] 934 | } 935 | }, { 936 | "guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414", 937 | "date": "2016-08-01T14:24:11.316Z", 938 | "author": "bob.heater@example.com", 939 | "comment": "will rework the heating model", 940 | "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" 941 | }] 942 | 943 | ### 3.4.2 POST Comment Service 944 | 945 | **Resource URL** 946 | 947 | POST /bcf/{version}/projects/{project_id}/topics/{guid}/comments 948 | 949 | [comment_POST.json](Schemas_draft-03/Collaboration/Comment/comment_POST.json) 950 | 951 | Add a new comment to a topic. This operation is only possible when the server returns the `createComment` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 952 | 953 | **Parameters** 954 | 955 | JSON encoded body using the "application/json" content type. 956 | 957 | |Parameter|Type|Description|Required| 958 | |---------|----|-----------|--------| 959 | |guid|string|The desired guid. See OpenCDE Foundation section [1.5.1](https://github.com/buildingSMART/foundation-API#151-conflict-on-creation) when GUID already exists in target system.|false| 960 | |comment|string|The comment text. Must not be blank or empty if provided|true, unless `viewpoint_guid` is provided| 961 | |viewpoint_guid|string|The GUID of the related viewpoint|true, unless `comment` is provided| 962 | 963 | **Example Request** 964 | 965 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments 966 | Body: 967 | { 968 | "comment": "will rework the heating model" 969 | } 970 | 971 | **Example Response** 972 | 973 | Response Code: 201 - Created 974 | Body: 975 | { 976 | "guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414", 977 | "date": "2016-08-01T14:24:11.316Z", 978 | "author": "bob.heater@example.com", 979 | "comment": "will rework the heating model", 980 | "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" 981 | } 982 | 983 | ### 3.4.3 GET Comment Service 984 | 985 | **Resource URL** 986 | 987 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid} 988 | 989 | [comment_GET.json](Schemas_draft-03/Collaboration/Comment/comment_GET.json) 990 | 991 | Get a single comment. 992 | 993 | **Example Request** 994 | 995 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414 996 | 997 | **Example Response** 998 | 999 | Response Code: 200 - OK 1000 | Body: 1001 | { 1002 | "guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414", 1003 | "date": "2016-08-01T14:24:11.316Z", 1004 | "author": "bob.heater@example.com", 1005 | "comment": "will rework the heating model", 1006 | "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" 1007 | } 1008 | 1009 | ### 3.4.4 PUT Comment Service 1010 | 1011 | **Resource URL** 1012 | 1013 | PUT /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid} 1014 | 1015 | [comment_PUT.json](Schemas_draft-03/Collaboration/Comment/comment_PUT.json) 1016 | 1017 | Update a single comment, description similar to POST. This operation is only possible when the server returns the `update` flag in the Comment authorization, see section [3.4.6](#346-determining-allowed-comment-modifications) 1018 | 1019 | **Example Request** 1020 | 1021 | PUT /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414 1022 | Body: 1023 | { 1024 | "comment": "will rework the heating model and fix the ventilation" 1025 | } 1026 | 1027 | **Example Response** 1028 | 1029 | Response Code: 200 - OK 1030 | Body: 1031 | { 1032 | "guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414", 1033 | "date": "2016-08-01T14:24:11.316Z", 1034 | "author": "bob.heater@example.com", 1035 | "modified_date": "2016-08-01T19:24:11.316Z", 1036 | "modified_author": "bob.heater@example.com", 1037 | "comment": "will rework the heating model and fix the ventilation", 1038 | "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" 1039 | } 1040 | 1041 | ### 3.4.5 DELETE Comment Service 1042 | 1043 | **Resource URL** 1044 | 1045 | DELETE /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid} 1046 | 1047 | Deletes a single comment. This operation is only possible when the server returns the `delete` flag in the Comment authorization, see section [3.4.6](#346-determining-allowed-comment-modifications) 1048 | 1049 | **Example Request** 1050 | 1051 | DELETE /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414 1052 | 1053 | **Example Response** 1054 | 1055 | Response Code: 200 - OK 1056 | 1057 | ### 3.4.6 Determining allowed Comment modifications 1058 | 1059 | The global default Comment authorizations are expressed in the project schema and when Comment(s) are requested with the 1060 | query parameter "includeAuthorization" equal to "true" Comments will include an "authorization" field containing any local 1061 | overrides for each Comment. 1062 | 1063 | ## 3.5 Viewpoint Services 1064 | 1065 | Viewpoints are described in detail in [BCF-XML](https://github.com/buildingSMART/BCF-XML/tree/release_2_2/Documentation#viewpoints). 1066 | 1067 | ### 3.5.1 GET Viewpoints Service 1068 | 1069 | **Resource URL** 1070 | 1071 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints 1072 | 1073 | [viewpoint_GET.json](Schemas_draft-03/Collaboration/Viewpoint/viewpoint_GET.json) 1074 | 1075 | Retrieve a **collection** of all viewpoints related to a topic. 1076 | 1077 | **Example Request** 1078 | 1079 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints 1080 | 1081 | **Example Response** 1082 | 1083 | Response Code: 200 - OK 1084 | Body: 1085 | [{ 1086 | "guid": "b24a82e9-f67b-43b8-bda0-4946abf39624", 1087 | "perspective_camera": { 1088 | "camera_view_point": { 1089 | "x": 0.0, 1090 | "y": 0.0, 1091 | "z": 0.0 1092 | }, 1093 | "camera_direction": { 1094 | "x": 1.0, 1095 | "y": 1.0, 1096 | "z": 2.0 1097 | }, 1098 | "camera_up_vector": { 1099 | "x": 0.0, 1100 | "y": 0.0, 1101 | "z": 1.0 1102 | }, 1103 | "field_of_view": 90.0, 1104 | "aspect_ratio": 1.33 1105 | }, 1106 | "lines": [{ 1107 | "start_point": { 1108 | "x": 2.0, 1109 | "y": 1.0, 1110 | "z": 1.0 1111 | }, 1112 | "end_point": { 1113 | "x": 0.0, 1114 | "y": 1.0, 1115 | "z": 0.7 1116 | } 1117 | }], 1118 | "clipping_planes": [{ 1119 | "location": { 1120 | "x": 0.7, 1121 | "y": 0.3, 1122 | "z": -0.2 1123 | }, 1124 | "direction": { 1125 | "x": 1.0, 1126 | "y": 0.4, 1127 | "z": 0.1 1128 | } 1129 | }] 1130 | }, { 1131 | "guid": "a11a82e7-e66c-34b4-ada1-5846abf39133", 1132 | "perspective_camera": { 1133 | "camera_view_point": { 1134 | "x": 0.0, 1135 | "y": 0.0, 1136 | "z": 0.0 1137 | }, 1138 | "camera_direction": { 1139 | "x": 1.0, 1140 | "y": 1.0, 1141 | "z": 2.0 1142 | }, 1143 | "camera_up_vector": { 1144 | "x": 0.0, 1145 | "y": 0.0, 1146 | "z": 1.0 1147 | }, 1148 | "field_of_view": 90.0, 1149 | "aspect_ratio": 1.33 1150 | }, 1151 | "lines": [{ 1152 | "start_point": { 1153 | "x": 1.0, 1154 | "y": 1.0, 1155 | "z": 1.0 1156 | }, 1157 | "end_point": { 1158 | "x": 0.0, 1159 | "y": 0.0, 1160 | "z": 0.0 1161 | } 1162 | }], 1163 | "clipping_planes": [{ 1164 | "location": { 1165 | "x": 0.5, 1166 | "y": 0.5, 1167 | "z": 0.5 1168 | }, 1169 | "direction": { 1170 | "x": 1.0, 1171 | "y": 0.0, 1172 | "z": 0.0 1173 | } 1174 | }] 1175 | }] 1176 | 1177 | ### 3.5.2 POST Viewpoint Service 1178 | 1179 | **Resource URL** 1180 | 1181 | POST /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints 1182 | 1183 | [viewpoint_POST.json](Schemas_draft-03/Collaboration/Viewpoint/viewpoint_POST.json) 1184 | 1185 | Add a new viewpoint. Viewpoints are immutable, meaning that they should never change. Requirements for different visualizations should be handled by creating new viewpoint elements. This operation is only possible when the server returns the `createViewpoint` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 1186 | 1187 | **Parameters** 1188 | 1189 | JSON encoded body using the "application/json" content type. 1190 | 1191 | |parameter|type|description|required| 1192 | |---------|----|-----------|--------| 1193 | | guid | string | The desired guid. See OpenCDE Foundation section [1.5.1](https://github.com/buildingSMART/foundation-API#151-conflict-on-creation) when GUID already exists in target system. | optional | 1194 | | index | integer | parameter for sorting | optional | 1195 | | orthogonal_camera | [Orthogonal camera](#3523-orthogonal-camera) | orthogonal camera view | see viewpoint optional/mandatory fields clarification | 1196 | | perspective_camera | [Perspective camera](#3524-perspective-camera) | perspective view of the camera | see viewpoint optional/mandatory fields clarification | 1197 | | lines | array of [Line](#3525-line) | graphical line | optional | 1198 | | clipping_planes | array of [Clipping Plane](#3526-clipping-plane) | clipping planes for the model view | optional | 1199 | | bitmaps | array of [Bitmap](#3527-bitmap) | embedded pictures in the viewpoint | optional | 1200 | | snapshot | [Snapshot](#3528-snapshot) | snapshot image of the viewpoint. Note: The longest dimension of should not exceed 1500 px, length or width. | see viewpoint optional/mandatory fields clarification | 1201 | | components | [Components](#3529-components) | Components in the viewpoint | optional | 1202 | 1203 | **Viewpoint optional/mandatory fields clarification** 1204 | 1205 | 1. **Camera definition** is exactly one of `perspective_camera` or `orthogonal_camera` 1206 | 2. **Visualisation information** consists of one or more of the following elements: `lines`, `clipping_plans`, `bitmaps`, `components` 1207 | 3. A viewpoint must contain a _camera definition_, a `snapshot` or both 1208 | 4. A viewpoint containing _visualization information_ must also contain a _camera definition_ 1209 | 1210 | #### 3.5.2.1 Point 1211 | [point.json](Schemas_draft-03/Collaboration/Viewpoint/point.json) 1212 | 1213 | |parameter|type|description|required| 1214 | |---------|----|-----------|--------| 1215 | | x | number | x point | mandatory | 1216 | | y | number | y point | mandatory | 1217 | | z | number | z point | mandatory | 1218 | 1219 | #### 3.5.2.2 Direction 1220 | [direction.json](Schemas_draft-03/Collaboration/Viewpoint/direction.json) 1221 | 1222 | Direction must not be a zero vector. 1223 | 1224 | |parameter|type|description|required| 1225 | |---------|----|-----------|--------| 1226 | | x | number | x direction | mandatory | 1227 | | y | number | y direction | mandatory | 1228 | | z | number | z direction | mandatory | 1229 | 1230 | ### Camera 1231 | 1232 | Perspective and Orthogonal cameras are explained in detail in [BCF-XML](https://github.com/buildingSMART/BCF-XML/tree/release_3_0/Documentation#camera). 1233 | 1234 | ![Camera Illustration](https://github.com/buildingSMART/BCF-XML/blob/release_3_0/Documentation/Graphics/Cameras.png) 1235 | 1236 | #### 3.5.2.3 Orthogonal camera 1237 | [orthogonal_camera.json](Schemas_draft-03/Collaboration/Viewpoint/orthogonal_camera.json) 1238 | 1239 | |parameter|type|description|required| 1240 | |---------|----|-----------|--------| 1241 | | camera_view_point | [Point](#3521-point) | camera location | mandatory | 1242 | | camera_direction | [Direction](#3522-direction) | camera direction | mandatory | 1243 | | camera_up_vector | [Direction](#3522-direction) | camera up vector | mandatory | 1244 | | view_to_world_scale | number | the entire vertical scaling from view to world | mandatory | 1245 | | aspect_ratio | number | proportional relationship between the width and the height of the view (w/h) | mandatory | 1246 | 1247 | #### 3.5.2.4 Perspective camera 1248 | [perspective_camera.json](Schemas_draft-03/Collaboration/Viewpoint/perspective_camera.json) 1249 | 1250 | |parameter|type|description|required| 1251 | |---------|----|-----------|--------| 1252 | | camera_view_point | [Point](#3521-point) | camera location | mandatory | 1253 | | camera_direction | [Direction](#3522-direction) | camera direction | mandatory | 1254 | | camera_up_vector | [Direction](#3522-direction) | camera up vector | mandatory | 1255 | | field_of_view | number | the entire vertical field of view angle of the camera, expressed in degrees | mandatory | 1256 | | aspect_ratio | number | proportional relationship between the width and the height of the view (w/h) | mandatory | 1257 | 1258 | #### 3.5.2.5 Line 1259 | [line.json](Schemas_draft-03/Collaboration/Viewpoint/line.json) 1260 | 1261 | |parameter|type|description|required| 1262 | |---------|----|-----------|--------| 1263 | | start_point | [Point](#3521-point) | start point of the line | mandatory | 1264 | | end_point | [Point](#3521-point) | end point of the line (Treated as point if start_point and end_point is the same | mandatory | 1265 | 1266 | #### 3.5.2.6 Clipping plane 1267 | [clipping_plane.json](Schemas_draft-03/Collaboration/Viewpoint/clipping_plane.json) 1268 | 1269 | |parameter|type|description|required| 1270 | |---------|----|-----------|--------| 1271 | | location | [Point](#3521-point) | origin of the clipping plane | mandatory | 1272 | | direction | [Direction](#3522-direction) | direction of the clipping plane, points in the invisible direction meaning the half-space that is clipped | mandatory | 1273 | 1274 | #### 3.5.2.7 Bitmap 1275 | [bitmap.json](Schemas_draft-03/Collaboration/Viewpoint/bitmap_POST.json) 1276 | 1277 | |parameter|type|description|required| 1278 | |---------|----|-----------|--------| 1279 | | bitmap_type | enum (string) | format of the bitmap. Predefined values `png` or `jpg` | mandatory | 1280 | | bitmap_data | base64 encoded string | The bitmap image data | mandatory | 1281 | | location | [Point](#3521-point) | location of the center of the bitmap in world coordinates (point) | mandatory | 1282 | | normal | [Direction](#3522-direction) | normal vector of the bitmap (vector) | mandatory | 1283 | | up | [Direction](#3522-direction) | up vector of the bitmap (vector) | mandatory | 1284 | | height | number | height of bitmap in the scene | mandatory | 1285 | 1286 | #### 3.5.2.8 Snapshot 1287 | [snapshot.json](Schemas_draft-03/Collaboration/Viewpoint/snapshot_POST.json) 1288 | 1289 | |parameter|type|description|required| 1290 | |---------|----|-----------|--------| 1291 | | snapshot_type | enum (string) | format of the snapshot. Predefined values `png` or `jpg` | mandatory | 1292 | | snapshot_data | base64 encoded string | The snapshot image data | mandatory | 1293 | 1294 | #### 3.5.2.9 Components 1295 | [components.json](Schemas_draft-03/Collaboration/Viewpoint/components.json) 1296 | 1297 | |parameter|type|description|required| 1298 | |---------|----|-----------|--------| 1299 | | selection | array of [Component](#35210-component) | Selected components | optional | 1300 | | coloring | array of [Coloring](#35211-coloring) | Colored components | optional | 1301 | | visibility | [Visibility](#35212-visibility) | Visibility of components | mandatory | 1302 | 1303 | #### 3.5.2.10 Component 1304 | [component.json](Schemas_draft-03/Collaboration/Viewpoint/component.json) 1305 | 1306 | ##### Optimization rules 1307 | BCF is suitable for selecting a few components. A huge list of selected components causes poor performance. All clients should follow this rule: 1308 | - If the size of the selected components is huge (approximately 1000 components), alert the user and give him the opportunity to modify the visibility. 1309 | 1310 | |parameter|type|description|required| 1311 | |---------|----|-----------|--------| 1312 | | ifc_guid | string | IFC guid of the component | optional, if authoring_tool_id is provided | 1313 | | originating_system | string | originating system of the component | optional | 1314 | | authoring_tool_id | string | internal id for the authoring tool of the component | optional, if ifc_guid is provided | 1315 | 1316 | Note that `ifc_guid` must be provided, if possible. The `authoring_tool_id` can be used as a fallback when an `ifc_guid` is not available. 1317 | 1318 | #### 3.5.2.11 Coloring 1319 | [coloring.json](Schemas_draft-03/Collaboration/Viewpoint/coloring.json) 1320 | 1321 | ##### Optimization rules 1322 | BCF is suitable for coloring a few components. A huge list of components causes poor performance. All clients should follow this rule: 1323 | - If the size of colored components is huge (approximately 1000 components), alert the user and give him the opportunity to modify the coloring. 1324 | 1325 | The color is given in ARGB format. Colors are represented as 6 or 8 hexadecimal digits. If 8 digits are present, the first two represent the alpha (transparency) channel. For example, `40E0D0` would be the color Turquoise. [More information about the color format can be found on Wikipedia.](https://en.wikipedia.org/wiki/RGBA_color_space) 1326 | 1327 | |parameter|type|description|required| 1328 | |---------|----|-----------|--------| 1329 | | color | string | Color of the components | mandatory | 1330 | | components | array of [Component](#35210-component) | Colored components | mandatory | 1331 | 1332 | #### 3.5.2.12 Visibility 1333 | [visibility.json](Schemas_draft-03/Collaboration/Viewpoint/visibility.json) 1334 | 1335 | ##### Optimization rules 1336 | BCF is suitable for hiding/showing a few components. A huge list of hidden/shown components causes poor performance. All clients should follow these rules: 1337 | - If the list of hidden components is smaller than the list of visible components: set default_visibility to true and put the hidden components in exceptions. 1338 | - If the list of visible components is smaller or equals the list of hidden components: set default_visibility to false and put the visible components in exceptions. 1339 | - If the size of exceptions is huge (approximately 1000 components), alert the user and give him the opportunity to modify the visibility. 1340 | 1341 | |parameter|type|description|required| 1342 | |---------|----|-----------|--------| 1343 | | default_visibility | boolean | If true: Show all components, and hide the exceptions. If false: Hide all components and show exceptions | optional, default false | 1344 | | exceptions | array of [Component](#35210-component) | Components to hide/show determined by default_visibility | optional | 1345 | | view_setup_hints | [View setup hints](#35213-view-setup-hints) | Hints about the setup of the viewer | optional | 1346 | 1347 | #### 3.5.2.13 View setup hints 1348 | [view_setup_hints.json](Schemas_draft-03/Collaboration/Viewpoint/view_setup_hints.json) 1349 | 1350 | |parameter|type|description|required| 1351 | |---------|----|-----------|--------| 1352 | | spaces_visible | boolean | Visibility of spaces | optional, default false | 1353 | | space_boundaries_visible | boolean | Visibility of space_boundaries | optional, default false | 1354 | | openings_visible | boolean | Visibility of openings | optional, default false | 1355 | 1356 | **Example Request** 1357 | 1358 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints 1359 | Body: 1360 | { 1361 | "index": 10, 1362 | "perspective_camera": { 1363 | "camera_view_point": { 1364 | "x": 0.0, 1365 | "y": 0.0, 1366 | "z": 0.0 1367 | }, 1368 | "camera_direction": { 1369 | "x": 1.0, 1370 | "y": 1.0, 1371 | "z": 2.0 1372 | }, 1373 | "camera_up_vector": { 1374 | "x": 0.0, 1375 | "y": 0.0, 1376 | "z": 1.0 1377 | }, 1378 | "field_of_view": 90.0, 1379 | "aspect_ratio": 1.33 1380 | }, 1381 | "lines": [{ 1382 | "start_point": { 1383 | "x": 1.0, 1384 | "y": 1.0, 1385 | "z": 1.0 1386 | }, 1387 | "end_point": { 1388 | "x": 0.0, 1389 | "y": 0.0, 1390 | "z": 0.0 1391 | } 1392 | }], 1393 | "clipping_planes": [{ 1394 | "location": { 1395 | "x": 0.5, 1396 | "y": 0.5, 1397 | "z": 0.5 1398 | }, 1399 | "direction": { 1400 | "x": 1.0, 1401 | "y": 0.0, 1402 | "z": 0.0 1403 | } 1404 | }], 1405 | "bitmaps": [{ 1406 | "bitmap_type": "jpg", 1407 | "bitmap_data": "SGVsbG8gV29ybGQh", 1408 | "location": { 1409 | "x": 10.0, 1410 | "y": -10.0, 1411 | "z": 7.0 1412 | }, 1413 | "normal": { 1414 | "x": -1.0, 1415 | "y": 1.25, 1416 | "z": 0.0 1417 | }, 1418 | "up": { 1419 | "x": -5.4, 1420 | "y": -4.3, 1421 | "z": 1.0 1422 | }, 1423 | "height": 1666 1424 | }], 1425 | "snapshot": { 1426 | "snapshot_type": "png", 1427 | "snapshot_data": "SGVsbG8gV29ybGQh" 1428 | }, 1429 | "components": { 1430 | "selection": [{ 1431 | "ifc_guid": "2MF28NhmDBiRVyFakgdbCT", 1432 | "originating_system": "Example CAD Application", 1433 | "authoring_tool_id": "EXCAD/v1.0" 1434 | }], 1435 | "coloring": [{ 1436 | "color": "ff0000", 1437 | "components": [{ 1438 | "ifc_guid": "3$cshxZO9AJBebsni$z9Yk" 1439 | }] 1440 | }], 1441 | "visibility": { 1442 | "default_visibility": false, 1443 | "exceptions": [{ 1444 | "ifc_guid": "4$cshxZO9AJBebsni$z9Yk" 1445 | }], 1446 | "view_setup_hints": { 1447 | "spaces_visible": true, 1448 | "space_boundaries_visible": false, 1449 | "openings_visible": true 1450 | } 1451 | } 1452 | } 1453 | } 1454 | 1455 | **Example Response** 1456 | 1457 | Response Code: 201 - Created 1458 | Body: 1459 | { 1460 | "guid": "a11a82e7-e66c-34b4-ada1-5846abf39133", 1461 | "index": 10, 1462 | "perspective_camera": { 1463 | "camera_view_point": { 1464 | "x": 0.0, 1465 | "y": 0.0, 1466 | "z": 0.0 1467 | }, 1468 | "camera_direction": { 1469 | "x": 1.0, 1470 | "y": 1.0, 1471 | "z": 2.0 1472 | }, 1473 | "camera_up_vector": { 1474 | "x": 0.0, 1475 | "y": 0.0, 1476 | "z": 1.0 1477 | }, 1478 | "field_of_view": 90.0, 1479 | "aspect_ratio": 1.33 1480 | }, 1481 | "lines": [{ 1482 | "start_point": { 1483 | "x": 1.0, 1484 | "y": 1.0, 1485 | "z": 1.0 1486 | }, 1487 | "end_point": { 1488 | "x": 0.0, 1489 | "y": 0.0, 1490 | "z": 0.0 1491 | } 1492 | }], 1493 | "clipping_planes": [{ 1494 | "location": { 1495 | "x": 0.5, 1496 | "y": 0.5, 1497 | "z": 0.5 1498 | }, 1499 | "direction": { 1500 | "x": 1.0, 1501 | "y": 0.0, 1502 | "z": 0.0 1503 | } 1504 | }], 1505 | "bitmaps": [{ 1506 | "guid": "20c1cb56-315f-4a0a-922d-ed7a4a8edf55", 1507 | "bitmap_type": "jpg", 1508 | "location": { 1509 | "x": 10.0, 1510 | "y": -10.0, 1511 | "z": 7.0 1512 | }, 1513 | "normal": { 1514 | "x": -1.0, 1515 | "y": 1.25, 1516 | "z": 0.0 1517 | }, 1518 | "up": { 1519 | "x": -5.4, 1520 | "y": -4.3, 1521 | "z": 1.0 1522 | }, 1523 | "height": 1666 1524 | }], 1525 | "snapshot": { 1526 | "snapshot_type": "png" 1527 | } 1528 | } 1529 | ### 3.5.3 GET Viewpoint Service 1530 | 1531 | **Resource URL** 1532 | 1533 | GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid} 1534 | 1535 | [viewpoint_GET.json](Schemas_draft-03/Collaboration/Viewpoint/viewpoint_GET.json) 1536 | 1537 | Retrieve a specific viewpoint. 1538 | 1539 | **Example Request** 1540 | 1541 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133 1542 | 1543 | **Example Response** 1544 | 1545 | Response Code: 200 - OK 1546 | Body: 1547 | { 1548 | "guid": "a11a82e7-e66c-34b4-ada1-5846abf39133", 1549 | "index": 10, 1550 | "perspective_camera": { 1551 | "camera_view_point": { 1552 | "x": 0.0, 1553 | "y": 0.0, 1554 | "z": 0.0 1555 | }, 1556 | "camera_direction": { 1557 | "x": 1.0, 1558 | "y": 1.0, 1559 | "z": 2.0 1560 | }, 1561 | "camera_up_vector": { 1562 | "x": 0.0, 1563 | "y": 0.0, 1564 | "z": 1.0 1565 | }, 1566 | "field_of_view": 90.0, 1567 | "aspect_ratio": 1.33 1568 | }, 1569 | "lines": [{ 1570 | "start_point": { 1571 | "x": 1.0, 1572 | "y": 1.0, 1573 | "z": 1.0 1574 | }, 1575 | "end_point": { 1576 | "x": 0.0, 1577 | "y": 0.0, 1578 | "z": 0.0 1579 | } 1580 | }], 1581 | "clipping_planes": [{ 1582 | "location": { 1583 | "x": 0.5, 1584 | "y": 0.5, 1585 | "z": 0.5 1586 | }, 1587 | "direction": { 1588 | "x": 1.0, 1589 | "y": 0.0, 1590 | "z": 0.0 1591 | } 1592 | }], 1593 | "bitmaps": [{ 1594 | "guid": "20c1cb56-315f-4a0a-922d-ed7a4a8edf55" 1595 | "bitmap_type": "jpg", 1596 | "location": { 1597 | "x": 10.0, 1598 | "y": -10.0, 1599 | "z": 7.0 1600 | }, 1601 | "normal": { 1602 | "x": -1.0, 1603 | "y": 1.25, 1604 | "z": 0.0 1605 | }, 1606 | "up": { 1607 | "x": -5.4, 1608 | "y": -4.3, 1609 | "z": 1.0 1610 | }, 1611 | "height": 1666 1612 | }], 1613 | "snapshot": { 1614 | "snapshot_type": "png" 1615 | } 1616 | } 1617 | 1618 | ### 3.5.4 GET Viewpoint Snapshot Service 1619 | 1620 | **Resource URL** 1621 | 1622 | GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/snapshot 1623 | 1624 | Retrieve a viewpoints snapshot (png or jpg) as image file. A viewpoint contains a snapshot if viewpoint.snapshot != null. 1625 | 1626 | **Example Request** 1627 | 1628 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/snapshot 1629 | 1630 | ### 3.5.5 GET Viewpoint Bitmap Service 1631 | 1632 | **Resource URL** 1633 | 1634 | GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/bitmaps/{guid} 1635 | 1636 | Retrieve a specific viewpoints bitmap image file (png or jpg). 1637 | 1638 | **Example Request** 1639 | 1640 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/bitmaps/20c1cb56-315f-4a0a-922d-ed7a4a8edf55 1641 | 1642 | ### 3.5.6 GET selected Components Service 1643 | **Resource URL** 1644 | 1645 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/selection 1646 | 1647 | [selection_GET.json](Schemas_draft-03/Collaboration/Viewpoint/selection_GET.json) 1648 | 1649 | Retrieve a **collection** of all selected components in a viewpoint. 1650 | 1651 | **Example Request** 1652 | 1653 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/selection 1654 | 1655 | **Example Response** 1656 | 1657 | Response Code: 200 - OK 1658 | Body: 1659 | { 1660 | "selection": [ 1661 | { 1662 | "ifc_guid": "2MF28NhmDBiRVyFakgdbCT", 1663 | "originating_system": "Example CAD Application", 1664 | "authoring_tool_id": "EXCAD/v1.0" 1665 | }, { 1666 | "ifc_guid": "3$cshxZO9AJBebsni$z9Yk" 1667 | } 1668 | ] 1669 | } 1670 | 1671 | ### 3.5.7 GET colored Components Service 1672 | 1673 | **Resource URL** 1674 | 1675 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/coloring 1676 | 1677 | [coloring_GET.json](Schemas_draft-03/Collaboration/Viewpoint/coloring_GET.json) 1678 | 1679 | Retrieve a **collection** of all colored components in a viewpoint. 1680 | 1681 | **Example Request** 1682 | 1683 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/coloring 1684 | 1685 | **Example Response** 1686 | 1687 | Response Code: 200 - OK 1688 | Body: 1689 | { 1690 | "coloring": [ 1691 | { 1692 | "color": "ff0000", 1693 | "components": [ 1694 | { 1695 | "ifc_guid": "2MF28NhmDBiRVyFakgdbCT", 1696 | "originating_system": "Example CAD Application", 1697 | "authoring_tool_id": "EXCAD/v1.0" 1698 | }, { 1699 | "ifc_guid": "3$cshxZO9AJBebsni$z9Yk" 1700 | } 1701 | ] 1702 | } 1703 | ] 1704 | } 1705 | 1706 | ### 3.5.8 GET visibility of Components Service 1707 | 1708 | **Resource URL** 1709 | 1710 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/visibility 1711 | 1712 | [visibility_GET.json](Schemas_draft-03/Collaboration/Viewpoint/visibility_GET.json) 1713 | 1714 | Retrieve visibility of components in a viewpoint. 1715 | 1716 | **Example Request** 1717 | 1718 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/visibility 1719 | 1720 | **Example Response** 1721 | 1722 | Response Code: 200 - OK 1723 | Body: 1724 | { 1725 | "visibility": { 1726 | "default_visibility": true, 1727 | "exceptions": [ 1728 | { 1729 | "ifc_guid": "2MF28NhmDBiRVyFakgdbCT", 1730 | "originating_system": "Example CAD Application", 1731 | "authoring_tool_id": "EXCAD/v1.0" 1732 | }, { 1733 | "ifc_guid": "3$cshxZO9AJBebsni$z9Yk", 1734 | } 1735 | ], 1736 | "view_setup_hints": { 1737 | "spaces_visible": true, 1738 | "space_boundaries_visible": false, 1739 | "openings_visible": true 1740 | } 1741 | } 1742 | } 1743 | 1744 | ### 3.5.9 DELETE Viewpoint Service 1745 | 1746 | **Resource URL** 1747 | 1748 | DELETE /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid} 1749 | 1750 | Deletes a single viewpoint. This operation is only possible when the server returns the `delete` flag in the Viewpoint authorization, see section [3.5.10](#3510-determining-allowed-viewpoint-modifications) 1751 | 1752 | Note: If there is a comment associated to the viewpoint, the server might reject this request: 1753 | - The server should return the http response status code 409 1754 | - The client needs to disaccosiate this comment, before trying again. 1755 | 1756 | **Example Request** 1757 | 1758 | DELETE /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133 1759 | 1760 | **Example Response** 1761 | 1762 | Response Code: 200 - OK 1763 | 1764 | ### 3.5.10 Determining allowed Viewpoint modifications 1765 | 1766 | The global default Viewpoint authorizations are expressed in the project schema and when Viewpoint(s) are requested with the 1767 | query parameter "includeAuthorization" equal to "true" Viewpoints will include an "authorization" field containing any local 1768 | overrides for each Viewpoint. 1769 | 1770 | ## 3.6 Related Topics Services 1771 | 1772 | ### 3.6.1 GET Related Topics Service 1773 | 1774 | **Resource URL** 1775 | 1776 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics 1777 | 1778 | [related_topic_GET.json](Schemas_draft-03/Collaboration/RelatedTopic/related_topic_GET.json) 1779 | 1780 | Retrieve a **collection** of all related topics to a topic. 1781 | 1782 | **Example Request** 1783 | 1784 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics 1785 | 1786 | **Example Response** 1787 | 1788 | Response Code: 200 - OK 1789 | Body: 1790 | [{ 1791 | "related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4" 1792 | }, { 1793 | "related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3" 1794 | }] 1795 | 1796 | ### 3.6.2 PUT Related Topics Service 1797 | 1798 | **Resource URL** 1799 | 1800 | PUT /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics 1801 | 1802 | [related_topic_PUT.json](Schemas_draft-03/Collaboration/RelatedTopic/related_topic_PUT.json) 1803 | 1804 | Add or update a **collection** of all related topics to a topic. This operation is only possible when the server returns the `updateRelatedTopics` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 1805 | 1806 | **Example Request** 1807 | 1808 | PUT /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics 1809 | Body: 1810 | [{ 1811 | "related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4" 1812 | }, { 1813 | "related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3" 1814 | }, { 1815 | "related_topic_guid": "bac66ab4-331e-4f21-a28e-083d2cf2e796" 1816 | }] 1817 | 1818 | **Example Response** 1819 | 1820 | Response Code: 200 - OK 1821 | Body: 1822 | [{ 1823 | "related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4" 1824 | }, { 1825 | "related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3" 1826 | }, { 1827 | "related_topic_guid": "bac66ab4-331e-4f21-a28e-083d2cf2e796" 1828 | }] 1829 | 1830 | ## 3.7 Document Reference Services 1831 | 1832 | Service for relating documents to topics. 1833 | Related documents can be either internal or external, determined by the fields **url** and **document_guid**. 1834 | 1835 | The **url** and the **document_guid** fields are mutually exclusive, which means that only one of these fields are set. 1836 | A document_reference with **url** set, is referencing an external resource. 1837 | A document_reference with **document_guid** set, is referencing an internal **document** which can be downloaded using the [GET Document Service](#383-get-document-service). 1838 | 1839 | ### 3.7.1 GET Document References Service 1840 | 1841 | **Resource URL** 1842 | 1843 | GET /bcf/{version}/projects/{project_id}/topics/{guid}/document_references 1844 | 1845 | [document_reference_GET.json](Schemas_draft-03/Collaboration/DocumentReference/document_reference_GET.json) 1846 | 1847 | Retrieve a **collection** of all document references to a topic. 1848 | 1849 | **Example Request** 1850 | 1851 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references 1852 | 1853 | **Example Response** 1854 | 1855 | Response Code: 200 - OK 1856 | Body: 1857 | [{ 1858 | "guid": "212ab37a-6122-448e-86fc-86503183b520", 1859 | "url": "http://example.com/files/LegalRequirements.pdf", 1860 | "description": "The legal requirements for buildings." 1861 | }, { 1862 | "guid": "6cbfe31d-95c3-4f4d-92a6-420c23698721", 1863 | "document_guid": "472ab37a-6122-448e-86fc-86503183b520", 1864 | "description": "The building owners global design parameters for buildings." 1865 | }] 1866 | 1867 | ### 3.7.2 POST Document Reference Service 1868 | 1869 | **Resource URL** 1870 | 1871 | POST /bcf/{version}/projects/{project_id}/topics/{guid}/document_references 1872 | 1873 | [document_reference_POST.json](Schemas_draft-03/Collaboration/DocumentReference/document_reference_POST.json) 1874 | 1875 | Add a document reference to a topic. This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 1876 | 1877 | Should either reference an internal or an external document. 1878 | - Internal 1879 | * **document_guid** must match an existing **document** in the project 1880 | * **url** must be null 1881 | - External 1882 | * **document_guid** must be null 1883 | * **url** must be the url to the external resource 1884 | 1885 | **Parameters** 1886 | 1887 | JSON encoded body using the "application/json" content type. 1888 | 1889 | |Parameter|Type|Description|Required| 1890 | |---------|----|-----------|--------| 1891 | |guid|string|The desired guid. See OpenCDE Foundation section [1.5.1](https://github.com/buildingSMART/foundation-API#151-conflict-on-creation) when GUID already exists in target system.|false| 1892 | |document_guid|string|The guid of the document (Internal document)|false| 1893 | |url|The url (External document)|false| 1894 | |description|string|The description of the document reference|false| 1895 | 1896 | **Example Request** 1897 | 1898 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references 1899 | Body: 1900 | { 1901 | "url": "http://example.com/files/LegalRequirements.pdf", 1902 | "description": "The legal requirements for buildings." 1903 | } 1904 | 1905 | **Example Response** 1906 | 1907 | Response Code: 201 - Created 1908 | Body: 1909 | { 1910 | "guid": "275ab37a-6122-448e-86fc-86503183b520", 1911 | "url": "http://example.com/files/LegalRequirements.pdf", 1912 | "description": "The legal requirements for buildings." 1913 | } 1914 | 1915 | **Example Request** 1916 | 1917 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references 1918 | Body: 1919 | { 1920 | "document_guid": "472ab37a-6122-448e-86fc-86503183b520", 1921 | "description": "The building owners global design parameters for buildings." 1922 | } 1923 | 1924 | **Example Response** 1925 | 1926 | Response Code: 201 - Created 1927 | Body: 1928 | { 1929 | "guid": "135ab37a-6122-448e-86fc-86503183b520", 1930 | "document_guid": "472ab37a-6122-448e-86fc-86503183b520", 1931 | "description": "The building owners global design parameters for buildings." 1932 | } 1933 | 1934 | ### 3.7.3 PUT Document Reference Service 1935 | 1936 | **Resource URL** 1937 | 1938 | PUT /bcf/{version}/projects/{project_id}/topics/{guid}/document_references/{guid} 1939 | 1940 | [document_reference_PUT.json](Schemas_draft-03/Collaboration/DocumentReference/document_reference_PUT.json) 1941 | 1942 | Update an existing document reference identified by **guid**. 1943 | Uses the same rules as [POST Document Reference Service](#372-post-document-reference-service). This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) 1944 | 1945 | **Example Request** 1946 | 1947 | PUT /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references/472ab37a-6122-448e-86fc-86503183b520 1948 | Body: 1949 | { 1950 | "url": "http://example.com/files/LegalRequirements_Update.pdf", 1951 | "description": "The legal requirements for buildings." 1952 | } 1953 | 1954 | **Example Response** 1955 | 1956 | Response Code: 200 - OK 1957 | Body: 1958 | { 1959 | "guid": "135ab37a-6122-448e-86fc-86503183b520", 1960 | "url": "http://example.com/files/LegalRequirements_Update.pdf", 1961 | "description": "The legal requirements for buildings." 1962 | } 1963 | 1964 | ## 3.8 Document Services 1965 | 1966 | ### 3.8.1 GET Documents Service 1967 | 1968 | [document_GET.json](Schemas_draft-03/Collaboration/Document/document_GET.json) 1969 | 1970 | **Resource URL** 1971 | 1972 | GET /bcf/{version}/projects/{project_id}/documents 1973 | 1974 | Retrieve a **collection** of all documents uploaded to a project. 1975 | 1976 | **Example Request** 1977 | 1978 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents 1979 | 1980 | **Example Response** 1981 | 1982 | Response Code: 200 - OK 1983 | Body: 1984 | [{ 1985 | "guid": "472ab37a-6122-448e-86fc-86503183b520", 1986 | "filename": "LegalRequirements.pdf" 1987 | }, { 1988 | "guid": "6cbfe31d-95c3-4f4d-92a6-420c23698721", 1989 | "filename": "DesignParameters.pdf" 1990 | }] 1991 | 1992 | ### 3.8.2 POST Document Service 1993 | 1994 | **Resource URL** 1995 | 1996 | POST /bcf/{version}/projects/{project_id}/documents 1997 | 1998 | Upload a document (binary file) to a project. This operation is only possible when the server returns the `createDocument` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) 1999 | 2000 | Optional: The desired document guid may be passed as a query parameter. 2001 | 2002 | **Example Request** 2003 | 2004 | POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents?guid=472ab37a-6122-448e-86fc-86503183b520 2005 | 2006 | **Example Response** 2007 | 2008 | Response Code: 201 - Created 2009 | Body: 2010 | { 2011 | "guid": "472ab37a-6122-448e-86fc-86503183b520", 2012 | "filename": "Official_Building_Permission.pdf" 2013 | } 2014 | 2015 | ### 3.8.3 GET Document Service 2016 | 2017 | **Resource URL** 2018 | 2019 | GET /bcf/{version}/projects/{project_id}/documents/{guid} 2020 | 2021 | Retrieves a document as binary file. 2022 | 2023 | **Example Request** 2024 | 2025 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents/472ab37a-6122-448e-86fc-86503183b520 2026 | 2027 | **Example Response** 2028 | 2029 | Retrieves a document as binary file. 2030 | 2031 | ## 3.9 Topics Events Services 2032 | 2033 | The topic events service reflects the events for topics. Each creation or update of a topic generates new topic events. 2034 | Note: Whenever a topic has been created, the server also generates "update" and "add" events for all fields that are initially set. Example: If a topic contains a description, the **description_updated** event is generated. This is to ensure the full history. 2035 | 2036 | ### 3.9.1 GET Topics Events Service 2037 | 2038 | **Resource URL** 2039 | 2040 | GET /bcf/{version}/projects/{project_id}/topics/events 2041 | 2042 | [topic_event_GET.json](Schemas_draft-03/Collaboration/Events/topic_event_GET.json) 2043 | 2044 | Retrieve a **collection** of topic events related to a project (default sort order is `date`). 2045 | 2046 | **Topic event types** 2047 | 2048 | |type|value| 2049 | |---------|-----------| 2050 | |topic_created|null| 2051 | |title_updated|The title (limit: 128 characters)| 2052 | |description_updated|The description (limit: 1024 characters)| 2053 | |description_removed|null| 2054 | |status_updated|The status (value from extensions) | 2055 | |type_updated|The type (value from extensions)| 2056 | |priority_updated|The priority (value from extensions)| 2057 | |priority_removed|null| 2058 | |due_date_updated|The due date| 2059 | |due_date_removed|null| 2060 | |assigned_to_updated|The assigned user (value from extensions)| 2061 | |assigned_to_removed|null| 2062 | |label_added|The label added (value from extensions)| 2063 | |label_removed|The label removed (value from extensions)| 2064 | |stage_added|The stage was added (value from extensions)| 2065 | |stage_updated|The stage was updated (value from extensions)| 2066 | |stage_removed|The stage was removed (value from extensions)| 2067 | 2068 | **Odata filter parameters** 2069 | 2070 | |parameter|type|description| 2071 | |---------|----|-----------| 2072 | |topic_guid|string|guid of the topic | 2073 | |author|string|userId of the author (value from extensions)| 2074 | |type|string|type of the event (value from Topic event types, table above)| 2075 | |date|datetime|date of the event| 2076 | 2077 | **Odata sort parameters** 2078 | 2079 | |parameter|description| 2080 | |---------|-----------| 2081 | |date|date of the event| 2082 | 2083 | **Example Request with odata** 2084 | 2085 | Get events of type 'status_updated' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent 2086 | 2087 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=author eq 'Architect@example.com' and type eq 'status_updated' and date gt 2015-12-05T00:00:00+01:00&$orderby=date asc 2088 | 2089 | Get latest events of given topic. Skip the 10 first, and get the 5 next 2090 | 2091 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=topic_guid eq 'A245F4F2-2C01-B43B-B612-5E456BEF8116'&$top=5&$skip=10 2092 | 2093 | Get events that are of type 'status_updated', 'type_updated' or 'title_updated' or 'label_added' 2094 | 2095 | /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=type eq 'status_updated' or type eq 'type_updated' or type eq 'title_updated' or type eq 'label_added' 2096 | 2097 | **Example Request** 2098 | 2099 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events 2100 | 2101 | **Example Response** 2102 | 2103 | Response Code: 200 - OK 2104 | Body: 2105 | [{ 2106 | "topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414", 2107 | "date": "2014-11-19T14:24:11.316Z", 2108 | "author": "Architect@example.com", 2109 | "events": [ 2110 | { 2111 | "type": "status_updated", 2112 | "value": "Closed" 2113 | } 2114 | ] 2115 | }, { 2116 | "topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 2117 | "date": "2013-10-21T17:34:22.409Z", 2118 | "author": "Architect@example.com", 2119 | "events": [ 2120 | { 2121 | "type": "type_updated", 2122 | "value": "Warning" 2123 | } 2124 | ] 2125 | }] 2126 | 2127 | ### 3.9.2 GET Topic Events Service 2128 | 2129 | **Resource URL** 2130 | 2131 | GET /bcf/{version}/projects/{project_id}/topics/{topic_guid}/events 2132 | 2133 | [topic_event_GET.json](Schemas_draft-03/Collaboration/Events/topic_event_GET.json) 2134 | 2135 | Retrieve a **collection** of topic events related to a project (default sort order is `date`). 2136 | 2137 | **Topic event types** 2138 | 2139 | |type|value| 2140 | |---------|-----------| 2141 | |topic_created|null| 2142 | |title_updated|The title (limit: 128 characters)| 2143 | |description_updated|The description (limit: 1024 characters)| 2144 | |description_removed|null| 2145 | |status_updated|The status (value from extensions) | 2146 | |type_updated|The type (value from extensions)| 2147 | |priority_updated|The priority (value from extensions)| 2148 | |priority_removed|null| 2149 | |due_date_updated|The due date| 2150 | |due_date_removed|null| 2151 | |assigned_to_updated|The assigned user (value from extensions)| 2152 | |assigned_to_removed|null| 2153 | |label_added|The label added (value from extensions)| 2154 | |label_removed|The label removed (value from extensions)| 2155 | |stage_added|The stage was added (value from extensions)| 2156 | |stage_updated|The stage was updated (value from extensions)| 2157 | |stage_removed|The stage was removed (value from extensions)| 2158 | 2159 | **Odata filter parameters** 2160 | 2161 | |parameter|type|description| 2162 | |---------|----|-----------| 2163 | |author|string|userId of the author (value from extensions)| 2164 | |type|string|type of the event (value from Topic event types, table above)| 2165 | |date|datetime|date of the event| 2166 | 2167 | **Odata sort parameters** 2168 | 2169 | |parameter|description| 2170 | |---------|-----------| 2171 | |date|date of the event| 2172 | 2173 | **Example Request with odata** 2174 | 2175 | Get events of type 'status_updated' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent 2176 | 2177 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$filter=author eq 'Architect@example.com' and type eq 'status_updated' and date gt 2015-12-05T00:00:00+01:00&$orderby=date asc 2178 | 2179 | Get latest events. Skip the 10 first, and get the 5 next 2180 | 2181 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$top=5&$skip=10 2182 | 2183 | Odata does not support list operators. To achieve list query, use the 'or' operator. 2184 | Get events that is of type 'status_updated', 'type_updated' or 'title_updated' or 'label_added' 2185 | 2186 | /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$filter=type eq 'status_updated' or type eq 'type_updated' or type eq 'title_updated' or type eq 'label_updated' 2187 | 2188 | **Example Request** 2189 | 2190 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events 2191 | 2192 | **Example Response** 2193 | 2194 | Response Code: 200 - OK 2195 | Body: 2196 | [{ 2197 | "topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 2198 | "date": "2014-11-19T14:24:11.316Z", 2199 | "author": "Architect@example.com", 2200 | "events": [ 2201 | { 2202 | "type": "type_updated", 2203 | "value": "Error" 2204 | } 2205 | ] 2206 | }, { 2207 | "topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 2208 | "date": "2013-10-21T17:34:22.409Z", 2209 | "author": "Architect@example.com", 2210 | "events": [ 2211 | { 2212 | "type": "status_updated", 2213 | "value": "Open" 2214 | } 2215 | ] 2216 | }] 2217 | 2218 | ## 3.10 Comments Events Services 2219 | 2220 | The comment events service reflects the events for topic comments. Each creation or update of a comment generates new comment events. 2221 | 2222 | Note: Whenever a comment has been created, the server also generates "update" events for all fields that are initially set. Example: If a comment contains a viewpoint, the **viewpoint_updated** event is generated. This is to ensure the full history. 2223 | 2224 | ### 3.10.1 GET Comments Events Service 2225 | 2226 | **Resource URL** 2227 | 2228 | GET /bcf/{version}/projects/{project_id}/topics/comments/events 2229 | 2230 | [comment_event_GET.json](Schemas_draft-03/Collaboration/Events/comment_event_GET.json) 2231 | 2232 | Retrieve a **collection** of comment events related to a project (default sort order is `date`). 2233 | 2234 | **Comment event types** 2235 | 2236 | |type|value| 2237 | |---------|-----------| 2238 | |comment_created|null| 2239 | |comment_text_updated|The comment text(limit: 1024 characters)| 2240 | |viewpoint_updated|The viewpoint guid| 2241 | |viewpoint_removed|null| 2242 | 2243 | **Odata filter parameters** 2244 | 2245 | |parameter|type|description| 2246 | |---------|----|-----------| 2247 | |comment_guid|string|guid of the comment | 2248 | |topic_guid|string|guid of the topic | 2249 | |author|string|userId of the author (value from extensions)| 2250 | |date|datetime|date of the event| 2251 | |type|string|type of the event (value from Comment event types, table above)| 2252 | 2253 | **Odata sort parameters** 2254 | 2255 | |parameter|description| 2256 | |---------|-----------| 2257 | |date|date of the event| 2258 | 2259 | **Example Request with odata** 2260 | 2261 | Get events of type 'comment_created' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent 2262 | 2263 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events?$filter=author eq 'Architect@example.com' and date gt 2015-12-05T00:00:00+01:00 and type eq 'comment_created'&$orderby=date asc 2264 | 2265 | Get latest events of given comment. Skip the 10 first, and get the 5 next 2266 | 2267 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events?$filter=comment_guid eq 'C4215F4D-AC45-A43A-D615-AA456BEF832B'&$top=5&$skip=10 2268 | 2269 | Get events that are of type 'comment_created', or 'viewpoint_updated' 2270 | 2271 | /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=type eq 'comment_created' or type eq 'viewpoint_updated' 2272 | 2273 | **Example Request** 2274 | 2275 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events 2276 | 2277 | **Example Response** 2278 | 2279 | Response Code: 200 - OK 2280 | Body: 2281 | [{ 2282 | "comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B", 2283 | "topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414", 2284 | "date": "2014-11-19T14:24:11.316Z", 2285 | "author": "Architect@example.com", 2286 | "events": [ 2287 | { 2288 | "type": "comment_created", 2289 | "value": null 2290 | } 2291 | ] 2292 | }, { 2293 | "comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B", 2294 | "topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 2295 | "date": "2013-10-21T17:34:22.409Z", 2296 | "author": "Architect@example.com", 2297 | "events": [ 2298 | { 2299 | "type": "viewpoint_updated", 2300 | "value": "b24a82e9-f67b-43b8-bda0-4946abf39624" 2301 | } 2302 | ] 2303 | }] 2304 | 2305 | ### 3.10.2 GET Comment Events Service 2306 | 2307 | **Resource URL** 2308 | 2309 | GET /bcf/{version}/projects/{project_id}/topics/{topic_guid}/comments/{comment_guid}/events 2310 | 2311 | [comment_event_GET.json](Schemas_draft-03/Collaboration/Events/comment_event_GET.json) 2312 | 2313 | Retrieve a **collection** of comment events related to a single comment (default sort order is `date`). 2314 | 2315 | **Comment event types** 2316 | 2317 | |type|value| 2318 | |---------|-----------| 2319 | |comment_created|null| 2320 | |comment_text_updated|The comment text(limit: 1024 characters)| 2321 | |viewpoint_updated|The viewpoint guid| 2322 | |viewpoint_removed|null| 2323 | 2324 | **Odata filter parameters** 2325 | 2326 | |parameter|type|description| 2327 | |---------|----|-----------| 2328 | |author|string|userId of the author (value from extensions)| 2329 | |date|datetime|date of the event| 2330 | |type|string|type of the event (value from Comment event types, table above)| 2331 | 2332 | **Odata sort parameters** 2333 | 2334 | |parameter|description| 2335 | |---------|-----------| 2336 | |date|date of the event| 2337 | 2338 | **Example Request with odata** 2339 | 2340 | Get events of type 'comment_created' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent 2341 | 2342 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$filter=author eq 'Architect@example.com' and date gt 2015-12-05T00:00:00+01:00 and type eq 'comment_created'&$orderby=date asc 2343 | 2344 | Get latest events of given comment. Skip the 10 first, and get the 5 next 2345 | 2346 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$top=5&$skip=10 2347 | 2348 | Get events that are of type 'comment_created', or 'comment_text_updated' 2349 | 2350 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$filter=type eq 'comment_created' or type eq 'viewpoint_updated' 2351 | 2352 | **Example Request** 2353 | 2354 | GET /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events 2355 | 2356 | **Example Response** 2357 | 2358 | Response Code: 200 - OK 2359 | Body: 2360 | [{ 2361 | "comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B", 2362 | "topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414", 2363 | "date": "2014-11-19T14:24:11.316Z", 2364 | "author": "Architect@example.com", 2365 | "events": [ 2366 | { 2367 | "type": "comment_created", 2368 | "value": null 2369 | } 2370 | ] 2371 | }, { 2372 | "comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B", 2373 | "topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116", 2374 | "date": "2013-10-21T17:34:22.409Z", 2375 | "author": "Architect@example.com", 2376 | "events": [ 2377 | { 2378 | "type": "comment_text_updated", 2379 | "value": "This is the updated comment" 2380 | } 2381 | ] 2382 | }] 2383 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Action/comment_actions.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "comment_actions", 3 | "required": false, 4 | "type": "array", 5 | "items": { 6 | "type": "string", 7 | "enum": ["update", 8 | "delete"] 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Action/project_actions.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "project_actions", 3 | "required": false, 4 | "type": "array", 5 | "items": { 6 | "type": "string", 7 | "enum": ["update", 8 | "createTopic", 9 | "createDocument"] 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Action/topic_actions.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "topic_actions", 3 | "required": false, 4 | "type": "array", 5 | "items": { 6 | "type": "string", 7 | "enum": ["update", 8 | "updateBimSnippet", 9 | "updateRelatedTopics", 10 | "updateDocumentReferences", 11 | "updateFiles", 12 | "createComment", 13 | "createViewpoint", 14 | "delete"] 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Action/viewpoint_actions.json: -------------------------------------------------------------------------------- 1 | { 2 | "required": false, 3 | "type": "array", 4 | "items": { 5 | "enum": ["delete"] 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Comment/comment_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "comment_GET", 3 | "type": "object", 4 | "properties": { 5 | "guid": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "date": { 10 | "required": true, 11 | "type": "string" 12 | }, 13 | "author": { 14 | "required": true, 15 | "type": "string" 16 | }, 17 | "comment": { 18 | "required": true, 19 | "type": "string" 20 | }, 21 | "topic_guid": { 22 | "required": true, 23 | "type": "string" 24 | }, 25 | "viewpoint_guid": { 26 | "type": ["string", 27 | "null"] 28 | }, 29 | "modified_date": { 30 | "type": ["string", 31 | "null"] 32 | }, 33 | "modified_author": { 34 | "type": ["string", 35 | "null"] 36 | }, 37 | "authorization": { 38 | "type": "object", 39 | "required": false, 40 | "properties": { 41 | "comment_actions": { 42 | "$ref": "../Action/comment_actions.json" 43 | } 44 | } 45 | } 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Comment/comment_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "comment_POST", 3 | "type": "object", 4 | "properties": { 5 | "guid": { 6 | "type": ["string", 7 | "null"] 8 | }, 9 | "comment": { 10 | "required": true, 11 | "type": "string" 12 | }, 13 | "viewpoint_guid": { 14 | "type": ["string", 15 | "null"] 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Comment/comment_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "comment_PUT", 3 | "type": "object", 4 | "properties": { 5 | "comment": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "viewpoint_guid": { 10 | "type": ["string", 11 | "null"] 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Document/document_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "document_GET", 3 | "type": "object", 4 | "properties": { 5 | "guid": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "filename": { 10 | "required": true, 11 | "type": "string" 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/Collaboration/DocumentReference/document_reference_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "document_reference_GET", 4 | "description": "Schema for a single document reference GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "guid": { 8 | "required": true, 9 | "type": "string" 10 | }, 11 | "document_guid": { 12 | "type": ["string", "null"] 13 | }, 14 | "url": { 15 | "type": ["string", "null"] 16 | }, 17 | "description": { 18 | "type": ["string", "null"] 19 | } 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /Schemas/Collaboration/DocumentReference/document_reference_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "document_reference_POST", 3 | "type": "object", 4 | "properties": { 5 | "guid": { 6 | "type": ["string", "null"] 7 | }, 8 | "document_guid": { 9 | "type": ["string", "null"] 10 | }, 11 | "url": { 12 | "type": ["string", "null"] 13 | }, 14 | "description": { 15 | "type": ["string", "null"] 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /Schemas/Collaboration/DocumentReference/document_reference_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "document_reference_PUT", 3 | "type": "object", 4 | "properties": { 5 | "document_guid": { 6 | "type": ["string", "null"] 7 | }, 8 | "url": { 9 | "type": ["string", "null"] 10 | }, 11 | "description": { 12 | "type": ["string", "null"] 13 | } 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Events/comment_event_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "comment_event_GET", 3 | "type": "object", 4 | "properties": { 5 | "comment_guid": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "topic_guid": { 10 | "required": true, 11 | "type": "string" 12 | }, 13 | "date": { 14 | "required": true, 15 | "type": "string" 16 | }, 17 | "author": { 18 | "required": true, 19 | "type": "string" 20 | }, 21 | "actions": { 22 | "type": "array", 23 | "minItems": 1, 24 | "items": { 25 | "$ref": "event_action.json" 26 | } 27 | } 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Events/event_action.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "event_action", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "type": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "value": { 10 | "type": ["string", 11 | "null"] 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Events/topic_event_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "topic_event_GET", 3 | "type": "object", 4 | "properties": { 5 | "topic_guid": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "date": { 10 | "required": true, 11 | "type": "string" 12 | }, 13 | "author": { 14 | "required": true, 15 | "type": "string" 16 | }, 17 | "actions": { 18 | "type": "array", 19 | "minItems": 1, 20 | "items": { 21 | "$ref": "event_action.json" 22 | } 23 | } 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /Schemas/Collaboration/File/file_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "file_GET", 4 | "description": "Schema for a single file GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "ifc_project": { 8 | "type": ["string", 9 | "null"] 10 | }, 11 | "ifc_spatial_structure_element": { 12 | "type": ["string", 13 | "null"] 14 | }, 15 | "filename": { 16 | "type": ["string", 17 | "null"] 18 | }, 19 | "date": { 20 | "type": ["string", 21 | "null"] 22 | }, 23 | "reference": { 24 | "type": ["string", 25 | "null"] 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /Schemas/Collaboration/File/file_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "file_PUT", 3 | "type": "object", 4 | "properties": { 5 | "ifc_project": { 6 | "type": ["string", 7 | "null"] 8 | }, 9 | "ifc_spatial_structure_element": { 10 | "type": ["string", 11 | "null"] 12 | }, 13 | "filename": { 14 | "type": ["string", 15 | "null"] 16 | }, 17 | "date": { 18 | "type": ["string", 19 | "null"] 20 | }, 21 | "reference": { 22 | "type": ["string", 23 | "null"] 24 | } 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /Schemas/Collaboration/File/project_file_display_information.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "project_file_display_information", 4 | "description": "Schema for the display information of a project file, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "field_display_name": { 8 | "required": true, 9 | "type": "string" 10 | }, 11 | "field_value": { 12 | "required": true, 13 | "type": "string" 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /Schemas/Collaboration/File/project_file_information.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "project_file_information", 3 | "description": "Schema for a single project file information, BCF REST API.", 4 | "type": "object", 5 | "properties": { 6 | "display_information": { 7 | "type": "array", 8 | "items": { "$ref": "project_file_display_information.json" }, 9 | "default": [] 10 | }, 11 | "file": { "$ref": "file_GET.json" } 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /Schemas/Collaboration/File/project_files_information_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Schema for the listing the response of the GET project files information service", 3 | "title": "project_files_information_GET", 4 | "type": "array", 5 | "items": { 6 | "$ref": "project_file_information.json" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /Schemas/Collaboration/RelatedTopic/related_topic_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "related_topic_GET", 4 | "description": "Schema for single related topic GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "related_topic_guid": { 8 | "required": true, 9 | "type": "string" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/Collaboration/RelatedTopic/related_topic_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "related_topic_PUT", 4 | "description": "Schema for related topic PUT, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "related_topic_guid": { 8 | "required": true, 9 | "type": "string" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Topic/bim_snippet.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "bim_snippet", 3 | "type": ["object", 4 | "null"], 5 | "properties": { 6 | "snippet_type": { 7 | "required": true, 8 | "type": "string" 9 | }, 10 | "is_external": { 11 | "required": true, 12 | "type": "boolean" 13 | }, 14 | "reference": { 15 | "required": true, 16 | "type": "string" 17 | }, 18 | "reference_schema": { 19 | "required": true, 20 | "type": "string" 21 | } 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Topic/topic_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "topic_GET", 3 | "type": "object", 4 | "properties": { 5 | "guid": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "server_assigned_id": { 10 | "required": true, 11 | "type": "string" 12 | }, 13 | "topic_type": { 14 | "type": ["string", 15 | "null"] 16 | }, 17 | "topic_status": { 18 | "type": ["string", 19 | "null"] 20 | }, 21 | "reference_links": { 22 | "type": ["array", 23 | "null"], 24 | "items": { 25 | "type": "string" 26 | } 27 | }, 28 | "title": { 29 | "required": true, 30 | "type": "string" 31 | }, 32 | "priority": { 33 | "type": ["string", 34 | "null"] 35 | }, 36 | "index": { 37 | "type": [ 38 | "integer", 39 | "null" 40 | ] 41 | }, 42 | "labels": { 43 | "type": ["array", 44 | "null"], 45 | "items": { 46 | "type": ["string", 47 | "null"] 48 | } 49 | }, 50 | "creation_date": { 51 | "required": true, 52 | "type": "string" 53 | }, 54 | "creation_author": { 55 | "required": true, 56 | "type": "string" 57 | }, 58 | "modified_date": { 59 | "type": "string" 60 | }, 61 | "modified_author": { 62 | "type": ["string", 63 | "null"] 64 | }, 65 | "assigned_to": { 66 | "type": ["string", 67 | "null"] 68 | }, 69 | "stage": { 70 | "type": ["string", 71 | "null"] 72 | }, 73 | "description": { 74 | "type": ["string", 75 | "null"] 76 | }, 77 | "bim_snippet": { 78 | "$ref": "bim_snippet.json" 79 | }, 80 | "due_date": { 81 | "type": ["string", 82 | "null"] 83 | }, 84 | "authorization": { 85 | "type": "object", 86 | "required": false, 87 | "properties": { 88 | "topic_actions": { 89 | "$ref": "../Action/topic_actions.json" 90 | }, 91 | "topic_status": { 92 | "type": ["array", 93 | "null"], 94 | "items": { 95 | "type": "string" 96 | } 97 | } 98 | } 99 | } 100 | } 101 | } 102 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Topic/topic_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "topic_POST", 4 | "description": "Schema for topic POST, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "guid": { 8 | "type": ["string", 9 | "null"] 10 | }, 11 | "topic_type": { 12 | "type": ["string", 13 | "null"] 14 | }, 15 | "topic_status": { 16 | "type": ["string", 17 | "null"] 18 | }, 19 | "reference_links": { 20 | "type": ["array", 21 | "null"], 22 | "items": { 23 | "type": "string" 24 | } 25 | }, 26 | "title": { 27 | "required": true, 28 | "type": "string" 29 | }, 30 | "priority": { 31 | "type": ["string", 32 | "null"] 33 | }, 34 | "index": { 35 | "type": [ 36 | "integer", 37 | "null" 38 | ] 39 | }, 40 | "labels": { 41 | "type": ["array", 42 | "null"], 43 | "items": { 44 | "type": ["string", 45 | "null"] 46 | } 47 | }, 48 | "assigned_to": { 49 | "type": ["string", 50 | "null"] 51 | }, 52 | "stage": { 53 | "type": ["string", 54 | "null"] 55 | }, 56 | "description": { 57 | "type": ["string", 58 | "null"] 59 | }, 60 | "bim_snippet": { 61 | "$ref": "bim_snippet.json" 62 | }, 63 | "due_date": { 64 | "type": ["string", 65 | "null"] 66 | } 67 | } 68 | } 69 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Topic/topic_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "topic_PUT", 4 | "description": "Schema for topic PUT, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "topic_type": { 8 | "type": ["string", 9 | "null"] 10 | }, 11 | "topic_status": { 12 | "type": ["string", 13 | "null"] 14 | }, 15 | "reference_links": { 16 | "type": ["array", 17 | "null"], 18 | "items": { 19 | "type": "string" 20 | } 21 | }, 22 | "title": { 23 | "required": true, 24 | "type": "string" 25 | }, 26 | "priority": { 27 | "type": ["string", 28 | "null"] 29 | }, 30 | "index": { 31 | "type": [ 32 | "integer", 33 | "null" 34 | ] 35 | }, 36 | "labels": { 37 | "type": ["array", 38 | "null"], 39 | "items": { 40 | "type": ["string", 41 | "null"] 42 | } 43 | }, 44 | "assigned_to": { 45 | "type": ["string", 46 | "null"] 47 | }, 48 | "stage": { 49 | "type": ["string", 50 | "null"] 51 | }, 52 | "description": { 53 | "type": ["string", 54 | "null"] 55 | }, 56 | "bim_snippet": { 57 | "$ref": "bim_snippet.json" 58 | }, 59 | "due_date": { 60 | "type": ["string", 61 | "null"] 62 | } 63 | } 64 | } 65 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/bitmap_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "properties": { 4 | "guid": { 5 | "type": "string" 6 | }, 7 | "bitmap_type": { 8 | "type": "string", 9 | "enum": ["jpg", "png"] 10 | }, 11 | "location": { 12 | "$ref": "location.json" 13 | }, 14 | "normal": { 15 | "$ref": "direction.json" 16 | }, 17 | "up": { 18 | "$ref": "direction.json" 19 | }, 20 | "height": { 21 | "type": "number" 22 | } 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/bitmap_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "properties": { 4 | "bitmap_type": { 5 | "type": "string", 6 | "enum": ["jpg", "png"] 7 | }, 8 | "bitmap_data": { 9 | "type": "string", 10 | "format": "base64" 11 | }, 12 | "location": { 13 | "$ref": "location.json" 14 | }, 15 | "normal": { 16 | "$ref": "direction.json" 17 | }, 18 | "up": { 19 | "$ref": "direction.json" 20 | }, 21 | "height": { 22 | "type": "number" 23 | } 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/clipping_plane.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "clipping_plane", 3 | "type": ["object", 4 | "null"], 5 | "properties": { 6 | "location": { 7 | "$ref": "location.json" 8 | }, 9 | "direction": { 10 | "$ref": "direction.json" 11 | } 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/coloring.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "coloring", 3 | "type": "object", 4 | "properties": { 5 | "color": { 6 | "type": "string" 7 | }, 8 | "components": { 9 | "$ref": "component_list.json" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/coloring_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "coloring_GET", 4 | "description": "Schema for coloring GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "coloring": { 8 | "type": ["array", "null"], 9 | "items": { 10 | "$ref": "coloring.json" 11 | } 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/component.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "component", 3 | "type": ["object"], 4 | "properties": { 5 | "ifc_guid": { 6 | "type": ["string", "null"] 7 | }, 8 | "originating_system": { 9 | "type": ["string", "null"] 10 | }, 11 | "authoring_tool_id": { 12 | "type": ["string", "null"] 13 | } 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/component_list.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "component list", 3 | "type": ["array", "null"], 4 | "items": { 5 | "$ref": "component.json" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/components.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "components", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "selection": { 6 | "$ref": "component_list.json" 7 | }, 8 | "coloring": { 9 | "type": ["array", "null"], 10 | "items": { 11 | "$ref": "coloring.json" 12 | } 13 | }, 14 | "visibility": { 15 | "$ref": "visibility.json" 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/direction.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "direction", 3 | "type": "object", 4 | "properties": { 5 | "x": { 6 | "type": "number" 7 | }, 8 | "y": { 9 | "type": "number" 10 | }, 11 | "z": { 12 | "type": "number" 13 | } 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/line.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "line", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "start_point": { 6 | "$ref": "point.json" 7 | }, 8 | "end_point": { 9 | "$ref": "point.json" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/location.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "location", 3 | "type": ["object", 4 | "null"], 5 | "properties": { 6 | "x": { 7 | "type": "number" 8 | }, 9 | "y": { 10 | "type": "number" 11 | }, 12 | "z": { 13 | "type": "number" 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/orthogonal_camera.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "orthogonal_camera", 3 | "type": ["object", 4 | "null"], 5 | "properties": { 6 | "camera_view_point": { 7 | "$ref": "point.json" 8 | }, 9 | "camera_direction": { 10 | "$ref": "direction.json" 11 | }, 12 | "camera_up_vector": { 13 | "$ref": "direction.json" 14 | }, 15 | "view_to_world_scale": { 16 | "type": "number" 17 | }, 18 | "aspect_ratio": { 19 | "type": "number" 20 | } 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/perspective_camera.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "perspective_camera", 3 | "type": ["object", 4 | "null"], 5 | "properties": { 6 | "camera_view_point": { 7 | "$ref": "point.json" 8 | }, 9 | "camera_direction": { 10 | "$ref": "direction.json" 11 | }, 12 | "camera_up_vector": { 13 | "$ref": "direction.json" 14 | }, 15 | "field_of_view": { 16 | "type": "number" 17 | }, 18 | "aspect_ratio": { 19 | "type": "number" 20 | } 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/point.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "point", 3 | "type": "object", 4 | "properties": { 5 | "x": { 6 | "type": "number" 7 | }, 8 | "y": { 9 | "type": "number" 10 | }, 11 | "z": { 12 | "type": "number" 13 | } 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/selection_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "selection_GET", 4 | "description": "Schema for selection GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "selection": { 8 | "$ref": "component_list.json" 9 | } 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/snapshot_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "snapshot_GET", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "snapshot_type": { 6 | "type": ["string"], 7 | "enum": ["jpg", "png"] 8 | } 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/snapshot_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "snapshot_POST", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "snapshot_type": { 6 | "type": ["string"], 7 | "enum": ["jpg", "png"] 8 | }, 9 | "snapshot_data": { 10 | "type": ["string"], 11 | "format": "base64" 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/view_setup_hints.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "view_setup_hints", 3 | "type": ["object", "null"], 4 | "properties": { 5 | "spaces_visible": { 6 | "type": "boolean", 7 | "default": "false" 8 | }, 9 | "space_boundaries_visible": { 10 | "type": "boolean", 11 | "default": "false" 12 | }, 13 | "openings_visible": { 14 | "type": "boolean", 15 | "default": "false" 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/viewpoint_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "viewpoint_GET", 3 | "type": "object", 4 | "properties": { 5 | "index": { 6 | "type": [ 7 | "integer", 8 | "null" 9 | ] 10 | }, 11 | "guid": { 12 | "required": true, 13 | "type": "string" 14 | }, 15 | "orthogonal_camera": { 16 | "$ref": "orthogonal_camera.json" 17 | }, 18 | "perspective_camera": { 19 | "$ref": "perspective_camera.json" 20 | }, 21 | "lines": { 22 | "type": ["array", "null"], 23 | "items": { 24 | "$ref": "line.json" 25 | } 26 | }, 27 | "clipping_planes": { 28 | "type": ["array", "null"], 29 | "items": { 30 | "$ref": "clipping_plane.json" 31 | } 32 | }, 33 | "bitmaps": { 34 | "type": ["array", "null"], 35 | "items": { 36 | "$ref": "bitmap_GET.json" 37 | } 38 | }, 39 | "snapshot": { 40 | "$ref": "snapshot_GET.json" 41 | }, 42 | "authorization": { 43 | "type": "object", 44 | "required": false, 45 | "properties": { 46 | "viewpoint_actions": { 47 | "$ref": "../Action/viewpoint_actions.json" 48 | } 49 | } 50 | } 51 | } 52 | } 53 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/viewpoint_POST.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "viewpoint_POST", 3 | "type": [ "object" ], 4 | "properties": { 5 | "guid": { 6 | "type": ["string", 7 | "null"] 8 | }, 9 | "index": { 10 | "type": [ 11 | "integer", 12 | "null" 13 | ] 14 | }, 15 | "orthogonal_camera": { 16 | "$ref": "orthogonal_camera.json" 17 | }, 18 | "perspective_camera": { 19 | "$ref": "perspective_camera.json" 20 | }, 21 | "lines": { 22 | "type": ["array", "null"], 23 | "items": { 24 | "$ref": "line.json" 25 | } 26 | }, 27 | "clipping_planes": { 28 | "type": ["array", "null"], 29 | "items": { 30 | "$ref": "clipping_plane.json" 31 | } 32 | }, 33 | "bitmaps": { 34 | "type": ["array", "null"], 35 | "items": { 36 | "$ref": "bitmap_POST.json" 37 | } 38 | }, 39 | "snapshot": { 40 | "$ref": "snapshot_POST.json" 41 | }, 42 | "components": { 43 | "$ref": "components.json" 44 | } 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/visibility.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "visibility", 3 | "type": "object", 4 | "properties": { 5 | "default_visibility": { 6 | "type": "boolean", 7 | "default": "false" 8 | }, 9 | "exceptions": { 10 | "$ref": "component_list.json" 11 | }, 12 | "view_setup_hints": { 13 | "$ref": "view_setup_hints.json" 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /Schemas/Collaboration/Viewpoint/visibility_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "visibility_GET", 4 | "description": "Schema for visibility GET, BCF REST API.", 5 | "type": "object", 6 | 7 | "properties": { 8 | "visibility": { 9 | "$ref": "visibility.json" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/Project/extensions_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "extensions_GET", 3 | "type": "object", 4 | "properties": { 5 | "topic_type": { 6 | "required": true, 7 | "type": ["array", 8 | "null"], 9 | "items": { 10 | "type": ["string", 11 | "null"] 12 | } 13 | }, 14 | "topic_status": { 15 | "required": true, 16 | "type": ["array", 17 | "null"], 18 | "items": { 19 | "type": ["string", 20 | "null"] 21 | } 22 | }, 23 | "topic_label": { 24 | "required": true, 25 | "type": ["array", 26 | "null"], 27 | "items": { 28 | "type": ["string", 29 | "null"] 30 | } 31 | }, 32 | "snippet_type": { 33 | "required": true, 34 | "type": ["array", 35 | "null"], 36 | "items": { 37 | "type": ["string", 38 | "null"] 39 | } 40 | }, 41 | "priority": { 42 | "required": true, 43 | "type": ["array", 44 | "null"], 45 | "items": { 46 | "type": ["string", 47 | "null"] 48 | } 49 | }, 50 | "users": { 51 | "required": true, 52 | "type": ["array", 53 | "null"], 54 | "items": { 55 | "type": ["string", 56 | "null"] 57 | } 58 | }, 59 | "stage": { 60 | "required": true, 61 | "type": ["array", 62 | "null"], 63 | "items": { 64 | "type": ["string", 65 | "null"] 66 | } 67 | }, 68 | "project_actions": { 69 | "$ref": "../Collaboration/Action/project_actions.json" 70 | }, 71 | "topic_actions": { 72 | "$ref": "../Collaboration/Action/topic_actions.json" 73 | }, 74 | "comment_actions": { 75 | "$ref": "../Collaboration/Action/comment_actions.json" 76 | } 77 | } 78 | } 79 | -------------------------------------------------------------------------------- /Schemas/Project/project_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "project_GET", 4 | "description": "Schema for single project GET, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "project_id": { 8 | "type": "string", 9 | "required": true 10 | }, 11 | "name": { 12 | "type": "string", 13 | "required": true 14 | }, 15 | "authorization": { 16 | "type": "object", 17 | "required": false, 18 | "properties": { 19 | "project_actions": { 20 | "$ref": "../Collaboration/Action/project_actions.json" 21 | } 22 | } 23 | } 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /Schemas/Project/project_PUT.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "project_PUT", 4 | "description": "Schema for project PUT, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "name": { 8 | "type": "string", 9 | "required": true 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /Schemas/User/user_GET.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "user_GET", 3 | "type": "object", 4 | "properties": { 5 | "id": { 6 | "required": true, 7 | "type": "string" 8 | }, 9 | "name": { 10 | "type": ["string", 11 | "null"] 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /Schemas/error.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-03/schema#", 3 | "title": "Error", 4 | "description": "Schema for error, BCF REST API.", 5 | "type": "object", 6 | "properties": { 7 | "message": { 8 | "type": "string", 9 | "required": true 10 | } 11 | } 12 | } 13 | --------------------------------------------------------------------------------