Documents

Structured, permissioned file metadata linked to entities of the master data, and how documents are shared with the parties that may read them.

📘

Purpose

Documents in facilioo go beyond simple file uploads — they are permissioned entities embedded into the legal and physical context of your portfolio.

In facilioo, documents represent a structured metadata layer around uploaded or imported files.
They provide context, access control and delivery to the right people.

A document is built from three parts:

PartEntityAnswers the question
ContentFileWhat is stored?
AssignmentpropertyId, unitId, contractId, partyId on the DocumentWhere is it filed, and whom is it about?
AccessDocument ShareWho may read it?

The key idea: an assignment does not grant access by itself, only a document share does.
facilioo can create these shares for you automatically from the assignment (Automatic sharing), or you create them yourself (Manual sharing).

Creating party and document groups

Every document belongs to the party that created it (the creating party), usually the property management company.
The creating party always sees all of its documents, whatever their shares are.

Documents are organized into document groups.
A group works like a folder: groups can be nested, and every group, subgroup and document in a tree belongs to the same creating party.
A document is filed in a group of its creating party (groupId), or at root level when groupId is empty.

A group can be hidden (isHidden).
A hidden group hides everything below it from the parties the documents are shared with.
The documents stay shared, but they become visible again only once the group is visible.
The creating party still sees hidden groups.

Each document group can also be configured for one or more contract types, such as tenants, owners or advisory board members.
This configuration decides whether facilioo shares the group's documents automatically and with whom.
You set it in the facilioo web application; it is not yet available through the API.

⚠️

Legacy flags

isSharedWithTenants, isSharedWithOwners and isSharedWithBoard on the document group are legacy.
They have no effect on who can access a document.
Automatic sharing only uses the contract type configuration described above.

Assignment

A document can be assigned to four places in the master data.
At least one of them has to be set:

FieldAssigned toTypical example
propertyIda Property or one of its entrancesHouse rules, insurance policy, annual statement of the property
unitIda UnitFloor plan or energy certificate of an apartment
contractIda Unit Contract (e.g. one tenancy or ownership)Rental agreement, individual service charge statement
partyIda Party (person or company)A letter to one specific person, independent of a unit

Where a document is listed

facilioo lists a document exactly at the places it is assigned to.
Nothing is inherited in either direction: a document assigned to a property is not listed at the property's entrances or units, and a document assigned to a unit is not listed at its property.
A property and each of its entrances have separate lists.

The list of a party is the exception.
Besides the documents assigned to the party, it also contains every document shared with the party.
Of these, a document that is also assigned to a property, entrance or unit is shown there as a reference to that place and is managed there.

Apart from the party's list, shares and the document group's configuration don't change where a document is listed.
The API filters behave the same way: propertyId, entranceId, unitId, contractId and partyId each only match documents with exactly this assignment.

Which fields to set

Set the field of the place the document is about, the most specific one.
For example, set only unitId for the floor plan of an apartment.
This is also what the facilioo web application does when you upload a document.

You may set several of them at once, for example propertyId and unitId.
The document is then listed at each of these places.
The values must fit together: the unit must belong to the property or entrance, and the contract to the unit.
When you set propertyId and contractId, unitId is required too.

CombinationEffect
unitIdListed at the unit.
propertyId + unitIdAlso listed at the property or entrance. Doesn't change who it is shared with.
unitId or propertyId + partyIdManaged at the unit or property, and shown as a reference in the party's list.
contractId + partyIdListed and managed at both the contract and the party.
⚠️

Reading combined assignments

The assignment is only validated when a document is created or updated.
When a unit is moved to another property later, the propertyId of its documents is not updated.
Take the current property of a unit from the unit, not from the document.

Party assignment

partyId files the document for one specific party.
The document is meant for this party and usually also about it.
This party is not the creating party of the document.
In a group with automatic sharing, the document is shared with exactly this party (see Automatic sharing).
Otherwise the party only gets access through a document share you create (see Manual sharing).

📘

Filing for a party in the facilioo web application

When a document is uploaded at a party or an email is filed at a party in the facilioo web application, facilioo creates the document share for that party right away, in any document group.
Creating a document through the API doesn't: it only triggers automatic sharing, so in a group without automatic sharing, create the share yourself.

Document shares

A document share grants one document to one party.
It is the only thing that gives any party other than the creating party (e.g. a tenant or owner using the facilioo app) access to a document.

FieldMeaning
documentId, partyIdThe document and the party receiving it. A document can be shared with a party only once. Both values are fixed after creation.
wasRead / readAtWhether and when the recipient opened the document. The recipient can set wasRead to true, never back to false.
wasSentWhether the document was sent to the recipient (e.g. by email, push notification or letter). facilioo sets it when it sends the notification for the share, and the sender can toggle it by hand; the recipient can't change it. It is used for tracking only and has no effect on access.

A party sees a shared document only while all of these are true:

  1. A share of the document exists for the party.
  2. Neither the document's group nor any group above it is hidden or deleted.
  3. The document is not archived (see Archived documents).

Deleting a share removes the access immediately.

Automatic sharing

Automatic sharing creates and removes document shares from the document's assignment, so that a document always reaches the right parties, including parties who move in later.

When it applies

Automatic sharing applies to a document if:

  • it is filed in a document group that is configured for at least one contract type, and
  • it is not archived.

For documents at root level or in groups without a contract type configuration, facilioo never creates or deletes shares on its own.
Sharing is then completely manual, also for a document with partyId.

Who receives the document

facilioo uses the most specific of the document's partyId, contractId, unitId and propertyId and ignores the less specific ones:

Most specific assignment setShared with
partyIdExactly this party, whatever its contracts are.
contractIdThe party of this contract, if the contract is current and its type is configured on the group.
unitIdThe parties of all current contracts of the unit whose type is configured on the group.
propertyIdThe parties of all current contracts of all units of the property whose type is configured on the group.

A contract is current when its move-in date is today or earlier (or empty) and its move-out date is today or later (or empty).

Example: You upload the house rules with propertyId = 42 into the group "Hausordnung", which is configured for tenants.
facilioo shares the document with every party that currently has a tenant contract on a unit of property 42.
Owners do not receive it unless the group is configured for owners too.

When it runs

Automatic sharing runs asynchronously in the background.
It is triggered when:

  • a document that isn't archived is created or updated, e.g. filed by upload, email, import or an interface such as SharePoint, moved to another group or assigned elsewhere,
  • a unit contract is created or deleted, for the contract's party,
  • a party is created,
  • a document group is saved with the option to recalculate its shares, e.g. after changing its contract type configuration.

Other changes, such as a changed move-in or move-out date of a contract, don't trigger it through the API.
Their effect on the shares only shows on the next run that covers the document or party.

The shares are usually up to date within a few minutes of the change.
Don't rely on the shares being there right after the change.

Shares are reconciled, not only added

Each run compares the shares a document has with the shares it should have under the rules above.
It then:

  • creates missing shares, and
  • deletes every other share of the document, including shares you created by hand.

So, for a document in a group with a contract type configuration, the assignment is the single source of truth for access.
If a party should receive such a document in addition to the computed recipients, file it in a group without automatic sharing, or create a separate document assigned to that party (partyId).

⚠️

Contract dates

Whether a contract is current is evaluated when automatic sharing runs, not when a date passes.
A contract that starts in the future gets its shares on the first run after its move-in date, and a party whose contract has ended keeps its shares until the next run for that party or document.

Manual sharing

For documents at root level or in a group without a contract type configuration, you manage access yourself by creating and deleting document shares.

A typical flow, e.g. for sharing a property document with selected parties only:

  1. Upload the file and create the document with propertyId set and a groupId of a group without automatic sharing.
  2. Create a document share for each recipient with the document's documentId and the recipient's partyId.

A document with partyId in such a group needs a manual share for that party as well.
In a group with automatic sharing, setting partyId is enough, and facilioo shares the document with that party.

Archived documents

A document can be created in the archived state (isArchived = true, shown as "nicht übernommen" in facilioo).
This is meant for ERP imports in which the property management company reviews imported documents before releasing them.

Archived documents:

  • are invisible to every party they are shared with,
  • are skipped by automatic sharing.
    Their existing shares are neither added to nor removed.

Once the property management company releases the document (isArchived = false), the parties it is shared with can see it.

When you omit isArchived on an update, the current state is kept.