The original migrator made too many assumptions about the way users actually used family studies component.
In particular, it was assumed only one patient (proband) would link to others (while others would be blank PT records or at least PT records with no family studies data), resulting in no conversion in a simple case of patient A stating to be a parent of patient B and patient B also stating to be a child of patient A. This turned out to be false, so a better converter is necessary.
The above assumptions were introduced because in the general case, unless all relations are symmetric (and they are not in practice) it is
a) hard to tell if there is some private information involved, e.g. if A refers to B and C but B refers to A but not C we don't know if maybe B is not supposed to know about C
b) since family studies allow selective inclusion/exclusion, in many cases there is an ambiguity, e.g. many different pedigrees matching the indicated relationships.
It was decided to partially ignore problem a) above if the family is small, and deal with problem b) by only converting the most simple (but at the same time most common) pedigree structures, as outlined below:
1) none of the family members already have a pedigree (if there is one, some comments will b added to existing pedigree nodes, similar to the original migrator)
2) all relations are consistent, e.,g. if A refers to B as a sibling B should also refer to A as a sibling (or not refer at all)
3) similar to the original migrator, only PARENT/CHILD/SIBLING/TWIN relations are used to generate a pedigree (since others are ambiguous, e.g. we don't know if an uncle is maternal or paternal)
4) all family members fit in the following pedigree:
5) there are no other relations between the patients in the pedigree, e.g. grandparents are not uncles to anyone, etc.
6) all patient records have the same owner (in PhenoTips)
Additionally, if a pedigree already exists and there are nodes with external IDs matching existing patients owned by the same person who owns the proband, those nodes will be linked to those patients (new compared to the original migrator)
Finally, externalID should not be set (to proband's last name) for newly created families, since with the new design we may not guess the proband correctly 100% of the time.