ifcopenshell.api.owner.create_owner_history

Module Contents

ifcopenshell.api.owner.create_owner_history.create_owner_history(file: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Creates a new owner history indicating an element was added

Any object in IFC with a unique ID and name (such as physical products, tasks, calendars, etc) may have an owner associated with it. An owner is a liable person and/or organisation which a bit of metadata indicating whether they have created the object, edited the object, when the change was made, and which application they used.

IFC does not offer a comprehensive specification for version control and change tracking, as this is completely out of scope. However this similar ability allows IFC to satisfy legal requirements where object ownership, responsibilities, and permissions must be specified. Recording the owner is mandatory in IFC2X3 but optional in IFC4. It is not recommended to store this ownership data in IFC4 unless a legal requirement is in place.

Because owner tracking is mandatory in IFC2X3, be aware that some configuration may be required to work correctly. Read on.

To track the owner, at a minimum we have to know the application that the element was authored from, as well as the user (person and organisation) that made the change. The IfcOpenShell API is a low level software library and will not know what application the API is being called from, and nor does it have the responsibility to manage the “active user” making edits, which may be as simple as hardcoding it to “Bob” or even be as complex as integration with a CDE’s authentication system. As a result, the developer responsible to integrate with IfcOpenShell is expected to overload the ifcopenshell.api.owner.settings.get_user and ifcopenshell.api.owner.settings.get_application functions.

It is not necessary to call this function directly if you are already using other API calls. It is a low level function only available if you are writing your own advanced scripts and want to take advantage of the easier ownership tracking.

Returns:

The newly created IfcOwnerHistory element or None if it’s not IFC2X3 and user or application is not found in the current project.

Return type:

Union[ifcopenshell.entity_instance, None]

Example:

# Let's imagine we're writing a small script, not large enough to be
# its own fully branded application. In this case, let's use the
# default application which is prepopulated with "IfcOpenShell" as
# the name and version.
application = ifcopenshell.api.run("owner.add_application", model)

# Let's imagine we run this as an automated QA process in an
# architectural firm. However, the results must be signed off by the
# registered architect who is liable for the project.
person = ifcopenshell.api.run("owner.add_person", model,
    identification="LPARTEE", family_name="Partee", given_name="Leeable")
organisation = ifcopenshell.api.run("owner.add_organisation", model,
    identification="AWB", name="Architects Without Ballpens")
user = ifcopenshell.api.run("owner.add_person_and_organisation", model,
    person=person, organisation=organisation)

# Let's configure our owner settings to hardcode always returning
# the application and user. In theory, you could build complex user
# access control lookup functions here, but this is simple enough.
ifcopenshell.api.owner.settings.get_user = lambda x: user
ifcopenshell.api.owner.settings.get_application = lambda x: application

# We've finished our ownership setup. Now let's start our script and
# create a space. Notice we don't actually call
# create_owner_history at all. This is already automatically handled
# by the API when necessary. Under the hood, the API is actually
# running this code on the IfcSpace element:
# element.OwnerHistory = ifcopenshell.api.run("owner.create_owner_history", model)
space = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSpace")