Library part format

File extension

Most GDL Library Objects are saved with the *.gsm extension and they are distinguished by their subtype in Archicad. There is a special extension, *.gdl (GDL Script Files) for the MASTER_GDL/MASTEREND_GDL files. Archicad handles any GDL Script File starting with the string “MASTER_GDL…” or “MASTEREND_GDL…” in their file name in a special way. These files can be used to load attribute definitions, define line types, materials, etc. (more information in The GDL Script Analysis).

Identification

The identifier

The ID consists of two parts, each 36 characters long. The first 36 characters represent the Main ID and the last 36 characters represent the Revision ID.

  • The Main ID is created when the library part is saved for the first time. It is also modified if the library part is resaved using the “Save as” command.
  • The Revision ID is also created when the library part is saved for the first time but it is modified if the library part is resaved using the “Save” command. Using the LP_XMLConverter tool a compilation will change the Revision ID and leave the Main ID untouched, of course.

This means that Main ID identifies a library part in its function and the Revision ID helps in distinguishing the revisions of the object. Let’s see this in practice.

Library Part Identification

When placing an object in Archicad, the program stores the reference by the ID and considers the name only for objects without an ID (library parts saved before Archicad 8 and .gdl files). In the case of Library Parts coming from versions earlier than Archicad 8, there was no such thing as a GUID. So when such a Library Part is encountered in the file, will fill out its ID with zeros.

When loading a library, uses the following hierarchical criteria for matching loaded library parts to objects already placed in the project:

  • In case the stored ID is valid:
    1. Archicad tries to get an exact match of both parts of the ID
    2. Failing that, Archicad tries to match the first part of the ID, which is the Main ID.
    3. In case it doesn’t find one matching, it starts to check other elements’ Migration Table values to find a substitute.
    4. Finally, when loading files saved before Archicad 12, Archicad tries to match by library part name.
  • In case the stored ID is zero, the identification procedure tries to match by name only.

The same process is executed when looking for macros in a placed element as every library part contains a lookup table for its called macros’ GUIDs. Naturally, when saving an object containing macro calls, this table is collected using a name-based search in the currently loaded library.

How to know what the exact GUID of a Library Object is

You can use Insert own GUID in the Edit menu when the Library Part Editor window is active. Alternatively, you can check the Subtype Hierarchy dialog window. In this dialog, you can see the subtype hierarchy of the currently loaded library in a tree view. The main attributes – name, version, ID, file location, flags indicating if the object is template or placeable – of the selected library part are displayed at the bottom of the window.

This dialog appears in 2 contexts:

  • Open Object by Subtype… (on Edit GDL Library Parts toolbar)
  • Place All Objects (in the Library Developer menu)

Naturally, you can read the ID in the HSF or XML format of the library part. To get these, use the LP_XMLConverter tool.

Compatibility issues

The most important principle is that the Main ID represents a constant functionality to the users of the library. This means that if you publish a new library part using a Main ID that is already in use by an old library part when loading an old project with the new library, the old placed elements will be replaced by the new object. This contradicts the users’ expectations, such as there will be no change in the object’s parameters and functions. If you want to change the name or the function of old parameters, generate a new Main ID and use migration scripts to avoid ambiguity and unexpected data loss. Make sure that this new Main ID is unique – not identical to any other ID in the library.

Note, that renaming an object won’t make it incompatible with its past self for Archicad as long as their MainIDs remain identical. Similarly, giving the name of an existing library part to a new one (with a new ID) will not make them compatible.

Migrating Elements

It is possible to maintain a link between the old and the new, updated version (with a new Main ID) of a library part by using migration scripts (forward migration script, backward migration script) and a migration table.

In these scripts, you can define which library part substitutes which (by connecting the old and new Main ID-s), and how to update the new object’s parameter values based on the old one (or vice versa). You can set rules for the migration to happen only under certain parametric conditions. If the subject of the migration meets these, the upgrade or downgrade is possible, otherwise it will not be an option.

Migrating Zones

Generally, it is possible for the subject of the migration to have one or more successors (or ancestors in backward migration) depending on parameter settings. The case is a little different when migrating Zone Stamps, though. One type of Zone Stamp can be linked to many Zone Categories. But each category can use only one kind of Zone Stamp. When migrating a Zone Stamp, the Category stays the same. If the route of migration diverges (“Zone Old” is upgraded to “Zone New 1”, or to “Zone New 2”, depending on different parameter settings), it is possible to get a Category with two different Stamps linked. While this is a valid result regarding the migration process, it is an inconsistent situation for Archicad. Make sure you only migrate Zone Stamps in a direct way, to avoid this.