Module Contents#

class ifcopenshell.api.document.add_reference.Usecase(file, information=None)#

Creates a new reference to a document to assign to products

A document may be associated with physical products, tasks, cost items, and so on. For example, spaces, storeys, and buildings may have a list of associated drawings so you can see which drawings (e.g. plans, sections, details) are documenting that location. Alternatively, equipment may have associated training manuals, operation and maintenance manuals or detailed assembly drawings. Resources may be training certification required, schedules may have gantt charts or bid documents, and so on.

In order to associate a document with an object, a reference to that document needs to be created. It could be a reference to the entire document, or a reference to a particular page or chapter. See ifcopenshell.api.document.assign_document for more information.


information (ifcopenshell.entity_instance.entity_instance) – The IfcDocumentInformation that the reference will be created for


The newly created IfcDocumentReference entity

Return type



document = ifcopenshell.api.run("document.add_information", model)
ifcopenshell.api.run("document.edit_information", model,
    attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
    "Location": "A-GA-6100 - Overall Plan.pdf"})

# In this case, we don't specify any more information, and so the
# reference is for the entire document, as opposed to a single page or
# chapter or section.
reference = ifcopenshell.api.run("document.add_reference", model, information=document)

# Alternatively, we can specify a single section, such as by a
# subheading code.
reference2 = ifcopenshell.api.run("document.add_reference", model, information=document)
ifcopenshell.api.run("document.edit_reference", model,
    reference=reference2, attributes={"Identification": "2.1.15"})