Importing data via Excel

If you have a large amount of legacy data that you want to add to BriefBuilder, you may want to import that data by means of an Excel import.

Importing Excel data can be very powerful, but it should be said that preparing the import Excel sheets can be a complex operation as these sheets need to be structured in particular way.

Excel imports can be done by means of the import button that can be found at in the menu at the top of each tree. When clicking on that you can choose between importing objects from another BriefBuilder model or doing an Excel import.

Below we will explain how Excel imports work in BriefBuilder.

We recommend that you read the instructions below closely and that try out your Excel import in a sandbox clone of your project before you do the import in your live project model.

What kind of data can you import?

You can import the following data:

• Objects
• Properties
• Relations
• Analysis data for objects, properties, and relations

You can see an example of how you can capture these different kinds of data in the Excel file below. Download an empty template in your language here.

The example concerns an import of data for the Spaces & Locations tree. It adds several new meeting rooms (objects; first tab), including their properties (second tab), and their relations (third tab).

On the first and the third tab, you can also find analysis data in the columns ‘review’ and ‘review note’.

You can also tell that the import contains a structured list. On the first tab, there’s a group of spaces called ‘meeting rooms’, which is listed as a the parent object of all the other meeting rooms on the sheet.

That means you can also import a tree structure when running an import.

How do you set up your import sheet?

Setting up your import file will require you to fill out information on the three main tabs/sheets (objects, properties, and relations). Some of these tabs have columns that are mandatory if you want to import something from that tab.

Determine what you will be importing and which tree or decomposition you will be using as a starting point to run your import from. For building projects, the Spaces & Locations tree is a logical place to start, as it is often the backbone of a project model. for infrastructure projects, it is usually the Systems & Elements tree.

Objects

This is the first tab of your import file. You can use it to add new objects to your project model. See below for an explanation of the different columns on this tab.

Mandatory	Optional	Mandatory	Optional	Optional	Optional	Optional
ObjectType	ObjectID	ObjectName	ParentObjectID	ParentobjectName	Description	Labels
Choose the type the object has to be (e.g. space or location). Click here for a list of possible types. Leaving this field empty will result in a folder in BriefBuilder (except for the spaces & locations tree, as it has no folders).	You can use this column to add a unique identifier. Adding an ID is essential when 2 or more objects have the same name.	The name of the object.	You can use this column alongside the Parentobject column to add a unique identifier OR to refer to a particular existing object (especially if there are multiple objects with the same name).	Use this column if you want to add a tree-structured decomposition to the list of objects you are importing.	Description of the object.	Separate multiple labels by using a comma.

You can import a list of objects in two ways: as a flat list of objects without a tree structure or as a structured decomposition.

Importing a flat list means you are only adding objects to your tree, and you will need to organize them in BriefBuilder by clicking and dragging them around. For this, you will only need to use the ObjectType and ObjectName columns.

Please note that you need to use the object type name as it is in the language of your project model. So, the object ‘meeting room’ would be ‘space’ in an English project model, and ‘ruimte’ in a Dutch project model.

If you want to import a structured list, you will need to use the ParentObject column(s). In database speak, the term ‘parent’ refers to the object that is on top (e.g. the system “power system” is the parent for the element “power socket”). To place objects under the right parent, you have to add the name and/or the ID of the parent object.

Properties

This is the second tab on your import sheet. You can use it to add new properies to your model or to add values to existing standard properties. It is intimately connected with the objects tab, because properties are always added to an object.

Optional*	Mandatory	Mandatory	Optional	Mandatory	Optional
ObjectID	ObjectName	PropertyName	Comparator	Value	Note
To refer to tab ‘Objects’ OR to an existing object in BriefBuilder. *If you choose to use the ObjectIDs in the ‘Objects’ Tab, you will have to use them here as well.	To refer to tab ‘Objects’ OR an existing object in BriefBuilder.	The name of the property.	You can choose between the options: < > = ≤ ≥ ≈	The value of the property.	Explanatory note to describe any specifics for this property.

You will need to make sure that all the properties you add on this tab have a correct reference to the object you want to add them to.

You can also add properties to existing objects which are already present in the model (and which you are not importing right now). If you do this, it is smart to look up the existing object’s ID in BriefBuilder and add that ID to the column ObjectID.

That way, you know for certain that BriefBuilder will match your property with the right object.

This sheet can also be used to import values for standard properties (e.g. usable floor areas for spaces). In that case, you have ensure that the property names in the Excel file match the name of the standard property in the model. Furthermore, you have to ensure that the value fields in your model are empty as the Excel import can only add values, not overwrite them.

Relations

This is the third and final tab on your import sheet. You can use it to add new relations between objects in your project model.

Optional*	Mandatory	Mandatory	Optional*	Mandatory	Optional	Optional
ObjectID1	ObjectName1	ObjectType2	ObjectID2	ObjectName2	Value	Note
To refer to tab ‘Objects’ OR to an existing object in BriefBuilder. *If you choose to use the ObjectIDs in the ‘Objects’ Tab, you will have to use them here as well.	To refer to tab ‘Objects’ OR an existing object in BriefBuilder.	Choose the type the object has to be. Click here for a list of possible types.	Here, you can refer to an object that already exists in BriefBuilder. You can use the existing object’s ID to refer to it directly, or you can choose to leave this column empty and rely on ObjectName2.	Here, you can refer to an object that already exists in BriefBuilder.	The value of the relation (for example, a quantity).	Explanatory note to describe any specifics for this relation.

Commonly, this tab is used in tandem with the objects tab to give the new objects their accompanying relations. In that case, the first two columns for Object 1 will refer back to the new objects on the first tab, and the two columns for Object 2 will refer to existing objects in BriefBuilder.

But you can also use it to add relations to objects that both already exist in your project model. Make sure you look up the existing objects’ IDs to add to the ObjectID columns, and BriefBuilder will automatically find the right ones for your import.

Analysis

Analysis does not have its own tab on the import sheet.

To import analysis data, you will have to add columns yourself. If you want to import analysis properties for objects, add your columns to the first tab; add columns for properties to the second tab, and columns for relations to the third tab.

The header or name of the column you add has to be unique. It cannot be the same as the name of any other column on that tab, and it must be different from any other analysis property columns you add, as well.

You will also need to add your Analysis properties (via Analysis Settings) to your project model before you run your import. Otherwise, BriefBuilder will not be able to match the new columns in your sheet with anything in your model.

Ground rules for imports

It is important to understand the following ground rules when running an import. This will help you avoid errors and create a better understanding of how to clean up or edit your model after you have successfully run an import.

(1) Imports can only add information. Existing information in BriefBuilder cannot be overwritten or edited by use of an import.

This means you can add new objects, properties, and relations. You can also add new properties to existing objects (use an object’s ID for reference). Or you can link existing objects to each other. But you cannot edit, delete or overwrite existing objects, properties or relations.

(2) You can only import object types or properties for one tree at a time. Every import sheet must be created specifically for one particular decomposition in BriefBuilder.

If you want to import data on rooms and their accompanying properties and relations, you will need to run your import from the Spaces & Locations tree. Anything else you still wish to add (e.g. properties for spatial elements) will need to get its own import sheet AND be imported from its own tree or decomposition.

(3) The language used for the object types in your import file must match the language of your project. Otherwise, BriefBuilder will not be able to correctly identify your data. This applies to the object types that you can specify.

If you want to look up the different object types in the language your project is in, simply go to the tree you want to run an import for and click on the plus button. You will get a list of all available object types for that tree.

(4) Property names for a single object must be unique. An object can not have two properties with the same name. If they do, BriefBuilder will consider this a conflict and abort your import.

This applies only to properties. Objects may have the same name, but in that case you will need to add an ObjectID so that software can differentiate between those objects.

(5) Analysis properties must be added to your BriefBuilder model before the import. So, if you have, for example, added an analysis column ‘stakeholder’ to your import file, you first have to create ‘stakeholder’ as analysis property in BriefBuilder. Otherwise, BriefBuilder will not find a match with the data from your sheet and will not import your analysis data.

You can add and edit analysis properties via the Analysis Settings menu. If no input type is given, an import will always default to text. Thus, for some properties, you might want to set this up in detail before running an import (e.g. define picklist options).

(6) Analysis property names must also be unique. Analysis property names must be unique from each other AND they cannot share a name with any of the other headers on your import sheet. If they do, BriefBuilder will consider this a conflict and abort your import.

For example: you cannot have two analysis properties that are both called ‘review’. Also, pay close attention to the other header names on your import sheet. For example, when importing properties, there are two headers for columns labelled as ‘value’ and ‘note’. Do not use these same names for the analysis properties that you wish to add via your import.

(7) Standard properties must be added to your BriefBuilder model before the import. This is similar to importing analysis properties. So, if you want to add “material” as a standard property to all your spatial elements, you should first create a standard property “material” in your model. Click here for learning more about how to create standard properties.

NB If you don’t do this, all those properties will be imported as standard properties. In itself not a problem, but standard properties are easier to manage.

Running an import

Once you have your import sheet all set up, running the import might even be the easiest part of the process — that is, if you do not get any error messages.

TIP: if this is your first time running your import sheet, we recommend you test your import sheet in a sandbox clone of your model before importing it into your live model.

Step-by-step

• Access the project that you wish to run the import in
• Open up the decomposition or tree that matches your import (e.g., Spaces & Locations, Systems & Elements, and so on)
• The import button () can be found in header menu of a tree

• Click on the import button and pick the option ‘Import objects from Excel’
• Upload your import sheet and click on the ‘Import’ button

BriefBuilder will now run your import. If the sheet contains a lot of data, this might take a while. If the pop-up message of running the import disappears, the import was successful. You can instantly see the new objects, properties or relations appear in the tree you have opened up.

If the pop-up disappears and BriefBuilder shows you an error message within the tree instead, the entire import has aborted due to an issue.

Troubleshooting

The error messages that BriefBuilder displays let you know which row on which tab of your import sheet is causing a potential conflict. You will need to open up your import file and check that specific row or cell to examine the problem.

The error message also clarifies what type of issue is causing the import to fail. For example, a lack of unique names (i.e., two properties with the same name), a wrong ID of an object or a type of object that does not exist within your project.

Checking the ground rules might help you further identify the problem. For example, are you importing in the right tree? Does your file’s language and type match that of your project?

Import templates for BriefBuilder

Download an Excel import template for BriefBuilder down below. Be sure to use the language of your project when specifying object types. For example, Danish BriefBuilder does not understand what a “space” is, and English BriefBuilder does not know what a “rum” is. Well, maybe it does, but not that kind of rum 😉

Import templates contain three tabs: one for importing objects, one for importing properties, and one for importing relations between objects. It is ok to leave tabs empty if not relevant for your import.

You will need to add analysis data to any of these three tabs yourself, because those properties are fully customizable and will thus differ per project.

Tips & Tricks

Importing new data: unpivoting Excel tables

Sometimes, you already have data available in Excel that you want to adapt to fit a BriefBuilder import sheet. A lot of data is often structured in the shape of a pivot table, which summarizes data as opposed to BriefBuilder’s ‘flat’ list in the import sheet.

Unpivoting your existing data will make it easier to transform it into an import sheet. This video shows you a simple way of doing so.

Using Excel imports as a mechanism to manage data in your BriefBuilder model

Large project and library models in BriefBuilder often need maintenance. Restructuring hundreds of objects or rehoming dozens of requirements takes a lot of time by hand, and the import function might be a useful trick.

Using imports with existing information should only be considered if (1) the amount of data is large and (2) if there is a lot of variation in where the data needs to end up. Otherwise, cloning or even a simple copy paste action can still be faster.

So, how do you easily extract data from BriefBuilder to use for an import?

You can use the Analysis table to find the information you want to use for an import. Use the filters to narrow the objects, properties or relations down to the ones you need.

In the upper left corner, next to the table’s name, you will find the icon. Click on it, and BriefBuilder will export your selections to Excel.

This will be a great starting point for your import sheet. All you need to do now is restructure the information into three tabs (objects, properties, and relations) and make changes according to the new decomposition you wish to have in your project model.