ifcopenshell.api.owner

An element may have an owner, indicating who is responsible, liable, or contactable regarding that element

Note that in IFC2X3, element ownership is mandatory and must be addressed prior to the creation of any element at all. See create_owner_history() for examples.

Submodules

Package Contents

ifcopenshell.api.owner.add_actor(file: ifcopenshell.file, actor: ifcopenshell.entity_instance, ifc_class: ACTOR_TYPE = 'IfcActor') → ifcopenshell.entity_instance

Adds a new actor

An actor is a person or an organisation who has a responsibility or role to play in a project. Actor roles include design consultants, architects, engineers, cost planners, suppliers, manufacturers, warrantors, owners, subcontractors, etc.

Actors may either be project actors, who are responsible for the delivery of the project, or occupants, who are responsible for the consumption of the project.

Identifying and managing actors is critical for asset management, and identifying liability for legal submissions.

Parameters:

  • actor (ifcopenshell.entity_instance) – Most commonly, an IfcOrganization (in compliance with GDPR requirements for non personally identifiable information), or an IfcPerson if it is a sole individual, or an IfcPersonAndOrganization if a specific person is liable within an organisation and must be legally nominated.

  • ifc_class (str, optional) – Either “IfcActor” or “IfcOccupant”.

Returns:

The newly created IfcActor or IfcOccupant

Return type:

ifcopenshell.entity_instance

Example:

# Setup an organisation with a single role
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
role = ifcopenshell.api.owner.add_role(model, assigned_object=organisation, role="ARCHITECT")

# Assign that organisation to a newly created actor
actor = ifcopenshell.api.owner.add_actor(model, actor=organisation)
ifcopenshell.api.owner.add_address(file: ifcopenshell.file, assigned_object: ifcopenshell.entity_instance, ifc_class: ADDRESS_TYPE = 'IfcPostalAddress') → ifcopenshell.entity_instance

Add a new telecom or postal address to an organisation or person

A person or organisation may have associated contact details such as phone numbers, mailing addresses, websites, email addresses, and instant messaging handles. This information is critical in recording the contact information of manufacturers and suppliers for facility management, or liable actors.

There are two types of addresses, postal addresses for physical snail mail, and telecom addresses for telephone or internet contact numbers and addresses.

Parameters:

  • assigned_object (ifcopenshell.entity_instance) – The IfcOrganization or IfcPerson the contact address belongs to.

  • ifc_class (str, optional) – Either IfcPostalAddress or IfcTelecomAddress. Defaults to IfcPostalAddress.

Returns:

The new IfcPostalAddress or IfcTelecomAddress

Return type:

ifcopenshell.entity_instance

Example:

organisation = ifcopenshell.api.owner.add_organisation(model)

# A snail mail address
postal = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcPostalAddress")
ifcopenshell.api.owner.edit_address(model, address=postal,
    attributes={"Purpose": "OFFICE", "AddressLines": ["42 Wallaby Way"],
    "Town": "Sydney", "Region": "NSW", "PostalCode": "2000"})

# A phone or internet address
telecom = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcTelecomAddress")
ifcopenshell.api.owner.edit_address(model, address=telecom,
    attributes={"Purpose": "OFFICE", "TelephoneNumbers": ["+61432466949"],
    "ElectronicMailAddresses": ["bobthebuilder@example.com"],
    "WWWHomePageURL": "https://thinkmoult.com"})
ifcopenshell.api.owner.add_application(file: ifcopenshell.file, application_developer: ifcopenshell.entity_instance | None = None, version: str | None = None, application_full_name: str = 'IfcOpenShell', application_identifier: str = 'IfcOpenShell') → ifcopenshell.entity_instance

Adds a new application

IFC data may be associated with an authoring application to identify which application was responsible for editing or authoring the data. An application is defined by the developing organisation, as well as a full name and identifier. This is akin to how web browsers have an identification string.

Parameters:

  • application_developer (ifcopenshell.entity_instance, optional) – The IfcOrganization responsible for creating the application. Defaults to generating an IfcOpenShell organisation if none is provided.

  • version (str, optional) – The version of the application. Defaults to the ifcopenshell.version data if not specified.

  • application_full_name (str, optional) – The name of the application

  • application_identifier (str, optional) – An identification string for the application intended for computers to read.

Returns:

The newly created IfcApplication

Return type:

ifcopenshell.entity_instance

Example:

application = ifcopenshell.api.owner.add_application(model)
ifcopenshell.api.owner.add_organisation(file: ifcopenshell.file, identification: str = 'APTR', name: str = 'Aperture Science') → ifcopenshell.entity_instance

Adds a new organisation

Organisations are the main way to identify manufacturers, suppliers, and other actors who do not have a single representative or must not have any personally identifiable information.

Parameters:

  • identification (str, optional) – The short code identifying the organisation. Sometimes used in drawing naming schemes. Otherise used as a canonicalised way of computers to identify the organisation. Like their stock name.

  • name (str, optional) – The legal name of the organisation

Returns:

The newly created IfcOrganization

Return type:

ifcopenshell.entity_instance

Example:

organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
ifcopenshell.api.owner.add_person(file: ifcopenshell.file, identification: str = 'HSeldon', family_name: str = 'Seldon', given_name: str = 'Hari') → ifcopenshell.entity_instance

Adds a new person

Persons are used to identify a legal or liable representative of an organisation or point of contact.

Parameters:

  • identification (str, optional) – The computer readable unique identification of the person. For example, their username in a CDE or alias.

  • family_name (str, optional) – The family name

  • given_name (str, optional) – The given name

Returns:

The newly created IfcPerson

Return type:

ifcopenshell.entity_instance

Example:

ifcopenshell.api.owner.add_person(model,
    identification="bobthebuilder", family_name="Thebuilder", given_name="Bob")
ifcopenshell.api.owner.add_person_and_organisation(file: ifcopenshell.file, person: ifcopenshell.entity_instance, organisation: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Adds a paired person and organisation

A person and an organisation may be paired to create a representative belonging to a company.

Parameters:

  • person (ifcopenshell.entity_instance) – The IfcPerson being the representative of the organisation.

  • organisation (ifcopenshell.entity_instance) – The IfcOrganization it

Returns:

The newly created IfcPersonAndOrganization

Return type:

ifcopenshell.entity_instance

Example:

person = ifcopenshell.api.owner.add_person(model,
    identification="lecorbycorbycorb", family_name="Curbosiar", given_name="Le")
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")

ifcopenshell.api.owner.add_person_and_organisation(model,
    person=person, organisation=organisation)
ifcopenshell.api.owner.add_role(file: ifcopenshell.file, assigned_object: ifcopenshell.entity_instance, role: str = 'ARCHITECT') → ifcopenshell.entity_instance

Adds and assigns a new role

People and organisations must play one or more roles on a project. Roles include architects, engineers, subcontractors, clients, manufacturers, etc. Typically these roles and their corresponding responsibilities will be outlined in contractual documents.

This function will both add and assign the role to the person or organisation.

Parameters:

  • assigned_object (ifcopenshell.entity_instance) – The IfcPerson or IfcOrganization the role should be assigned to.

  • role (str, optional) – The type of role, taken from the IFC documentation for IfcActorRole, or a custom name. Defaults to “ARCHITECT”.

Returns:

The newly created IfcActorRole

Return type:

ifcopenshell.entity_instance

Example:

organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
ifcopenshell.api.owner.add_role(model, assigned_object=organisation, role="ARCHITECT")
ifcopenshell.api.owner.assign_actor(file: ifcopenshell.file, relating_actor: ifcopenshell.entity_instance, related_object: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Assigns an actor to an object

An actor may be assigned to objects which implies that the actor is responsible for. This is most commonly used in facility management for indicating the manufacturers, suppliers, and warrantors for product types.

Here are a list of objects you may assign an actor to:

  • IfcControl: Indicates project directives issued by the actor.

  • IfcGroup: Indicates groups for which the actor is responsible.

  • IfcProduct: Indicates products for which the actor is responsible.

  • IfcProcess: Indicates processes for which the actor is responsible.

  • IfcResource: Indicates resources for which the actor is responsible to

    allocate, manage, or delegate. This is not the actor actually using the resource or performing the work. For that type of actor, see ifcopenshell.api.resource.assign_resource.

Parameters:

  • relating_actor (ifcopenshell.entity_instance) – The IfcActor who is responsible for the object.

  • related_object (ifcopenshell.entity_instance) – The object the actor is responsible for.

Returns:

The newly created IfcRelAssignsToActor relationship.

Return type:

ifcopenshell.entity_instance

Example:

# We need to procure and install 2 of this particular pump type in our facility.
pump_type = ifcopenshell.api.root.create_entity(model, ifc_class="IfcPumpType")

# Define who the manufacturer is
manufacturer = ifcopenshell.api.owner.add_organisation(model,
    identification="PWP", name="Pumps With Power")
ifcopenshell.api.owner.add_role(model, assigned_object=manufacturer, role="MANUFACTURER")

# To help our facility manager, it's nice to provide contact details
# of the manufacturer so they know how to call when the pump breaks.
telecom = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcTelecomAddress")
ifcopenshell.api.owner.edit_address(model, address=telecom,
    attributes={"Purpose": "OFFICE", "TelephoneNumbers": ["+61432466949"],
    "ElectronicMailAddresses": ["contact@example.com"],
    "WWWHomePageURL": "https://example.com"})

# Make the manufacturer responsible for that pump type.
ifcopenshell.api.owner.assign_actor(model,
    relating_actor=manufacturer, related_object=pump_type)
ifcopenshell.api.owner.create_owner_history(file: ifcopenshell.file) → 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.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.owner.add_person(model,
    identification="LPARTEE", family_name="Partee", given_name="Leeable")
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
user = ifcopenshell.api.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.owner.create_owner_history(model)
space = ifcopenshell.api.root.create_entity(model, ifc_class="IfcSpace")
ifcopenshell.api.owner.edit_actor(file: ifcopenshell.file, actor: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcActor

For more information about the attributes and data types of an IfcActor, consult the IFC documentation.

Parameters:

  • actor (ifcopenshell.entity_instance) – The IfcActor entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

# Setup an organisation with a single role
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
role = ifcopenshell.api.owner.add_role(model, assigned_object=organisation)
ifcopenshell.api.owner.edit_role(model, role=role, attributes={"Role": "ARCHITECT"})

# Assign that organisation to a newly created actor
actor = ifcopenshell.api.owner.add_actor(model, actor=organisation)

# Edit the description of the attribute.
ifcopenshell.api.actor.edit_actor(model,
    actor=actor, attributes={"Description": "Responsible for buildings A, B, and C."})
ifcopenshell.api.owner.edit_address(file: ifcopenshell.file, address: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcAddress

For more information about the attributes and data types of an IfcAddress, consult the IFC documentation.

Parameters:

  • address (ifcopenshell.entity_instance) – The IfcAddress entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

# A snail mail address
postal = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcPostalAddress")
ifcopenshell.api.owner.edit_address(model, address=postal,
    attributes={"Purpose": "OFFICE", "AddressLines": ["42 Wallaby Way"],
    "Town": "Sydney", "Region": "NSW", "PostalCode": "2000"})

# A phone or internet address
telecom = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcTelecomAddress")
ifcopenshell.api.owner.edit_address(model, address=telecom,
    attributes={"Purpose": "OFFICE", "TelephoneNumbers": ["+61432466949"],
    "ElectronicMailAddresses": ["bobthebuilder@example.com"],
    "WWWHomePageURL": "https://thinkmoult.com"})
ifcopenshell.api.owner.edit_organisation(file: ifcopenshell.file, organisation: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcOrganization

For more information about the attributes and data types of an IfcOrganization, consult the IFC documentation.

Parameters:

  • organisation (ifcopenshell.entity_instance) – The IfcOrganization entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects With Ballpens")
ifcopenshell.api.owner.edit_organisation(model, organisation=organisation,
    attributes={"name": "Architects Without Ballpens"})
ifcopenshell.api.owner.edit_person(file: ifcopenshell.file, person: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcPerson

For more information about the attributes and data types of an IfcPerson, consult the IFC documentation.

Parameters:

  • person (ifcopenshell.entity_instance) – The IfcPerson entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

person = ifcopenshell.api.owner.add_person(model,
    identification="bobthebuilder", family_name="Thebuilder", given_name="Bob")
ifcopenshell.api.owner.edit_person(model, person=person,
    attributes={"MiddleNames": ["The"], "FamilyName": "Builder"})
ifcopenshell.api.owner.edit_role(file: ifcopenshell.file, role: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edits the attributes of an IfcActorRole

For more information about the attributes and data types of an IfcActorRole, consult the IFC documentation.

Parameters:

  • role (ifcopenshell.entity_instance) – The IfcActorRole entity you want to edit

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

person = ifcopenshell.api.owner.add_person(model,
    identification="bobthebuilder", family_name="Thebuilder", given_name="Bob")

# By default, the role is an architect
role = ifcopenshell.api.owner.add_role(model, assigned_object=person)

# But Bob is not an architect
ifcopenshell.api.owner.edit_role(model, role=role, attributes={"Role": "CONSTRUCTIONMANAGER"})
ifcopenshell.api.owner.remove_actor(file: ifcopenshell.file, actor: ifcopenshell.entity_instance) → None

Removes an actor

Parameters:

actor (ifcopenshell.entity_instance) – The IfcActor to remove.

Returns:

None

Return type:

None

Example:

# Setup an organisation with a single role
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
role = ifcopenshell.api.owner.add_role(model, assigned_object=organisation)
ifcopenshell.api.owner.edit_role(model, role=role, attributes={"Role": "ARCHITECT"})

# Assign that organisation to a newly created actor
actor = ifcopenshell.api.owner.add_actor(model, actor=organisation)

# Actually we need ballpens on this project
ifcopenshell.api.owner.remove_actor(model, actor=actor)
ifcopenshell.api.owner.remove_address(file: ifcopenshell.file, address: ifcopenshell.entity_instance) → None

Removes an address

Naturally, any organisations or people using that address will have the relationship removed.

Parameters:

address (ifcopenshell.entity_instance) – The IfcAddress to remove.

Returns:

None

Return type:

None

Example:

organisation = ifcopenshell.api.owner.add_organisation(model)
address = ifcopenshell.api.owner.add_address(model,
    assigned_object=organisation, ifc_class="IfcPostalAddress")

# Change our mind and delete it
ifcopenshell.api.owner.remove_address(model, address=address)
ifcopenshell.api.owner.remove_application(file: ifcopenshell.file, application: ifcopenshell.entity_instance) → None

Removes an application

Warning: removing an application may invalidate ownership histories. Check whether or not the application is used anywhere prior to removal.

Parameters:

address (ifcopenshell.entity_instance) – The IfcApplication to remove.

Returns:

None

Return type:

None

Example:

application = ifcopenshell.api.owner.add_application(model)
ifcopenshell.api.owner.remove_address(model, application=application)
ifcopenshell.api.owner.remove_organisation(file: ifcopenshell.file, organisation: ifcopenshell.entity_instance) → None

Remove an organisation

All roles and addresses assigned to the organisation will also be removed.

Parameters:

organisation (ifcopenshell.entity_instance) – The IfcOrganization to remove

Returns:

None

Return type:

None

Example:

organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
ifcopenshell.api.owner.remove_organisation(model, organisation=organisation)
ifcopenshell.api.owner.remove_person(file: ifcopenshell.file, person: ifcopenshell.entity_instance) → None

Remove an person

All roles and addresses assigned to the person will also be removed. In IFC2X3 will also remove related inventories if person was the only responsile person for them.

Parameters:

person (ifcopenshell.entity_instance) – The IfcPerson to remove

Returns:

None

Return type:

None

Example:

ifcopenshell.api.owner.add_person(model,
    identification="bobthebuilder", family_name="Thebuilder", given_name="Bob")
ifcopenshell.api.owner.remove_person(model, person=person)
ifcopenshell.api.owner.remove_person_and_organisation(file: ifcopenshell.file, person_and_organisation: ifcopenshell.entity_instance) → None

Removes a person and organisation

Note that the underlying person and organisation is not removed, only the “person and organisation” group.

Parameters:

person_and_organisation (ifcopenshell.entity_instance) – The IfcPersonAndOrganization to remove.

Returns:

None

Return type:

None

Example:

person = ifcopenshell.api.owner.add_person(model,
    identification="lecorbycorbycorb", family_name="Curbosiar", given_name="Le")
organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")

user = ifcopenshell.api.owner.add_person_and_organisation(model,
    person=person, organisation=organisation)

ifcopenshell.api.owner.remove_person_and_organisation(model, person_and_organisation=user)
ifcopenshell.api.owner.remove_role(file: ifcopenshell.file, role: ifcopenshell.entity_instance) → None

Removes a role

People and organisations using the role will be untouched. This may leave some of them without roles.

Parameters:

role (ifcopenshell.entity_instance) – The IfcActorRole to remove.

Returns:

None

Return type:

None

Example:

organisation = ifcopenshell.api.owner.add_organisation(model,
    identification="AWB", name="Architects Without Ballpens")
role = ifcopenshell.api.owner.add_role(model, assigned_object=organisation, role="ARCHITECT")

# After running this, the organisation will have no role again
ifcopenshell.api.owner.remove_role(model, role=role)
ifcopenshell.api.owner.unassign_actor(file: ifcopenshell.file, relating_actor: ifcopenshell.entity_instance, related_object: ifcopenshell.entity_instance) → None

Unassigns an actor to an object

This means that the actor is no longer responsible for the object.

Parameters:

  • relating_actor (ifcopenshell.entity_instance) – The IfcActor who is responsible for the object.

  • related_object (ifcopenshell.entity_instance) – The object the actor is responsible for.

Returns:

None

Return type:

None

Example:

# We need to procure and install 2 of this particular pump type in our facility.
pump_type = ifcopenshell.api.root.create_entity(model, ifc_class="IfcPumpType")

# Define who the manufacturer is
manufacturer = ifcopenshell.api.owner.add_organisation(model,
    identification="PWP", name="Pumps With Power")
ifcopenshell.api.owner.add_role(model, assigned_object=manufacturer, role="MANUFACTURER")

# Make the manufacturer responsible for that pump type.
ifcopenshell.api.owner.assign_actor(model,
    relating_actor=manufacturer, related_object=pump_type)

# Undo the assignment
ifcopenshell.api.owner.unassign_actor(model,
    relating_actor=manufacturer, related_object=pump_type)
ifcopenshell.api.owner.update_owner_history(file: ifcopenshell.file, element: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Updates the owner that is assigned to an object

This ensures that the owner is tracked to have modified the object last, including the time when the change occured. See ifcopenshell.api.owner.create_owner_history for details.

Parameters:

element (ifcopenshell.entity_instance) – The IfcRoot element to update the ownership details on when a change is made.

Returns:

The updated IfcOwnerHistory element.

Return type:

ifcopenshell.entity_instance

Example:

# See ifcopenshell.api.owner.create_owner_history for setup
# [ ... example setup code ... ]

# 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.owner.create_owner_history(model)
space = ifcopenshell.api.root.create_entity(model, ifc_class="IfcSpace")

# Any edits we make will have ownership tracking automatically
# applied. There is no need to run any owner.update_owner_history
# API calls either.
ifcopenshell.api.attribute.edit_attributes(model, product=space, attributes={"Name": "Lobby"})