Copyright © 2011 the Secretariat for the OmniClass™ Development Committee. All Rights Reserved. http://www.omniclass.org/
OmniClass is part of NBIMS 2.0:
Introduction
On July 7, 2012 the OmniClass™ tables listed below are the first WebService on the BIM CLOUD. OmniClass™ is part of the National BIM Standard Version 2 published by the National Institute of Building Sciences buildingSMARTalliance™.
On June 19, 2012 a Data Exchange Forum was held at the National Institute of Building Sciences in Washington DC. A discussion during this Forum centered around how WebServices could be used to manage standards.
The Need for BuildingSMART Standards through WebServices
Onuma’s opinion is that standards such as OmniClass™ should be managed and maintained in a database and made accessible through WebServices to the industry. In order for standards to be accepted they need to be made accessible, consistent and easy to implement by developers. OmniClass™ was used as a discussion point since a lot of effort has been put into the development of it and it’s relatively easy structure to make it an ideal candidate for WebServices.
Some concerns expressed by the participants in the June 19, 2012 Forum:
- Maintaining a version control of the standard published via WebServices
- Some solutions do not want real time updates through WebServices, they only want periodic updates
- Archiving the version of the standard for older projects
These concerns are not related to where a software gets the data but what is included in the data source and how a solution implements the versioning. The client can request whatever version it needs through the WebService call. If the returned data includes mapping to older or newer versions, the client can even make a translation from one version to another very easily. The client application can be designed for the user to choose the version or convert one version into another. With appropriate mapping like it was started with OmniClass, the client of the WebServices can even convert the classification from one System (such as OmniClass) to another (e.g. OSCRE). All this without having the burden to verify that the file at hand is a “correct” version or was not altered compared to the “official” version. The authoritative WebService makes certain we are all using the same data.
Challenges
Up until now the OmniClass™ tables were available only in PDF or Excel format. The main tables are available here: http://www.omniclass.org/ and Table 13, 21, 22, 23, 32 and 36 are in PDF format in the National BIM Standard 2.0 http://www.nationalbimstandard.org/. There are several problems with this approach that have nothing to do with WebServices, this is strictly a management and maintenance issue. PDF and non structured Excel files are not the best way to manage standards and not the easiest format for software solutions to consume the data. Managing and maintaining versions becomes a problem when it is in two locations such as the PDFs in the National BIM Standard and the PDFs on the OmniClass™ website and with multiple worksheets with (hopefully) the same data on each sheet. The consistency of the data in the Excel files has not been historically good. This is a challenge of using Excel as a mechanism to maintain the standard, and not using a database. This makes it difficult for software vendors to rely on the data.
Decision to Implement WebServices for OmniClass™
Subsequent to the meeting of June 19, 2012 several discussions between Onuma Inc. and the directors of buidlingSMARTalliance relating to WebServices occured. Onuma Inc. volunteered to enable a first version of WebServices for OmniClass™ that would be made open and available to the industry as a working prototype to use for software development, and expansion of the buildingSMART standards. It was decided that since OmniClass™ was part of the National BIM Standard 2.0 it would be an appropriate use of the standard to enable it through WebServices.
The decision to implement was driven by the fact that creating a WebService for OmniClass™ was simple and it makes a lot of sense to go this route. Having a working version of it makes it easier to test in active applications and spread the use of buildingSMART standards by encouraging software developers to directly use the standard. Now that we have this first version we encourage others in the industry to use it, test and comment on where to go next with this development.
Implementation
On this page is a fully functioning prototype for OmniClass™ WebServices that can be used by software developers in solutions.
The process and time involved in converting the published OmniClass™ tables from Excel into WebServices were:
- Open Excel files and import them into a simple database tool to check for consistency of the structure.
- Create a Scheme in XML of the OmniClass™ tables using http://www.oxygenxml.com/. Approximately 2 hours.
- Upload the OmniClass™ tables to the BIM CLOUD Server. Approximately 2 hours to set up and upload.
- Activate WebServices for OmniClass™. Approximately 2 hours.
The biggest challenge of activating WebServices for OmniClass™ was step 1, analyzing the Excel files for the logic and correcting errors in the data. We are keeping this apart from the discussion of creating the WebServices since it does not have anything to do with actually creating the XML Schema and activating the WebServices.
The Result
Since this initial setup has been completed, subsequent edits and updates will go much faster. The main message is that it is relatively easy to activate WebServices especially for a simple flat structure of data such as OmniClass™ . Once it is WebServices enabled, managing, maintaining and publishing the standard for the industry to use and the value of OmniClass™ is increased.
Authoritative Source
Our recommendation is that subsequent updates of data in OmniClass™ happen in a database and not in Excel files. This WebService for OmniClass™ can stay here or can be moved over to OmniClass.org. It is critical that the authoritative source of OmniClass™ drive the maintenance and update of data. Our belief is that as more BIM standards are implemented it is crucial for the end user and developer to have machine readable access to standards.
Use of the OmniClass™ WebServices in Software Applications
The resulting WebService here is now 100% useable for software solutions. We welcome other Software Vendors to use the OmniClass™ WebServices and provide input and guidance in further developing WebServices for other BIM Standards.
The ONUMA System uses the OmniClass™ WebServices by pulling the tables in real time from the BIM Cloud Server to the ONUMA System interface. Here are some screen shots of that interface:
Going Forward
Some data in the Excel files of OmniClass™ had other data that could be very valuable in WebServices. For example Table 13 has a tab called “transition matrix” that has the beginning of mapping to other space standards such as OSCRE, ASTM, GSA, VA and other acronyms. There is almost enough information and structure in this tab to include it, but not quite enough. There are enough questions, inconsistencies and terms that are not clear that would make it difficult to implement. We see a lot of good information and effort in these tables and believe with some input from the authors of the data, it would be possible to WebService enable these as well. The end result would be that software vendors could then easily implement tools to switch from standard to standard.
The reality of standard development is that it is a dynamic process. Because of this, it becomes even more critical to have a WebServices and data centric approach to managing and publishing the standards.
Available Tables as WebServices
- Table 13 - Spaces by Function
- Version 1 - 2006
- Version 2 - 2010-06-24
- Table 21 - Elements
- Version 1 - 2006
- Version 2 - 2011-02-11
- Table 22 - Work Results
- Version 1 - 2006
- Version 2 - 2011-04-11
- Table 23 - Products
- Version 1 - 2006-03-28
- Version 2 - 2010-06-24
- Table 32 - Services
- Version 1 - 2006
- Version 2 - 2011-02-11
- Table 36 - Information
- Version 1 - 2006
- Version 2 - 2011-02-11
REST API
- GET the full table:
http://bim-cloud.com/rest/omniclass/2/23/
(note: this might take a while to load since it includes over 6,000 classes) - or GET a specific "Level", for example Level 1 of table 23:
http://bim-cloud.com/rest/omniclass/2/23/Level1 - or GET only one class with all its parents and descendants:
http://bim-cloud.com/rest/omniclass/2/23/23-13%2039%2027
(23-13 39 27 - Roof Cladding)
Notes:
- The URL always contains the content (/omniclass/), the version according to the table above (/2/) and the table number (/23/).
- In addition, either the Level to be returned or the specific class to be returned can be added. Important: the URL has to be URL-encoded, in other words, the empty spaces in the OmniClass number has to be replaced by "%20" as seen in the URL example above.
- Each class that is returned includes the attributes "number" and "title", which is really all that is needed for the classification. The service also returns a child element for each class with extended attributes such as definitions, discussions, and the mapping to the previous or following version of the same OmniClass table (for applications to translate versions).
- The above extended attribute element also includes a URL-encoded URI for each class' WebService request.
- The Schema for this XML response can be found here:
http://bim-cloud.com/xsd/001/omniclass-001.xsd - The documentation for this schema can be viewed here:
http://bim-cloud.com/omniclass-001.html