DICTIONARY OF ATTRIBUTES

TABLE OF CONTENT

• Collection of attributes

  • Person
  • Contract
  • Part

• Documents

• Attribute specifications

• Utilities

ATTRIBUTES COLLECTION

You'll find hereafter information about only some attributes included in collections. These information precise the meaning and/or behavior of the selected attributes as it might not be obvious at a first glance.

CONTENT

PERSON COLLECTIONS

ABSTRACT PERSON

This collection allows to deal with all sort of person, wether they are "physical" or not, like a private company for instance. Another benefice is to create some entities from several physical person, like a mariage (union). dealing in the real-estate universe, this allows to consider that the owner of a good is the union, and is so unique.

A (abstract) person can be part of a (abstract) contract. Either as a "customer", meaning it will receive different kind of services ; or as a supplier, meaning it will offer services.

e.g. A condo has a contract with a bank. If we take a look at the condo person, we will see in the part "Services received" the contract with the bank, because the condo is in this case in a "customer" role, ; if now we switch to the bank, we will see the same contract but in the part "services offered".

Abstract person also contains several id for different kind of addresses (postal, phone, email...).

• organizationald : represents the legal entity using the system (e.g. a real estate agency). Each and every person who is created in the system must be link to this organizationId.
• legacyId : used in case of import. Represent id given in a former (and now imported) system
• name : is mandatory. The only mandatory attribute. This name is composed according to the following :

COMPANY PERSON

• corporateName : is mandatory
• companyId : see. This attribute is type of string, because it might be used elsewhere than in France, and so where official id would not be only number like in France.
• companyRegNumber & companyRegCity : official specific number given to company registered in France : RCS. e.g. : PARIS B 20140015
• shareHolders : seeNOTE : ShareHolder type is : shareholder
• vatNumber : see
• officialActivity : activity officially declared when a company is legally registered. In France, official activities are codified under the "NAF" list, available here
• servicesOffer : list of all services a company can render. Please note that one, some or all services listed here can be used in the attribute natures from the abstractContract collection, depending of the object of the contract signed between the company and its customer.
• SCI : SEPA Creditor Identifier. A unique reference for organisations collecting payments by SEPA Direct Debit.
• legalRepresentant : the from included in the legal representant contract

CONDO PERSON

In the real world, a condo is created by the condo regulation contract

• type : represents the type of the condo, throuh : CatalogValue(CONDO_TYPE)
• easyId : free ID. Can be used by trustee to reference condos according to their own numbering convention.
• companyId : see A condo must have a company ID if it has or had got employee.s
• registrationNumber : is an official number given by authorities to condos. In France, the "Agence Nationale de l'Habitat" is responsible for - link here. This number is formatted on 9 digits as follow : AA1111111 (2 char + 7 num)
• registrationDate : date when the condo was registred (see just above)
• condoCouncil : A condo has by law a council, which role is to reprensent it towards the outside world. The council is made of some members elected, during yearly General Meeting, amongst owners. From a technical perspective, each elected member has a legal representant contract

NOTE : A condo is always created, even in the case of a mono-property see here

For a condo creation process, please refer here

For a global definition of a condo, please take a look at data dictionary

DELEGATE PERSON

A delegate is a person who can act on behalf of another one. This is formalized by a contract, between a "principal" which allows the "delegate" to act on its behalf. For instance, someone wants to rent an apartment, but doesn't want to do the rental himself. he can contact a delegate (like a trustee, e.g.) and sign a "delegation" contract. Then a tenant is ok to rent the apartment. He will therefore sign a rental contrat, between himself and the owner but through the delegate. The contract will so show 3 names : the owner, the delegate and the tenant.

This is also the case for a trustee contract, where a trustee is entitled on behalf of the condo to sign different contratcs, like insurance, bank account...

see also

DIVISION PERSON

A division represents the fact that an ownership is splitted between 2 parties. For instance, can happen when the parents donate their house to their children. Children possess the house while their parents still live in the house. This constitutes an indivisible whole based on 2 categories :

• the bare-owner(s) who is the owner of the goods, but can't use it ;
• the beneficiary(ies), who can use the goods but has no property rights. (e.g. no right to sell it).

In our model, the 2 categories are represented by shareHolders : see

NOTE : each category is independant. That means each category can have 1 or several shareholder(s) for a total of 100% each, and not the 2 together. Bare-owner = 100 % Beneficiary = 100 %

FLATSHARE PERSON

• a flatShare Person is used only in the context of rental flatsharing, and specificaly when there is only one rental contract issued for all the co-tenants. See below rental contract
• Another possibility would be to issue as many rental contract as the number of co-tenants. But in this case, the "toReceiver" of the contract would be the natural person itself.

INDIVISION PERSON

An indivision represents a legal entity made of several persons (wether physical or not) that share an ownership. An indivision must comprise at least 2 members, named "undivided".

• shareHolders : seeNOTE : ShareHolder type is : interest_Holder
• legalRepresentant : the from included in the LegalRepresentant Contract see

NATURAL PERSON

Represents a physical person

• lastName = family name, the one who is given at birth. A last name can be (at least in France) a combination of 2 names
• usageName = either a spouse name, or a family name not declared at birth (e.g one can have his father's name, but want alos to use his mother's one)
• nationality : type of country => points towards official ISO list of countries
• civility : is mandatory. From here can be deducted the gender : SIR = male, etc etc....
• gender : is not given in front end but deducted from civility
• user : this concept is of importance. A user can be assigned to a natural person for security access reason. For details about user access management, see here

COOWNER PERSON

Group person is used in context of the condoRegulation contract. It represents "dynamically" a "collection" of persons, of any kind (natural, company...), who are owners.

To see when a co-owner is created, please refer here

UNION PERSON

A union concerns either an official marriage or a free union. Made of 2 natural persons. The union type attribute qualifies the legal marital status.

UNKNOWN PERSON

It might happen that a person would remain unidentified. One case could occur in a contract, where e.g. the "fromSupplier" part would be unknown. In such a case, the unknown person would be used.

RELATIONSHIPS BETWEEN PERSONS

As describes above, some "special" persons, like Union, Division, Indivison and Company comprise shareHolders. The shareHolders can be any kind of person, so for instance, a company can be potentially shareholder of another company. Usually, in most of the cases of our application context, shareHolders will be natural persons.

See below shareholder collection

SHAREHOLDERS

Despite its name, this object is used besides the "company" collection, enlarging the concept of "sharing" : wherever 2 or more "members" have a part of an entity, they will be considered as a "holder" with a "share". ShareHolders can be found in : Company, Union, Division, Indivision and Group person.

The ShareHolder collection contains :

• a holder, which is the abstractPerson holding a share
• a type, corresponding to the concrete person to which shareHolder is linked :

• a share : the amount of shares hold by a shareHolder
• a divider : represents the total amount of share.

NOTE : some shareHolders may have a share at zero. This happens for type member (group person)

CONTRACT COLLECTIONS

A contract is between 2 persons, meaning "from" a person "to" a person (so defined in abstractContract). The "from" offers a service, and the "to" receives it. Any person can have : 0..n contract(s), and can offers and /or receives services.

In the model, a real contract (like e.g. a supplier contract) is actualy made up of 2 contracts : an abstract contract and the real contract (supplier contract in our example). Both share the same id.

CONTRACT MASTER DATA

This collection allows to deal with all sort of contracts, concluded between 2 persons or more, whatever their nature is : natural, company, condo, unknown... This is the meaning of the "fromSuppliers" (AKA "FROM") and "toReceivers" (AKA "TO") attributes. Receiver notion refers to the beneficiary of the service provided by the supplier.

Note 1 : in some case a contract can have several from and/or to. For instance, in the condo regulation contract, there are several co-owners as "to" ; in a rental contract, the "from" is the association of the owner and the real estate agency.

=> in such case(s), a group person will be used to gather the different "from" and/or "to"

Note 2 : It is important to note that there is not necessarily a "real" supplier and a "real" receiver, as it might happen to get a contract between entities that are not "physical". It might be also that a contract be concluded between the entity itself (theoretically, no real case currently).

About the dates : a contract can have at least 3 dates :

• begin : corresponds basically to the effective start date of the contract
• end : when the contract ends
• signatureDate : every contract can have potentially a date of signature. This date might differ from the begin date. E.g. a rental contract is signed on March, 20th with an effective date (= begin) on april, 1st

Attributes :

• organizationald : represents the legal entity using the system (e.g. a real estate agency). Each and every contract created in the system must be linked to this organizationId.
• origin : qualifies the origin of the contract : a creation, a take-over (e.g. a rental contract already existing) or a transfer (and more possible)
• legacyId : used in case of import. Represent id given in a former (and now imported) system
• externalId : the number of the contract given for instance by the supplier, an insurance company.
• EasyId : some types of contract can be numbered or must be legally numbered according to a chronological sequence : see. For instance, the Rental Delegate Contract or the Rental. Each contract has a separate sequence : i.e. RDC1, RCD2.... for rental delegate contract ; RC101, RC102...for rental contract
• serviceOffers : the object of the contract. E.g, opening a bank account is representing a "bank" activity. see also
• legalAct : represents any official document binding the involved parties. It may be e.g. an email in the case of the oral contract.
• inChargeOf : when a contract is signed between 2 entities (a "fromSuppliers" and a "toReceivers"), it is possible to say who will be in charge of the contract excecution. It might be 0, 1 or n persons. Let's take for instance a contract between a condo and a Trustee. The trustee manager will assign an account manager, an assistant and an accountant to this particular condo. These 2 people will have an employee contract with the trustee. In that case, employee will be "from" and trustee the "to". This attribute is also used in the security area, defining who can access what.
• relatedParts : represent the part(s) subject of a contract. E.g. the part(s) owns by a owner ; the part(s) given as a rental ; the part(s) addressed in maintenance by a supplier...see also Part

ABSTRACT PART CONTRACT

Suppressed as of 03/2019. Its only attribute (relatedParts) has been included within Contract Master Data.

BANK CONTRACT

• Used to store bank account number for any kind of person that owns one. The bank is the FROM.
• Consistency IBAN should be checked

CONDO REGULATION CONTRACT

For a global definition, please refer to Data dictionary

This contract so-called CRC is concluded between the condo and several persons who are co-owners. In the Contract Master Data, the "FROM" is the condo ; and the "TO" is a group person, called coower person that represents dynamically the different co-owners => means that co-owners are not stored in this group person but are identified dynamically through their part.s

The path is the following : an agency has a trustee contract with a condo. The condo has a CRC, in which there is, as relatedParts, the property (PART0). This property contains a building, which has units => these units belong to a co-owner

NOTE : This contract is created automatically when a condo person is created.

To see when a CRC is created, please refer here

REMINDER : in both trustee activity and rental activity a condo is created, meaning a CRC will always be present in both cases.

CONTACT CONTRACT

info :contract initially set-up to qualifiy the type of person : owner, tenant, supplier...
supressed as of 05/2020. Every object is now linked to a organizationId

DIAGNOSTIC CONTRACT

Info : in order to rent, buy or sell a part (like a flat), some technical checks must be done (by law)
replaced as of 09/2020 by document metadata

EMPLOYEE CONTRACT

In our model, only two entities are entitled to hire people : the trustee and the condo. Please note that a condo may have none employee, and same for the trustee (in case of a only one person is managing the trustee).

• the employee is the FROM of the contract
• the TO of the contract is the company that has hired the employee

GENERIC CONTRACT (not in use)

Generic means that this contract can cover multiple natures, essentially :

The nature of a generic contract (actually "subject" attribute in the generic contract collection) are represented by one or more element(s).

• an element is a set of at least 2 items, up to many.

• Elements can be chosen amongst an enum or can be type-in.

• To avoid irrelevant combination by choosing any item in any list, combinations of items are pre-defined.

• an item is made of a key and a value. A key can be a combination of previous key and value.

LEGAL REPRESENTATION CONTRACT

Represent an official mandate given by one entity to another, whether amongst its member or not. For instance, a condo can nominate during annual general board meeting some owners as constituting the conco council, that will represent the condo towards the trustee. We also consider that a CEO or a MD, due to his position in a company, as also implicitly "subscribe" this kind of contract between himself/herself and the company he/she represents.

• In that sense, the FROM will be the person representing an entity
• the TO will be the entity represented : the company, the condo, the indivision...

ORAL CONTRACT (not in use)

This particular contract may occur in different situations :

• a owner (physical person) would like to do some small maintenance / repair in the common parts of his/her building. This owner needs first an approval of the trustee, which can be given over phone => he/she will be the FROM

• it might happen some emergency situation, like for instance a big leak occurring suddenly in the common parts of a building. The trustee will call a plumber to act very fast, without asking approbation of the condo.

OWNER CONTRACT

Represents the acquisition of a property which is a part of a condo : apartment, garage, commercial premise... As every contract, there is a "FROM" and a "TO". The "TO" is the new owner, which is clearly identified. Normally the "FROM" is known, nevertheless it may remain unidentified, namely in the case where a condo has decided to go for a new trustee. In such a case, the trustee will do a data transfer, including the current owners but not necessarily the previous ones.

• buyer : person who buys a part. In most of the case, the sold part belongs to a building which is or become a condo, meaning the buyer is actually a co-owner.

RENTAL CONTRACT

Rent between the owner of part(s) and one or more tenant(s). The owner will be renting through a real estate agency (the delegate) => the FROM will be a group person. In case of more than one tenant (co-tenants), there will be also a group person in the TO

• rentalDurationNormal : unit is year
• rentalDurationShortened : unit is year or month
• initialRentAmount : unit is €/month
• previousRent : unit is €/month
• InitialRentChargesAmount : unit is €/month
• chargeEconomicSharingAmount : unit is €
• chargeEconomicSharingDuration: unit is month
• cotenantInsuranceAnnualAmount : unit is €/year
• cotenantInsuranceMonthlyAmount : unit is €/month
• improvementWorksAmount : unit is €
• improvementWorksRentIncrease : unit is €
• improvementWorksRentDecrease : unit is €
• improvementWorksRentModifDuration : unit is €/month
• rentDepositAmount : unit is €
• rentingMediationLandlordFeesWithoutVAT : unit is €
• rentingApplicationFeesLandlordWithoutVAT : unit is €
• rentingApplicationFeesTenantWithoutVAT : unit is €
• rentingInventoryLandlordFeesWithoutVAT : unit is €
• rentingInventoryTenantFeesWithoutVAT : unit is €
• noticeDate : the date on which agency officialy receives the notice letter from the tenant (tenant is leaving)
• noticeReason : reason for which the tenant is leaving. Has an impact on the noticePeriod.
• noticePeriod : usually 1 or 3 month, starting from the noticeDate. But in some case, notice period can be shortened => In that case, a noticeReason would be given
• endDateIsDifferent : it also might happen, in some exceptional case, that the effective end date cannot be met and must be changed (before or after theoretical end date)
• Indexes : refers to a separate collection. This index is retrieve from the collection based on the begin date of the contract, and is normally the last known index as of begin date of the rental contract. This because indexes are published on a quarterly basis, but in the next quarter.
  E.g., index for Q4/2019 will be published around 15/01/2020. Q3/2020 will be published around 15/10/2020. So if a rental contract is signed on 02/02/2020, the last known index would be Q4/2019.
  If it might happen for some reason that the publication of an index is delayed, the same principel applies. Let's assume that Q4/2019 is not yet published when the rental contract is signed on the 2nd of february 2020 => in that case, we would take Q3/2019.
  For more details and example, see revision index
• inventory : value object see below
• annualRentReviewPoint (ARRP): represents a day + month (dd/mm) when each year the rent review should occur. E.g. a new rental contract is created on march 10th. Its begin date (= begin date) is : april 1, 2020. The ARRP will be set to : 01/04.
• takeOverDate : date to when an existing RC is taken over (i.e. from another agency)

NOTE 1 : this contract must have a unique easyId (given by the system)
NOTE 2 : As of april 2020 : only index "IRL" is used

RENTAL DELEGATE CONTRACT

Rent between the owner of part(s) and a delegate that is in charge of renting the part(s).

• the real estate agency is the FROM of the contract
• the TO of the contract is the owner
• plannedPayDay : the owner is paid according to frequency on a day defined on advance
• managementFeesWithoutVat : unit is %
• rentingMediationLandlordFeesWithoutVAT : unit is €
• rentingApplicationFeesLandlordWithoutVAT : unit is €
• rentingApplicationFeesTenantWithoutVAT : unit is €
• rentingInventoryLandlordFeesWithoutVAT : unit is €
• rentingInventoryTenantFeesWithoutVAT : unit is €
• Status : related to state machine states
• EasyId : contract must have an easyId, starting to 1. The number is given by user in FE.

NOTE 1 : easy Id given must be validated => check :
1 - this number has not already been used ;
2 - that this number is strict following the last recorded one.
E.g. if the very first number reordered was 17, 17 can not be use anymore ; and the next one MUST be 18.

NOTE 2 : If a number has been given to a contract that is cancelled, this number must be archived and shall not be attributed again.

TRUSTEE CONTRACT

Contract signed between the condo and a trustee. For more information, please refer to general concept in see Data Dictionary

• the FROM of the contract depends on the context :
  • case the user that creates the contract is acting as a trustee => FROM is the trustee
  • case the user is acting in the context of rental activity, that is he/she needs to create a building, then the unit to manage the rent, but the building is actually a condo (vs mono-ownership) and is managed with a trustee :
    • the trustee is not the same as the rental agency => FROM is a supplier
    • the trustee is the same as the rental agency => FROM is the trustee
• the TO is always the person condo

PART COLLECTIONS

PART CONCEPT

A part is a global concept representing a portion of a property.Parts are represented through a graph (hierarchy). The property is the highest level of the graph.

Part can have 6 main types (collections) :

• Property
• Building
• unit
• common equipment
• common space
• Component

As an example, let's consider a single building, made of 10 units, using an elevator and including a garden. In our model, there will be 5 kind of parts :

• 1 building
• 10 parts for the 10 units
• 1 part for the garden, type "common space"
• 1 part for the elevator, from type "common equipment". The elevator can contain some components, like e.g. the engine

Every part is a composition of a abstract part as a core, and a collection that characterize the part itself.

ABSTRACT PART

This collection contains the minimal set of data common to each type of part described above.

• organizationald : represents the legal entity using the system (e.g. a real estate agency). Each and every part created in the system must be linked to this organizationId.
• legacyId : used in case of import. Represent id given in a former (and now imported) system
• easyId : number given by the agency for convenience
• mortgageNumber : official number given by mortgage registry
• creationDate : is a string as the accurate date can be unknown and so typed in as e.g. "before 1920"
• name : is mandatory

PROPERTY

Property is a special part, so-calls "PART0", which is systematically created when a building is added. It represents the top of the parts hierarchy.
A property can be held by only 1 owner (= mono-property), or by several owner (= condo-property), see condo
NOTE : A property is always created along with a condo independently of the scope of activity, whether it is trustee activity or rental activity

A property may have an official address, namely if it contains several buildings located at the same address

For a property part creation process, please refer here

BUILDING

• surfaces : unit is square_meter

UNIT

• surfaces : unit is square_meter
• unitRooms : unit is pieced

EQUIPMENT

• surfaces : unit is square_meter

SPACE

• surfaces : unit is square_meter

PART RELATIONSHIP

A part is always in relation with another part, which thus creates a relationship between one part defined as a "source" and a destination part called the "target". The relationship is also characterized by 3 parameters :

• "uses" : defines which part is the source and which one is the target, by representing the fact that the source has usage of the target. E.g. a flat has the usage the elevator (actually the owner of the flat)
• "owns" : the source part can also be owner of the target part, fully or partially. E.g. a flat has some ownership rights on a portion of the property, i.e. a portion of the common parts.
• "pays" : the source always has to pay for the usage of some part(s). A unit has always to pay for the usage of the common parts

Each of these 3 parameters held a ratio number, not necessarily expressed in %. A unit can for instance owns the 541 / 1 234 portions of the common parts. In that case, the ratio is defined when the condo had been created or modified. All ratios of the same nature (e.g. "pays"), same type (e.g. 2), and group together by a relationship having the same target part, determine an allocation key

DOCUMENT COLLECTION

In its daily work, a user may have to enter into the system information coming from real documents, and also may upload an electronic version of this document. Documents can be regarded as : paper documents, emails, pictures...

The information contained into a document are store in a documentData collection ;
The files themselves (electronic .pdf, .jpg....) are stored apart, in another DB

Please refer to document section to see diagram

DOCUMENT DATA

• allowedTargetType : documentData must be linked to one of the master objects : Person, Contract, Part or AccountingEvent

note : accountingEvent yet tbd

• documentType : defines a high-level type of document, like Identity, diagnostics, Bank...

• document Nature : qualifies the type. Several natures can be related to a type, but only one nature can be chosen. For instance, for type = Identity, the nature could be found amongst {idcard, passport, driving licence}, but only passport could be selected.

• lifePeriod : the document can contain a life period, meaning for instance that it is valid only for a certain period of time. e.g. a insurance certificate valid from 01/01/2020 to 31/12/2020.

• data : actually a map which can contain 0 or several DataKeys :

Here is a full example of a map :

• attachments : a document data can contain 0 or several electronic files. Attachments can be created after documentData object, reason why creationDateTime can differ one from the other.

FILE

• fileName : a file must contain a name. The user may (or not) change the file name when uploading it.

• Url : the url where the file is stored.

NOTE :

• file are stored in an external DB and not in the core application one.

ATTRIBUTES SPECIFICATIONS

SERIAL NUMBERING

• A cron is a sequential numbering given for some objects :

  • RentalDelegateContract
  • RentalContract
  • ticket

• The sequence must be continuous

• Format numbering is done according to the following :

• once a number has been used, it cannot be re-used. If for instance number is given in a contract, and the contract is then cancelled, its number cannot be re-used for a new contract.

COMPANY ID

official number given for every company. In France, this number is known as "SIRET", given by the "INSEE" organism. This number is unique and formatted on 14 digits (only num). The first 9 digits represent the SIREN (company HQ) and the following 5 digits represent each and every branch a company may have.

VAT NUMBER

Number given by tax authorities in every country member of the european community (EC). This number is mandatory for trading across EC, namely for VAT purposes. In France, this number is under the following format : FR + 2 figures + SIREN (see above).

UTILITIES

ACTIVITY (VALUE OBJECT)

List of all activities that a company can offer.

• agreement (Boolean) : some activities being regulated, the company must be granted an official agreement (e.g. professional card, delivered by the commercial chamber, for the trustee).

PERIOD (VALUE OBJECT)

• effectiveDate : can be assimilated to a document date. Represents the date on which a document has been issued
• discharge : date when a judiciary decision is deemed finished
• before : it might happen that a precise date would remain unknown. In such a case, only the year would be fulfilled.

QUANTITY (VALUE OBJECT)

quantity value object receives number data and their unit (if any). For instance, an amount of 100 € will be a couple (amount = 100 ; unit = euro) ; a water price will be recordered as € / m3....

REGISTRY OF MANDATES

For some contracts, an official list of mandates ("registry of mandates") and / or of transactions with all numbers and related information must be maintained. This list is completed with object related. If an object has been cancelled, the list has to express this case.

• list for mandates :

  Number	Signature	Client	Client address	Object	Part	Transaction#	Comment	State
  cron	signature date	person client in the contract	client address	"rental Delegate Contract"	part number + part description	none	free text	state of the contract
  Example:
  RC-000001	15/03/2018	M. John Doe	3 rue des fleurs 06000 Nice	rental Delegate Contract	unit# 3 / appartment	none	free text	provisioned
  RC-000002	07/10/2018	Ms. Carry Doe	15 rue Dugué 06560 Antibes	rental Delegate Contract	unit# 17 - appartment + unit# 22 / cellar	none	free text	cancelled

NOTE 1 : information about chrono here

NOTE 2 : transaction number is the number pointing towards registry of transaction.

RENT INVENTORY (VALUE OBJECT)

rent inventory is used to store values related to the inventory done when a new rental contract is signed, and when the contract ends. The idea of inventory is to check if the apartment (e.g.) is correct, or if some works have to be done because of misuage from the tenant.

• inventoryDateIn : when inventory is physically performed at rental contract creation
• inventoryDateOut : when inventory is physically performed at the end of the rental contract. Tenant remits the keys.
• inventoryOutCompliance : result of the inventory. value = CatalogValue
• endContractSettelmentTerm usage ? represents the maximum date to which the full tenant account must be settled calculation ? inventoryDateOut + parameter This parameter (to be created and store in UTILITIES) represent a legal period of time to be added to the inventoryDateOut, and depending on the result of the inventory compliance (inventoryOutCompliance) :
  • compliant => 1 month
  • not compliant = > 2 month