Introduction

This template guide contains the documentation for Simplebim Excel templates that were the solution for BIM wrangling automation in Simplebim until version 10. Simplebim versio 11 introduces Dataflows that are replacing the old Excel based templates. The old templates can still be used as part of Dataflows via a Dataflow step that applies the Excel template file.

Template System Overview

Templates are used for automating operations in Simplebim. Templates are straight forward Excel files that follow a certain structure. For creating templates you can modify one of the templates that ship with Simplebim, download samples from the Simplebim web site or create a new template from scratch.

Templates can be ultra-simple, containing just a few items. But you can also create very advanced templates by chaining templates (applying templates in a sequence) and running tools as part of your template. Templates can also be integrated to Simplebim add-ons such that a template is applied automatically by the add-on, and templates can even be used by the Simplebim command line for batch processing models.

When you use a template you first import or open a model, create a Dataflow with one or more Apply Template steps and run the dataflow.

When you have applied your template, please be sure to check the template report. This report gives you in-depth information about how the template was interpreted, including any warnings and errors that may have occurred.

You can install templates by copying them into the User Templates folder. Installed templates show up in the Dataflow Presets dialog used for adding Dataflow steps making them very easy to use. The other option is to add the Apply Template step and select a template from anywhere on your system using a File Open dialog.

Excel does not have to be installed on the computer where the templates are used. You need Excel only for editing the templates.

This guide applies to Simplebim version 10.0. Older template versions are backward compatible, so you do not have to convert your templates to the latest version. However, when you create new templates we recommend that you always use the latest version.

Template Structure

Simplebim® templates are Excel files that have a pre-defined set of Worksheets and on each Worksheet a set of Sections. You should not change the names of the Worksheets or Sections and you should also not re-arrange the Sections.

Worksheet Overview

Templates contain the following Worksheets

Template worksheets are applied from left to right and the sections on each worksheet from top to bottom.

Template Sections

The following information and rules apply to all sections in a template.

Fields with a green background are mandatory; fields with a purple background are optional. Optional fields are either not always needed or have a default value that you can find in the documentation. 

Cells may have dropdown lists that you can use for selecting from a list of valid values.

Sections with a variable number of rows have horizontal headers and 3 rows by default. You can add any number of new rows to such a section. You can also have empty rows within a section, but if you have more than 100 empty rows in a sequence the subsequent rows and any sections after will not be processed.

The best way to add new rows is to start your row selection from a middle row (not first and not last), select down as many rows as you wish to add and select Insert. This will maintain the formatting of the new rows, including dropdown lists on the cells.

Using Excel Techniques

It is easier to maintain your templates and avoid mistakes if you reference cells containing e.g. a name or key instead of copying that name or key to a different cell. You can use any Excel techniques, including formulas, to manage your template data more effectively.

Using Names and Keys

In many places fields accept both a Name and a Key. The Name of an item (template, object, property etc.) is a human understandable name shown in the user interface. The key is the internal identification of the item used by Simplebim for uniquely identifying the item. Normally the Name works well, but if two or more items have the same Name, then the key can be used for distinguishing between these items. Using the Name is easy but contains some risk when several items have the same name. Using the Key is always safe, but templates that use Keys are more difficult for humans to read.

NOTE: Names and keys are always case insensitive and any whitespace (spaces) at the beginning and end of the name or key are ignored

Using Value Lists

In many places a cells accept a list of values. Such properties are marked with a [+]. The following techniques can be used for defining lists.

You can use any combination of the techniques described above in a single cell that accepts a list of values.

Disabling Template Items

The special asterisk character ‘*’ can be used for disabling a row anywhere in the template, except in Substitution. Simply place the asterisk sign on the applicable row in column B, and that row will be ignored when the template is processed.

Setting Reporting Actions

By default a warning is written into the Template Log when a template item is not valid in the context of the model to which it is applied. For example trying to manipulate the value of property ‘A’ will result in a warning if the model does not contain property ‘A’.. This default behaviour can be overridden with Reporting Actions. The Reporting Action is specified in Column B with the following values.

You can disable a template item that has a Reporting Action. The notation for this is *f, *w or *n.

Finding Help for Using Templates

Templates include a lot of different kind of rules you can apply to the models. Each rule have a dedicated section in the Template files. Each section have a subtitle, which is also a link to the documentation. The easiest way to get help for a specific rule is simply to click on the link in subtitle.

You don’t have to master all the rules in order to start automating you BIM data wrangling with Templates. You can simply start by creating a new Template, then finding the right rule to apply, clicking on the subtitle to learn how to use the rule, and then applying it.

Note that the rule specific links and documentation are available from Simplebim 10 SR1 onwards. The older versions of the Templates have only higher level documentation links.

Settings Worksheet

Template -section

When you install a template the information in this section is used for displaying and organizing templates in the user interface. For templates that are not installed this section can be left empty.

A picture inserted anywhere on the Settings worksheet will be used as the icon of the template in the Simplebim user interface. The recommended size for the picture is 64×64 pixels.

Model Author -section

Information in this section appears in the ‘Author and License’ dialog in the Simplebim user interface and is written to IFC as a property set attached to the project.

Model License -section

Information in this section appears in the ‘Author and License’ dialog in the Simplebim user interface and is written to IFC as a property set attached to the project.

Depends on Templates –section

This section is used for chaining templates by defining which templates must be applied before the current template is applied.

When you start using templates in a more advanced way it becomes important that your templates are easy to maintain. You want to avoid copying the same information into multiple templates, because then updating your templates after changes becomes difficult.

A good practice is to keep all your identity definitions in one template and make your other templates dependent on that template. This way you have a central repository for your identities.

Another good practice is to separate generic content from project specific content. You might for example have one template that trims a model for quantity take-off and another template that validates the model for quantity take-off based on agreement made in a specific project. You may also have company specific content such as model author information that you don’t want to repeat in multiple templates and model license information that needs to be defined separately for each exchange.

Template chaining works such, that the more specific template is made dependent on the more generic templates. The template you apply in Simplebim is on the top of this structure (‘Project A’ in the example below) and it pulls in all the other dependent templates. Templates are applied in a sequence where the top template is applied last. This allows you to override content in the more generic templates by content from the more specific ones.

IFC Import Settings –section

With IFC import settings you can optimize the IFC import. When you exclude information from the import this will speed up the import but the excluded information will not be available to you when you validate, copy-edit and export the model.

IFC Import Configuration –section

In this section you can configure the IFC import on a lower level. The items in ‘IFC Import Settings’ are shortcuts for configurations that could also be done in this section, but not all possible configurations have these shortcuts.

IFC Export Settings –section

With IFC export settings you can control several aspects of the IFC export. The same settings can be found in the IFC Export Settings dialog in Simplebim.

Resources Worksheet

Define IFC Property (PropertySet) –section

In this section you can define identities that are mapped to IFC PropertySets

Advanced

You can use any text you want as the Property Key as long as the key is unique. However, if you want to avoid creating duplicate properties when the property with an identical mapping already exists in the model, you either need to leave the Property Key empty or use a specific format for the Property Key. If you want to explicitly define the Property Key, the easiest way to get the correct key is to import an IFC file containing that property into Simplebim, select that property in the Properties palette and choose ‘Copy Special’ > ’Copy Key’ from the context menu. Finally paste the value into the Property Key field in the template.

The format for PropertySet keys is:

IFC:F:IP:<PSET_NAME>:<PROPERTY_NAME>:<PROPERTY_TYPE>

The old format starting with IFC2X3:FLAT:PROP is also still supported

The property type values are:

• Text = STRING
• Whole Number = INTEGER
• Decimal Number = DOUBLE
• Yes/No = BOOLEAN
• For all others the applicable IFC entity, for example IFCLENGTHMEASURE

Define IFC Property (Element Quantity) –section

In this section you can define properties that are mapped to IFC Element Quantities

Advanced

You can use any text you want as the Property Key as long as the key is unique. However, if you want to avoid creating duplicate properties when the property with an identical mapping already exists in the model, you either need to leave the Property Key empty or use a specific format for the Property Key. If you want to explicitly define the Property Key, the easiest way to get the correct key is to import an IFC file containing that property into Simplebim, select that property in the Properties palette and choose ‘Copy Special’ > ’Copy Key’ from the context menu. Finally paste the value into the Property Key field in the template.

The format for ElementQuantity keys is:

IFC:F:IQ:<QUANTITYSET_NAME>:<QUANTITY_NAME>

The old format starting with IFC2X3:FLAT:QTY is also still supported

Define Property –section

In this section you can define properties that can be shown in Simplebim and can be exported to e.g. Excel, but are not necessarily mapped to IFC. You could for example define properties that translate object and property names to your own language.

If you want to define properties that are mapped to IFC PropertySets or Element Quantities, please use the dedicated sections instead.

Add Property Source –section

The Property Source is an entity that defines properties. This entity could be for example you, a standards organization or the project you are working on.

Add Property Metadata –section

In this section you can add metadata to identities in order to modify their behaviour in Simplebim. This is an advanced technique for add-on developers, who have a deeper understanding of the identity concept in Simplebim.

Model Worksheet

Set Units –section

Units can be set for the model and for the template.

Setting the model units affects the unit definition of the model (the model is converted to these units) and thus also the exported IFC file. If no value is given for a model unit, the unit defined in the imported IFC model is used.

The template units define the interpretation of any measure values used in the template. If no value is given for a template unit the model unit is assumed. Template units have no effect on the units of the exported IFC file.

Add Identity to Object –section

In this section you can add new identities (names) for Object Classes. This has no effect on the IFC export but allows you for example to translate the names of object classes to your own language in the Simplebim user interface.

Add Property to Object Class or Group –section

In this section you can add new properties to Object Classes, Groups or Group Categories. You use the Identities defined on the Resources sheet for adding new properties.

Adding a property to an Object Class automatically includes that property in the model view. If you want to exclude the property you added, you must exclude it explicitly in the ‘Include/Exclude Property’ section of the ModelView worksheet. 

Add Identity to Property –section

In this section you can add new identities (names) for properties. This has no effect on the IFC export but allows you for example to translate the names of properties to your own language in the Simplebim user interface.

Swap Property Values –section

In this section you can swap the values of two properties. When you swap property values (instead of copy) the values of both properties remain in the model for future use.

Trim Text Property Values –section

You can use this section to trim away part of a text property value, for example a prefix or postfix. You could for example trim a ‘Basic Wall’ prefix from the building element construction type of walls.

There is a separate section in the template for trimming before copy operations and after copy operations because the order of events determines if the trim is applied to a copied value or to the original value.

Find and Replace Text Property Values –section

You can use this section for setting the value of a text property based on the current value of the same property. You could for example replace ‘Mtg.’ with ‘Meeting’ in space names.

NOTE: There is a separate section in the template for find and replace before copy operations and after copy operations because the order of events determines if the find and replace is applied to a copied value or to the original value.

Set Property Values Based on Text Property Value –section

In this section you can set the value of one property based on the text value of another property. You could for example set the IsExternal property to ‘Yes’ for all walls that have a building element construction type that starts with ‘EXT’.

There is a separate section in the template for setting property values before copy operations and after copy operations because the order of events determines if finding the objects for which the property values are set is done based on a copied value or to the original value.

If you need a large number of such operations the Enrichment system is probably the better alternative because it is much more compact and easy to manage. 

Copy Property Values –section

This section is superseded by the Copy Property Values -tool that can be used as a Dataflow step. All future improvements will be made to this tool.

In this section you can copy text property values from one property to another. Using regular expression you can also copy only a part of the original value.

You can easily ‘Merge Copy‘ values from several properties with the same name into a new property. When you specify a name (not key) as the ‘From Property’, the system scans all properties with that name and tries to copy values from all of them. When using Merge Copy you need to set ‘Overwrite Non Empty Values’ to ‘No’, otherwise the actual values may be overwritten with an empty value.

If the ‘From Property’ and ‘To Property’ have the same name, for example you are copying values from one property set to another and both property sets have the same property names, you must use a Key as the ‘To Property’ to specify the target explicitly. In this scenario the ‘From Property’ can be either a Name or a Key. The system will automatically filter out the ‘To Property’ from the list of possible ‘From Properties’, which means that the ‘To Property’ and ‘From Property’ will never be the same.

Rotate Site Around Pivot Point –section

In this section you can move and rotate the site object around a given pivot point, typically for preparing a model for use as part of a combined model.

X, Y and Z must be in the length unit measure (mm, m, inch, feet…) of the model.

Move and Rotate Site –section

In this section you can move and rotate the site object, typically for preparing a model for use as part of a combined model.

X, Y and Z must be in the length unit measure (mm, m, inch, feet…) of the model.

Move and Rotate Project –section

In this section you can move and rotate the project object, typically for preparing a model for use as part of a combined model.

X, Y and Z must be in the length unit measure (mm, m, inch, feet…) of the model.

ModelView Worksheet

Include/Exclude Objects Based on Object Class or Group –section

In this section you can include and exclude objects based on their object class or membership in a group. You could for example exclude all furniture or include all objects in a ‘Building Envelope’ group. See the Groups –worksheet chapter of this guide for more information about groups.

If you want to start with a clean slate, use the special value ‘All’ for Object or Group on the first row. This will exclude all objects in the model. Then you can start including the objects you really need.

The following object classes cannot be excluded via templates: Project, Site, Building and Building Storey

Include/Exclude Property –section

In this section you can include and exclude properties from Object Classes.

If you want to start with a clean slate, use the special value ‘All’ for both Object and Property on the first row. This will exclude all properties for all objects. Then you can start including the properties you really need.

Set Object Color and Transparency Based on Object Class or Group –section

In this section you can set the 3D appearance of objects, i.e. their color and transparency.

Validation Worksheet

Required Objects –section

In this section you can define the object classes and groups for which the model must contain objects, for example that the model must contain walls, or that a ‘Building Envelope’ Group must contain objects.

Required Properties –section

In this section you can define the properties that must have values. If a model does not have objects of a given Object Class or a Group is empty, then the required properties for that Object Class or Group are not validated. You can for example require that the Name property of all Space objects has a value, but this requirement only applies if the model has Space objects.

Validate Text Property Values –section

In this section you can define validation rules for text properties. You can for example define a list of allowed values for space names, an allowed pattern for building storey names or that space numbers must be unique.

If multiple rules are defined for the same property, the new rules will override the previous ones and only the last rule will be used. However, you can define different rules for the same property in the context of an Object Class and in the context of Groups.

The following table contains a short description of the different rule types

Enrichment Worksheet

Enrichment -section

With Enrichment you can efficiently merge data from external sources into the model by setting property values to objects that match a given criteria. You can add as many Enrichment Worksheets into the workbook as you like and they will be processed if the name of the Worksheet starts with ‘Enrichment’. Each Enrichment Worksheet can contain as many Enrichment sections as you wish.

Each Enrichment section must be formatted like this.

The easiest way to get this right is to copy and paste the sample section on the Enrichment worksheet.

Insert the name of the Object Class or Group on Column C on the row where Column B has the text ‘Object or Group [+]’ (Cell C4 in the picture above).

Use the special value ‘[GROUP]’ as the ‘Object or Group [+]’ to set the values of the properties of a group. In this option the match property is always the name of the group and the operator in Match (case insensitive). You would use this option for example if you want to set the start and end dates of groups that represent tasks. In this case you would not set the dates for the objects in the groups, but for the groups themselves.

Define one Match property by giving a property name or key. This property is used for finding the objects for which the other properties are set. The match property must be a Text property. The Match operator can have the following values.

The format for the Operator in a Match cell is ’Match=<Operator>’, for example ‘Match=Equals’. If the Operator is mixed case the match will be case sensitive, otherwise case insensitive.

All whitespace (spaces) is trimmed from the Operator, for example ‘Starts With’ is the same as ‘StartsWith’.

You can use the special value [EMPTY] as the match value. Using this value means that you want to enrich all objects where the Match property has no value.

Define as many Set -properties (Operator = Set) as you wish by giving a property name or key. If needed simply add new properties on column F, G, H and so on. These are the properties for which the values are set. Set properties can be of any data type (text, number, measure…). Do not leave any empty columns in between.

Enrichment DOES NOT add the Set -properties to the model, they must already exist in the model or you must add the properties to the model.

This is because a name is not enough for defining a property. In addition to the name, as a minimum the name of the property set and the data type of the property are needed.

You can also define Info properties (Operator = Info) that are not processed but could help you better understand the data or save you the trouble of deleting columns you don’t want to include. Info columns can be used between Set columns.

On the rows below the header (containing the Object Class and Properties) add as many rows as you wish. Each row must have a value for the Match Property and optionally values for the Set Properties. Do not put any value into the cell on column B, because column B is reserved for use by the system.

If you set measure value, please pay attention to the Template Units.

Substitution Worksheet

Substitution Lists -section

Substitution is a technique for making templates more compact and easier to read and manage. In substitution you define a named list of values and use that name in other parts of the template instead of the original list of values.

Starting with Simplebim 10 the substitution list has, for convenience, a ‘All Elements’ list that contains all IFC building element classes.

You could for example define a Substitution List with the names of all Object Classes that are relevant to structural design and call it ‘Structural Objects’. Then you could define another list containing the names of all properties that are used by all structural objects and call it ‘Common Structural Properties’. Let’s say there are 10 items in both lists. Now when you want to include the common properties for all structural objects you would simply do the following…

Without Substitution you would have 10 rows in the ‘Include/Exclude Objects Based on Object Class or Group’ section and 100 rows in the ‘Include/Exclude Property’ section. You could also use the same substitution lists in other places, like in validation. Later when you notice a mistake (something missing, spelling mistake…) in a substitution list, you can simply edit the list on the Substitution worksheet and your template is fixed.

Groups Worksheet

Add Group Categories –section

In this section you can add new Group Categories to the model. Group categories are used for organizing groups and defining properties that are common to all groups in a category.

You can add properties to group categories in the Add Property to Object Class or Group -section of the Model Worksheet by using the key or name of the group category in the Object or Group field.

Define Groups Based on Property Values –section

In this section you can define new groups using rules.

When you define a group that already exist the existing group is redefined. The matching for the existing group happens by group name and the comparison is case insensitive. For classification items the operator is starts with, which means that you can use the identification instead of the full name as the group name. For all other groups the operator is Equals. When a existing group is redefined the group category is maintained. For example if you redefine an IFC Zone, then the redefined group is also an IFC Zone.

Assign Groups to Group Categories –section

In this section you can map groups to IFC and assign Groups to Group Categories, for example define that your group will be exported to IFC as an IfcZone. Simplebim automatically creates Group Categories for all IFC group types, like IfcGroup. IfcSystem or IfcZone. You can in addition create your own group Categories for organizing Group that you use in Simplebim.

By default the groups you define in templates will not be exported to IFC. You must map them to IFC if you want to export them to IFC.

Add Classification Systems –section

In this section you can define hierarchical classification systems that are exported to IFC using dedicated classification resource of IFC.

Unlike in other sections, in this section the first row defines the classification system and the subsequent rows the items of the classification system.

You may define several classification systems in the same section by first defining the first classification system and then adding a new First Row for the second classification system followed by the subsequent rows for that classification system.

First Row

Subsequent Rows

The hierarchy of the classification system is created by indenting the rows for the classification items based on their hierarchy level in the classification system.

For the first level of the classification system the first non empty column is column D, the second non empty column E and the third non empty column F.

For the second level of the classification system the first non empty column is column E, the second non empty column F and the third non empty column G.

Example