Window of Authorization

Inhoud

Window of Authorization (WoA)

An important aspect of the COINS information transaction process using COINS Containers is the control over the data access rights of the person who executes an assignment. A BIM contributor typically needs access to a subset of the central BIM and will generally add, update or delete information objects to this sub-model. It should be completely unambiguous if a certain information object is accessible (read access) or can be updated (write access).

The Window of Authorization is able to specify the access status for all information objects of the central CBIM in a very compact way. The main principle is to mark certain nodes of the object tree with explicit access rights (write access, read access or no access) and to propagate these access rights along the tree branches and along the information objects that can be reached from there.

The Window of Authorization specification forms no part of the CBIM itself. A central BIM may have many parallel WoA's in several concurrent transactions. A WoA is therefore saved in a separate XML file and shipped in a separate folder of the COINS Container.

WoA Specification

Window of Authorization specification example.
Window of Authorization specification example.

The WoA specification uses the object tree as its base structure. The procedure is to specify the access rights for a set of function fulfillers explicitly while afterwards an algorithm uses some rules to decide what the access rights will be of all the other information objects (including object instances of other classes).
A function fulfiller object may express three different access rights:

  • write access
    Write access means that in principle all attribute and relation types of the function fulfiller are open for updating (adding, removing, modifying). The 'in principle' addition means that certain restrictions may apply.
    The function fulfiller that explicitly receives write access rights (in contrast to getting these rights as a derivation from an ancestor) are beforehand limited (limited write access) in updating its relations (especially in the same layer and above).
  • read access
    Read access means that in principle all attribute and relation types of the function fulfiller are open for reading (inspecting, traversing). The 'in principle' addition means that certain restrictions may apply.
    The function fulfiller that explicitly receives read access rights (in contract to getting these rights as a derivation from an ancestor) are beforehand limited (limited read access) in inspecting and traversing its relations (especially in the same layer and above).
  • no access
    No access means that such an object can in no way be accessed. Even its very existence is hidden, which is practically achieved by leaving them out during the export procedure to a COINS Container.

The WoA specification can be serialized into an XML file. For example the WoA of the COINS BIM shown above could be expressed as follows:

<?xml version="1.0" encoding="UTF-8"?>
<woa:WindowOfAuthorization xmlns:woa="http://www.coinsweb.nl"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="nl/coinsweb/cbim/woa/WindowOfAuthorization.xsd">
   <woa:WriteAccess>
       <woa:RootObject layerDepth="1"
           objectID="http://www.coinsweb.nl/woa-example.owl#_b6f6ac82-295e-11b2-80a1-840ad48ff048">
           <woa:Name>B1.1</woa:Name>
           <woa:UserID/>
           <woa:LinkAccess>http://www.coinsweb.nl/c-bim.owl#physicalChild</woa:LinkAccess>
       </woa:RootObject>
   </woa:WriteAccess>
   <woa:ReadAccess>
       <woa:RootObject layerDepth="2"
           objectID="http://www.coinsweb.nl/woa-example.owl#_b6f6ac80-295e-11b2-80a1-840ad48ff048">
           <woa:Name>B1</woa:Name>
           <woa:UserID/>
       </woa:RootObject>
   </woa:ReadAccess>
</woa:WindowOfAuthorization>

The WoA specification may contain up to three sections: to specify the write access area, read access area and no access area respectively. In this example the no-access part is left out which means that it is implicitly defined: any object that has no write access or read access is automatically regarded to be a no-access object.

<woa:WriteAccess>
    <woa:RootObject layerDepth="1"
        objectID="http://www.coinsweb.nl/woa-example.owl#_b6f6ac82-295e-11b2-80a1-840ad48ff048">
        <woa:Name>B1.1</woa:Name>
        <woa:UserID/>
        <woa:LinkAccess>http://www.coinsweb.nl/c-bim.owl#physicalChild</woa:LinkAccess>
    </woa:RootObject>
</woa:WriteAccess>

The write access area specification mentions one function fulfiller (B1.1) as a write access area root object that extends one layer deep and thus includes its children (B1.1.1, B1.1.2, B1.1.3). The link access element specifies that only child relations of the root object are open for updating (besides the attribute values), which facilitates, in this particular case, adding or removing child objects to this root object.

<woa:ReadAccess>
   <woa:RootObject layerDepth="2"
       objectID="http://www.coinsweb.nl/woa-example.owl#_b6f6ac80-295e-11b2-80a1-840ad48ff048">
       <woa:Name>B1</woa:Name>
       <woa:UserID/>
   </woa:RootObject>
</woa:ReadAccess>

The read access area specification mentions one function fulfiller (B1) as a read access area root object that extends two layers deep and thus includes its children and grandchildren (B1.1, B1.2, B1.2.1). The write access area has precedence over the read access area so function fulfiller B1.1 is only upward read-only and its children are entirely not affected though they are located in the two-layer read access area.

WoA specification propagation rules

A WoA specification only specifies access rights for a subset of the function fulfillers. A set of rules dictates how to determine the access rights of the rest of the function fulfillers and all information objects that are no function fulfillers at all. Those rules are:

  • If a so called WoA root object (i.e. a function fulfiller that has explicitly defined access rights) has a layer depth greater than 0 descendant function fulfillers inherit the access rights of this root object.
  • Within the object tree a write access area overrules a read access area and a read access area overrules a no-access area.
  • Function fulfillers outside any access area belong implicitly to the no-access area.
  • Other (no function fulfiller) information objects that are referenced by a function fulfiller inherit the same access rights.
  • If such an information object is referenced by more than one function fulfiller the most restricted rights take precedence, i.e. a read access right takes precedence of a write access right and a no-access rights takes always precedence other access rights. There is one exception with regard to baseline objects. The reason is that baselines often will contain a mix function fulfillers (write access, read access or no-access) and would end therefore as a no-access information object itself. That would be undesirable, besides baselines have a protection mechanism of its own: a baseline can be open or closed for updating. Of course only information objects with write access can be updated in an open baseline. Normally you won't expect information objects with write access in a closed baseline. When this situation occurs the closed baseline status should take precedence.
  • The previous rule can be applied recurrently between the rest of the model objects. The algorithm should take care that all function fulfillers are assigned their access rights first. Other information objects cannot overrule this status afterwards.
  • Finally, all (non-function fulfiller) information objects that cannot be reached using above procedure will receive by default write-access rights.

Explicit individual object WoA specification

Besides the specification method based on object tree access individual CBIM objects can declared explicitly to reside in an authorization class. This possibility is sometimes needed to overrule the standard propagation rules or when, in an early model stage, the object tree is not available yet.

WoA during the transaction

The WoA specification XML file should be part of a COINS container. By convention, it is stored in a folder named woa.

XML Schema

The serialization of the WoA specification is in XML format. The XML Schema is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:woa="http://www.coinsweb.nl" targetNamespace="http://www.coinsweb.nl"
	elementFormDefault="qualified" attributeFormDefault="unqualified"
	version="0.1">
	<xs:element name="WindowOfAuthorization" type="woa:WindowOfAuthorizationType">
		<xs:annotation>
			<xs:documentation>Window of Authorization specifies the access rights
				of the accompanying building information model.
			</xs:documentation>
		</xs:annotation>
	</xs:element>
	<xs:complexType name="WindowOfAuthorizationType">
		<xs:sequence>
			<xs:element name="WriteAccess" type="woa:WriteAccessType"
				minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="ReadAccess" type="woa:ReadAccessType"
				minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="NoAccess" type="woa:NoAccessType"
				minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="WriteAccessType">
		<xs:sequence>
			<xs:element name="RootObject" type="woa:RootObjectType"
				minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="CbimObject" type="woa:CbimObjectType"
				minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ReadAccessType">
		<xs:sequence>
			<xs:element name="RootObject" type="woa:RootObjectType"
				minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="CbimObject" type="woa:CbimObjectType"
				minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="NoAccessType">
		<xs:sequence>
			<xs:element name="RootObject" type="woa:RootObjectType"
				minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="CbimObject" type="woa:CbimObjectType"
				minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="RootObjectType">
		<xs:sequence>
			<xs:element name="Name" type="xs:string" minOccurs="0"
				maxOccurs="1" />
			<xs:element name="UserID" type="xs:string" minOccurs="0"
				maxOccurs="1" />
			<xs:element name="LinkAccess" type="woa:PropertyType"
				minOccurs="0" maxOccurs="unbounded"
				default="http://www.coinsweb.nl/c-bim.owl#physicalChild" />
		</xs:sequence>
		<xs:attribute name="objectID" type="woa:ObjectIDType"
			use="required" />
		<xs:attribute name="layerDepth" type="woa:LayerDepthType"
			default="1" />
	</xs:complexType>
	<xs:complexType name="CbimObjectType">
		<xs:sequence>
			<xs:element name="Name" type="xs:string" minOccurs="0"
				maxOccurs="1" />
			<xs:element name="UserID" type="xs:string" minOccurs="0"
				maxOccurs="1" />
		</xs:sequence>
		<xs:attribute name="objectID" type="woa:ObjectIDType"
			use="required" />
	</xs:complexType>
	<xs:simpleType name="LayerDepthType">
		<xs:restriction base="xs:integer"></xs:restriction>
	</xs:simpleType>
	<xs:simpleType name="ObjectIDType">
		<xs:restriction base="xs:anyURI" />
	</xs:simpleType>
	<xs:simpleType name="PropertyType">
		<xs:restriction base="xs:anyURI" />
	</xs:simpleType>
</xs:schema>

WoA checking

There are two ways to check on violations of the WoA specification:

  • during the actual updating by a COINS compatible application
  • during a merge operation of a COINS container with the central BIM

The first option is primarily to assist the person charged to update the model. He/she will be informed immediately that a certain modification is not allowed by the prevailing WoA.
Various (configurable) implementation forms can be used. The COINS Navigator for example warns but enables the user to neglect this warning. The idea behind it is the possibility that the WoA is too restrictively defined for the job in question. Informal communication could agree about broadening the write access area.
It could of course also happen that an application add-on cannot prevent (read: has insufficient access) WoA violations. In that case a separate WoA checker could do the job.
Before the actual merge operation a final check is done. The COINS Building Information System should offer sufficient control how to deal with encountered violations.

As a rule, more than one transaction will stand out at an arbitrary point in time. The BIM manager should have an overview of all those transactions and their corresponding WoA's. In principle, write access areas should not overlap. This will prevent update clashes. The WoA specification offers fine tuning in updating the relationships giving write access for relation type A (for example updating parent/child relations) while blocking write access for relation type B (for example attaching planning objects).

WoA specification in the COINS Navigator

Window of Authorization pop-up menu.
Window of Authorization pop-up menu.
A Window of Authorization can be specified using the object tree panel. Selecting a function fulfiller and right clicking shows a pop-up menu including a Window of Authorization sub-menu. The menu-items trigger the following functions:
  • Add write access
    Declare this object a read/write access root.
  • Add read access
    Declare this object a read-only access root.
  • Add no access
    Declare this object inaccessible.
  • Link access
    Sub-menu to fine-grain the link accessibility.
  • Remove access
    Remove the access specification.
  • Increase layer depth
    Increase the number of downward layers this access specification can reach. Initially the number of layers is set to 0 meaning: the same layer as the function fulfiller itself.
  • Decrease layer depth
    Inverse function of increase layer depth.
  • Read WoA
    Import a WoA description file.
  • Write WoA
    Export a WoA description file.
  • Propagate WoA
    Propagate the WoA root object specifications over all the information objects of the BIM.
  • Reset WoA
    Remove the current WoA specification.

Colour coding

Figure 44: Example colour coding in the object tree panel.
Figure 44: Example colour coding in the object tree panel.
To have a quick clue about the access status of a certain information object the COINS Navigator uses colour coding:
  • Green
    Full read/write access.
  • Turquoise
    Limited read/write access for certain link types.
  • Blue
    Full read-only access.
  • Violet
    Limited read access for certain link types.
  • Red
    No access.

The red colour code (no access rights) can only be observed in a CBIS environment. During the generation of a COINS Container the no-access information objects are simply skipped.

WoA violation messages

Figure 45: Window of Authorization violation warning.
Figure 45: Window of Authorization violation warning.
The COINS Navigator actively checks all changes to a CBIM object. If a violation is detected a warning message is issued.

The COINS Navigator offers the option to ignore the WoA specification. The reason is that during the execution of the assignment it may turn out that the WoA was defined to restrictively. In that case it could be very cumbersome to generate a new COINS Container and restart the transaction. Then it could be handy to circumvent the authorization. Still there is a final check during the merge operation with the central BIM. At that point in the transaction this violation will be detected and must be approved or rejected.

Afkomstig van CoinsWiki NL, de Vrije Encyclopedie. "http://www.coinsweb.nl/wiki/index.php/Window_of_Authorization"
Personal tools