Dangl.Blog();

Accessing AVACloud Directly with User Accounts

Wed, 05 Jul 2023 11:42:51 Z

Disclaimer: This is a cross-post from my professional website. It's a tutorial for a product my company sells.

With AVACloud, you would usually use service based accounts to access the API. However, recently we've had an interesting use case: A client did the integration for AVACloud in an Excel AddIn, and for this, we wanted to go with individual Dangl.Identity user accounts instead of centrally managed OAuth2 clients. Since the default AvaCloudClientFactory from our Dangl.AVACloud package assumes that you're working with clients, you need to add some plumbing code to work with user accounts. It's pretty straightforward, but you need to follow a few steps to achieve it. So, here's how to do it:

We're first creating a class called UserAccountTokenHandler, which implements the ITokenHandler interface. This will try to obtain a Json Web Token (JWT) directly from AVACloud, with provided user credentials. It's used to replace the OpenID Connect based client credentials authentication flow used by default, and allows you to authenticate with AVACloud with a real user context. The implementation is pretty straightforward, getting a token is a single call to the AVACloud API.

We're then adding the TokenAccessChecker class, which just gets a token and checks if the user does have access to perform AVACloud operations. That way, we can show a notification in the UI if AVACloud access is denied, before waiting to see if service calls fail with a 403 - Forbidden status code response.

UserAccountHttpClientAccessor is a small utility class that's just a wrapper around HttpClient. We're using that to be able to provide a typed HttpClient with the HttpClientFactory pattern. We could also use named clients, but I usually prefer to wrap the Http client in a separate class.

Now that everything's set up, we want some more convenience. Working with REST APIs always has some overhead, like managing HttpClient lifecycle and ensuring each request is properly authenticated. Since I'm a big fan of using dependency injection, I usually create factory classes that can be used a singletons throughout the whole app lifecycle, and which do their internal service management. So, in our case, we're just initializing a single instance of AvaCloudUserClientFactory and then rely on it's internal service provider when we want to get a client class.

Finally, here's a test showing you a quick example that gets a token, checks if the user has access and then converts an Excel file using AVACloud:

Happy converting!

What is GAEB?

Mon, 30 Apr 2018 21:12:29 Z

Disclaimer: This is a cross-post from my professional website.

Who is GAEB?

In both the Architecture, Engineering & Construction industry (AEC) as well as in commerce, you hear about the German GAEB. The Joint Committee for Electronics in the Construction Industry (German: Gemeinsamer Ausschuss Elektronik im Bauwesen) is an organization that engages in standardizing and describing electronic methods in the AEC industry and related branches. In effect, GAEB supports the industry in finding and creating vendor independent structures and processes to facilitate the exchange of data between multiple applications.

What is GAEB?

When GAEB is mentioned, more often than not GAEB-DA, Data Exchange (German: Datenaustausch) is meant, a container format. A GAEB file is to a service specification (also known as bill of quantities) what a Microsoft Word file is to a letter - it's the data format to save and exchange information.

Bills of quantities describe services or projects by splitting them up in partial elements, often with a specific structure of the work. For example, this could be the detailed description of the construction of a building, the contract for a five-year facility cleaning service or even just the order of office supplies. All of these examples have in common that a high-level work is split into multiple, small parts, each of which is easy to describe, estimate and calculate. There can also be supplemental information, such as notes, pictures, plans or special requirements be present in the service specification. These projects exist in all sizes. The construction of a duplex garage for a residential building could be described in just a few parts, while the development of a new school could span hundreds and even thousands of single items. Take this very simple example to get a picture of how this could look like:

Example of a service specification.

The GAEB format was designed to meet the needs of modern tendering processes, called AVA in German for Ausschreibung, Vergabe und Abrechnung. It does actually exist since the 80s of the last century, but has been continually improved and adapted and is currently available in its latest version from 2013. There are the legacy GAEB 90 and GAEB 2000 formats, of which the latter is hardly used, as well as the current GAEB XML formats. The adoption is so big, that GAEB is used in virtually all building projects. Most governmental contracts in Germany demand its usage.

This widely supported format empowers all stakeholders in the AEC industry to exchange bills of quantities and related data. Typically at the beginning of a project, the responsible architectural bureau would create a bill of quantities and then distribute it in the GAEB format to interested construction companies that want to bid on the award. After each bidder has created and offer, with the software of his choice, he exports the data again as GAEB and sends it back. Modern tendering and calculation software makes it easy to manage even huge projects in this way.

Especially when combined with BIM, modern GAEB applications allow for great benefits in working efficiently. Interconnecting GAEB data with building models improves a lot of use cases in the AEC industry.

Do you have additional questions regarding the GAEB standard? Don't hesitate to contact me!

Get started with the free GAEB converter right here on this site!

Happy constructing!

Tutorial: Work With GAEB-Converted Excel Files

Tue, 03 May 2016 21:28:48 Z

This tutorial shows you how to work with Excel files created from the GAEB converter. I’m using the sample projects that you can download here as GAEB 90, GAEB 2000 or GAEB XML.

Structure of the File

The Excel file does have three worksheets in it with which you can calculate prices for a project or extract data from GAEB files.

There’s actually another, hidden worksheet in the file that’s used to save project related data. Please don’t change any values in that, otherwise it can’t be converted back to GAEB

The Overview Worksheet

The Overview Worksheet contains the core of the service specification. It’s got a list of all the elements in the file (along their properties such as price, quantity and descriptions), has sums for all groups and calculates the total price. You can use the buttons on the left to collapse or expand groups to adjust your view of the project.

The Project Information Worksheet

The Project Information Worksheet contains basically two types of information:

Price components, e.g. the names of the price components used in a project like “Material”, “Gear” or “Labour”
Contact information about the buyer and the bidder in the project

The Calculation Worksheet

The Calculation Sheet is used to calculate prices. You can also write your prices directly into the overview, but here you’ve got a chance for a bit more structure.

Working with the File

Adding Information about Yourself

When you work with GAEB, it’s often required that you input your contact details into the GAEB file itself. This is to make it easy for architects and building owners to read your data and compare your offer to your competitors. To do that, simple enter your data in the section for Bidder in the Project Information Worksheet.

Here's an example input:

Which would look like this in a GAEB file:

<CTR>
  <Address>
    <Name1>Georg Dangl</Name1>
    <Name2>c / o Construction Co.</Name2>
    <Street>Fakestr. 124</Street>
    <PCode>12346</PCode>
    <City>Munich</City>
    <Country>Germany</Country>
    <Contact>Georg Dangl</Contact>
    <Phone>+49 (160) 121212456</Phone>
    <Email>blog@dan.gl</Email>
  </Address>
</CTR>

Calculating Prices

You have two options to calculate and input your prices in the file:

Use the Calculation Worksheet where you can do a structured and precise calculation
Input the resulting unit price directly into the Overview Worksheet

Here, I’ll show you how to do a detailed calculation:

The following happens in this clip:

Position 01.01.001 is getting a calculation entry for “Transport of Material” with a value of 500.- on the price component “Material”.
The same Position needs another price component, so I just select the appropriate position reference in Column A and enter another calculation part.
After switching back to the Project Overview, we see that the unit price for position 01.01.001 was updated to 900.- € and so was its parent group and the total price.

Tip: Since this is Excel, you are free to use formulas instead of fixed values when you’re calculating prices.

Setting Tax Rates

For a complete offer, you often have to include the tax rates suitable for the project. The above picture shows you (marked yellow) where to enter the overall tax rate. Additionally, you can set custom tax rates for specific items (marked green).

In Germany, Water used on a construction site usually has a reduced tax rate of 7%

Supplying Quantities where Demanded

Sometimes, it’s up to the bidder to offer a quantity for a position. This may be used when the size of a necessary excavation depends on the machines that are used, but it nevertheless forces the bidder to supply the data when submitting an offer. Quantities that are required to be entered are marked with a comment, indicated by a small red triangle in the corner in the Overview Worksheets quantity column (E). You just have to enter the value in the Overview Worksheet and then you’re good to go.

Offering Deductions

If you’re feeling generous, you can enter percentages of deductions in column I for positions, groups as well as the whole service specification. The total price will then be the deducted price.

Converting the File Back to GAEB

When you've entered all your data and the project is ready, you can convert the file back again to a GAEB project. To do that, use the GAEB converter again, upload your Excel file and select one of the GAEB formats as output target. Additionally, you should chose to transform to exchange phase 84 (offer), so the file can easily be read by whomever you're sending it to. You can read the documentation for the GAEB converter here.

Tutorial: How to Use the GAEB Converter

Tue, 03 May 2016 20:35:56 Z

In the german building industry, the GAEB data format is often used to exchange descriptions of services in the process of tendering, i.e. to describe the works expected to be performed within a project and to collect bids based on these descriptions. For that, the GAEB format is understood by most calculation and tendering applications and the format is required in virtually any projects above a certain size, especially for government contracts.

The online GAEB converter here is a free tool that can be used to convert between the different GAEB formats and Microsoft Excel. Additionally, the converter does allow to enter calculation data such as prices and quantities in the Excel file and then convert it back to GAEB for submission. It’s also possible to just extract certain data from a GAEB project, such as when you want to pass on a subsection of the complete description to another party.

This tutorial will give you an overview of the GAEB converters functionality.

Converting from a GAEB or Excel File

Probably the most common use case of the converter is to create an Excel file, calculate the prices and then convert it back to GAEB for submission to the owner.

I’ll show you the process with a very small example project that you can download either as GAEB 90, GAEB 2000 or GAEB XML to try it for yourself.

At first, you have to upload a GAEB file. See the following clip for how this works.

When the upload is finished, the file has been analyzed and you can select the options for the conversion.

Tip: If you’re uploading an Excel file, please keep in mind that only files generated by the GAEB converter can be converted.

Then you specify the output format, which can be either Excel or any of the GAEB file formats. If you chose a GAEB format, you can optionally select to transform the output to a phase. If you chose “None” (the default), all the information in the file will be kept. For example, when you want to submit an offer, chose phase 84 (Offer) and the GAEB file will be transformed so that only the information relevant for offering will be kept.

Tip: You can use the converter to transform between different GAEB file formats, such as transform a GAEB XML file to GAEB 2000 if you can’t open it. It’s also good to repair damaged GAEB files, since there are some programs that are quite picky when it comes to reading GAEB files.

On the left side, you can select three more options:

Include Longtext
Some elements, such as positions, may have quite a long text description and it’s not always necessary for your use case. If all you want is a neat Excel list of your positions without cluttering texts, deactivate it
Include Prices
If disabled, all prices will be stripped from the result. Use this if you want to forward parts of the service specification to a sub contractor
Select Elements
If you activate this check box, the structure of the service specification is displayed on the right and you can select and deselect elements to change the output. This is useful if you want to extract only certain elements from the whole document

Tip: The GAEB converter detects your browsers language. If it sees German, the Excel files content will be in German, otherwise it will be in English.

Finally, when you’ve chosen what you want, just click on the blue “Start Conversion” button and the file is being converted and prepared for download. When the download is ready, just click on the blue download button and you’ll get your file.

Please note that you can download a converted file only once. If you don’t download a file, it is deleted after 15 minutes for security reasons.

If you want to know how to work with the Excel files, read this tutorial to learn it.