What is it?¶
Within SEED, matching refers to a possible relationship between at least 2 properties or at least 2 tax lots. Two properties match if they have the same values for some specified field(s). These specified fields are referred to as matching criteria, and each SEED organization has its own set of matching criteria which is customizable by users.
Why does it exist?¶
At a high level, matching is used to identify if two or more property records are actually different representations of the same property (or tax lots representing one tax lot). For example, within the same cycle, two matching records, so one persists while the other is used and subsequently discarded to update the persisting record (say if the building owner’s phone number changed). Or across different cycles, it’s possible that the two records capture the same property at different times/cycles - this relationship is referred to as a link.
How and when is it used?¶
(This is different from manual merging.)
For records within the same cycle, there really shouldn’t be more than one representation of the same property (or tax lot). As much as possible, the program is set up to prevent this from happening by automatically merging matched records together whenever they might occur in the same cycle.
Specifically, a merge of matches might need to occur after any of the following events:
The record has been manually edited.
The record was just created as a result of a manual merge (via the ‘Actions’ on the Properties or Tax Lots page).
The record has just been imported.
The actual execution of merges includes a few additional, unrelated steps but, in the scope of merging, the following occurs.
The record in the scenarios listed above is the “target” record. Any and all matches found, excluding the “target”, are merged together first. If there are overlapping values, priority is given to more recently updated records.
Once these matches (excluding the target) are merged together, the final step is to merge the “target” record. In all but one case, choosing between overlapping values gives priority to the “target”. That one case is when a record has just been imported. Here, overlapping values follow merge protection rules set by the user for an organization in this final step.
Note on In-Cycle Not-merged Matches¶
Even though the application tries it’s best to have only one representative record per property (or tax lot) per Cycle, it’s possible for there to exist matches that were not merged. This can happen if a user manually unmerges a record after a (manual or automatic) merge occurs. If this happens, and there exists two records that match each other but are not merged, both records are completely unlinked. Without user intervention such as editing one of the matching criteria values, these will be merged and linked as described above next time the system finds them during a match search.
Match Searching in Depth¶
Though they accomplish the same goal, the process for merging is very different between the last case, importing, and the first 2 cases, manual edit or manual merge.
In the case of manual merging or editing, this process accounts for the fact that these are records that already exist. Specifically, they may have associations such as labels, notes, pairings, and for properties, meters. So during a subsequent match search leading to a merge of two or more records, all of these “old” associations are carried over to the final record once merges are complete.
In the case of importing, considerations must be taken for the fact that, in most cases, multiple records are being imported together. Also, since this is the entry point for records, it’s possible that a user might accidentally try to import the same record snapshot twice - where all the record values are the same as another existing record (as opposed to just having the same values for matching criteria fields). So on import, the process is as follows:
Amongst only the incoming records, duplicates (of other incoming or existing) are flagged and ignored.
Amongst only the incoming records, matching records are merged together.
Amongst all records in the same Cycle, incoming records that match an existing record gets merged with priority to that existing record. If the incoming record has multiple existing matches, the existing matches are merged together in latest updated order first while also combining any other associations (labels, notes, etc.) just as in the manual merge or edit cases. Since the incoming record is new, it doesn’t have any of the other associations.