Modify a Person in FamilySearch

An existing person's information in FamilySearch can be changed.

Assumptions

• The user must be signed in to FamilySearch through your application.
• The user must select the option to edit the person information.

Programming Steps

1. Read the existing values for the person.
2. Give the user the option to edit current values.
3. Post the updated information.

User Interface Suggestions

To modify vital information of a person, comply with the following user interface guidelines.

1. Prompt the user to modify the following information one item at a time or on a form.
   • Name
   • Gender
   • Birth Date and Place
   • Christening Date and Place
   • Living or Deceased
   • Death Date and Place
   • Burial Date and Place
2. When editing an item, show the prior contributor, date, and reason.
3. Prompt the user to enter a reason for each update.
   • Show the prior reason, if available, in the reason entry box
   • The label of this entry box should be “Why this edit is correct”
   • The user can add to it, write over it or delete it.
   • Provide a button or prompt to "Add Sources"
4. SAVE or CANCEL the edit, and return to the Modify screen.
5. Click DONE to return to the previous function in your app.

See Also

• Person Data Format (XML)
• Person Data Format (JSON)
• Persons Guide
• Create a Person

Person Delete

A person can be deleted after the relationships to existing persons are deleted.

Typically you should remove relationships rather than delete a person. Rarely would you delete a person you did not add.

Assumptions

• The user is signed in to FamilySearch through the third-party application.
• The user has searched for matches in Family Tree and found no possible matches.
• The user knows how the new person is related to an existing person in Family Tree.

Programming Steps

1. Search for an existing person and show all information about the person.
2. Show discussions for the person.
3. Show Relationships the person has.
4. Show sources that are attached to the person.
5. Delete relationships.
6. Delete the person.

User Interface Suggestions

1. The user selects a person to delete.
2. Display the person's vital information. a) Display the discussions with a cautionary message. b) Display the relationships with a cautionary message. c) Display the sources with a cautionary message.

3. Click PROCEED or CANCEL.

   

4. Present a confirmation page, and prompt the user to provide a reason for deleting this person.

5. Prompt the user to agree to the following three statements:
   • I have read the other reason statements above.
   • I have reviewed the couple and parent-child relationships for this person.
   • I have provided a reason statement regarding why I feel this person should be deleted.

6. Click DELETE the person or CANCEL.

   

Standardization of Event Information

Data for vital events such as birth, marriage, and death should be standardized using normalized values from FamilySearch Authority APIs or the partner standards. FamilySearch Authority APIs are the preferred method of standardization. Standardized values help to maintain accuracy in identifying person matches and duplicates.

Places should be standardized for the following:

• Events in a person's life
• Couple relationships events
• Parent-child relationships events

Other information fields should be standardized as well but are not required.

Assumptions

• The user must be signed in to FamilySearch through the app.
• The user is entering a date or place for an event in a person’s life.

Programming Steps

1. Capture information using a dropdown form item.
2. Search possible standards from the FamilySearch Authorities API module or the partner's authorities database.
3. Populate the dropdown with possible standardized values to select.
4. Update the website with standardized value.

User Interface Suggestions

1. Prompt the user to enter place and request a standardized value

   

2. Provide selection of standardized choices

   

3. Indicate that value selected is standardized

   

See Also

• Seach For Places

Person Compare and Transfer of Partner Application Data to FamilySearch Data

Person vital facts from third-party databases can be compared with values in FamilySearch. Values can be added or replaced in FamilySearch as long as the existing attribution and prior contributor's reason have been viewed. All transfers to FamilySearch must include the new reason for the addition or change.

Assumptions

• Select a person in the partner application to compare with a person in FamilySearch that is already linked.

Programming Steps

1. Read a Person.
2. Update a Person.
3. Add a Person.
4. Add a Fact (conclusion).

User Interface Suggestions

1. Show a comparison of person information between the partner application and FamilySearch.
2. Provide buttons or links for Sources, Discussion, and Change History. Sources and Discussions should show a count of activity.
3. More and Less buttons show and hide additional details of fact or events listed for the person. More should always include the attribution and the contributor's reason. The application could choose to show More as the default. The attribution and reason must be shown before any change is made to the FamilySearch person.
4. The tagged sources can link to a list of sources or display the sources in FamilySearch for this person with the facts or events that are tagged. Optionally, the process may be used for Notes and/or Person Sketches.
5. Marking a checkbox indicates that the third-party application's values for the fact or event should be added to or the values replaced in FamilySearch.
6. Present a dialog that provides the detail information with a listing of the sources. The user can submit or cancel the change after entering the reason for the change.
   The user is returned to the comparision page where the changed values now match.

Notes:

• The user flow does not depict a confirmation of changes before committing the changes. You might want to present a summary of changes and ask for confirmation before writing the changes.
• Group multi-value facts (nonvitals) need to be compared and maintained individually. All FamilySearch values need to be presented underneath the fact. For example, each job and date needs to be presented for the occupation multi-value fact.
• The attribution and prior reasons need to be presented and the ability to add "why this edit is correct" for each value.
  • Show the prior reason, if available, in the reason entry box
  • The label of this entry box should be “Why this edit is correct”
  • The user can add to it, write over it or delete it.

Check for Duplicates

Preventing the performance of duplicate persons and their information is one of Family Tree’s main purposes.

Issues

To prevent duplication, a person’s record must be merged with the duplicate person that contains the duplicated information. This may create the following challenges:

• End users may become discouraged or bored if they have to review too many possible duplicates.
• Users may be confused if they merge some duplicate records and then later find that more possible duplicates exist for the same person.

Minimum Requirements

• Offer the user through a prompt, menu item, or button the option to check for "Possible Duplicates". This option should appear before or on the screen where users add or change the person's information.
• Provide your own duplicate maintenance using the API, or redirect the user to the FamilySearch Possible Duplicates page specified in the “duplicates” context parameter. For more information, see the Persistent Identifiers guide.

Restore to a Previous State in FamilySearch

The change history log in FamilySearch can be used to assist in performing the following changes.

• Delete a resource that was added
• Restore a resource that was deleted
• Restore a person deletion

Deleted persons, their relationships, and the reasons for changes are found in the Change History Log. Restoring a deleted person restores the person and the parental relationship.

Note: Restore functionality is not required for partner application certification.

Programming Steps

1. Select a person to review.
2. Read the change history, and display it.
   • For actions, list the value, attribution, and reason for the current and historic actions.
   • For persons, list the person and the parent information.
3. The user selects an item to restore and enters a reason.
4. Restore the change that was selected.
   • Restore an action.
   • Restore a person.
   • Restore a parental relationship.

User Interface Suggestions

When selecting the person to restore, display the following information:

• Summary information of the deleted person and the parents.
• The current value and the value of the data being restored.
• The reason, contributor, and last modified date for the current value.
• Give an opportunity to enter a reason for performing this restore.

Change or Delete Relationships in FamilySearch

Couple relationships and parent-child relationships can be changed or deleted. Before the relationship is changed or deleted, show the people in the relationship, the date of the relationship, the type of relationship, the attribution, and the prior reason and sources. Before the change is committed, prompt the user to enter a reason for the change.

Programming Steps

Update Couples

1. Read Couple Relationship of a person to obtain the "Couple ID".
2. Read Couple Relationship Sources to view details of the sources attached to a couple.
3. Read Couple Relationship Source Reference to view a list of sources attached to the couple.
4. Update Persons of a Couple Relationship to change the persons in the couple.
5. Update Couple Relationship Conclusions to add or change statistics relevant to a couple.

Update Parent-Child

1. Read Child-Parent Relationship
2. Read Child-Parent Relationship Sources
3. Read Child-Parent Relationship Source Reference
4. Update Child-Parent Relationship
5. Update Child-Parent Relationship Conclusions

Delete Couples and Parent-Child

1. Delete Couple Relationship
2. Delete Couple Relationship Conclusion

User Interface Suggestions

1. The user selects a person.
2. Show the existing relationships.

3. The user selects a relationship to change or delete.

4. Change Relationship

   Couple Relationships are changed by adding an event for marriage, annulment, common law, or divorce. Show the existing relationship event and date. Select the relationship, enter the date, place, and the reason before saving or canceling.

   Parent Relationships are changed by editing the parents of a child relationship type which includes adoptive, biological, guardianship, foster, or step. Select the relationship, enter the date, place, and the reason before saving or canceling. The relationship can be set separately for each parent.

   Child Relationships are changed by selecting the child and changing the relationship with the parents.

5. Delete Relationship

   Show the vital facts of the persons involved in the relationship and the number of attached sources and events. Prompt for a reason for the deletion before deleting, or cancel and return to the Select Relationships page.

Merge Persons Maintenance in FamilySearch

After person records in the application database have been linked to FamilySearch persons, possible duplicate records must be identified and merged where appropriate.

Check for duplicates, and provide enough information to determine if the person should be merged. Present a name-by-name comparison so the user can make a correct decision.

Assumptions

• Possible matches have been requested for a focus person from that person's summary or detail page.

Progamming Steps

1. Read Person Possible Duplicates
2. Merge Persons

User Interface Suggestions

1. Display a list of the possible matches of the selected or focus person. Include name, person ID, birth and death events, parents, spouse, and sources. Provide a "Merge by ID" option to merge a specific person ID with the focus person.
2. Provide an option to show a list of the persons who are not matches.
3. For each possible match, provide a preview merge option which will show a side-by-side comparison of the person records with an opportunity to merge them.
4. The Not Matches list shows the persons that are specified as not a match with the focus person. "Review Details" goes to the Review Not a Match page.
5. On the Preview Merge page, the expansion of possible match information reveals a choice to replace the focus person information.
6. Information will not be merged unless this radio button is selected.
7. Merge goes to a confirmation page of the matches that will be merged.
8. Not a Match goes to the Not a Match Dialog. Cancel makes no changes and returns to the Possible Matches page.
9. The Review Not a Match page displays the focus person on one side and the not a match person on the other side of a page. Prompt the user for a reason. Remove removes the person from the not a match list and returns to the Possible Matches page. Cancel returns to the Possible Matches page.
10. The Merge confirmation page shows the facts that will be merged. Prompt for a reason. Finish completes the merge and returns to the Possible Matches page. Cancel returns to the Possible Matches page.
11. The Not a Match Dialogue page displays the focus person on one side and the possible match person on the other side of a page. Prompt the user for a reason. Finish puts the person on the not a match List and returns to the Possible Matches page. Cancel returns to the Possible Matches page.

Important!

• The application must make it clear to the user which information will survive. The option to submit a reason why the information is correct must be offered.
• The application must provide the ability to select which specific values will be replaced and which will be preserved after the merge, including vitals and other information, parents, and children.
• The user must be able to choose to bring over any relationships and sources that do not exist with the focus person.
• The application must prompt for a reason this merge is correct before finishing the merge.
• Summary of any sources related to the person should be displayed before finalizing the merge.

Restore Merged Persons

Sometimes two persons are incorrectly merged and need to be unmerged. That is, the merged persons need to be restored as two individuals. The history of merged persons is found in the Change History of the surviving person. After the merge is found in the Change History, the persons can easily be restored to their state before the merge.

Assumptions

• You have the Person ID of the person you want to unmerge.

Programming Steps

1. Display the Change History of the merged person.
2. Display the summary of the two persons that were merged together and the reason they were merged.
3. Unmerge the selected person.

User Interface Suggestion

1. View the Change History of a person, and locate the merge that you want to unmerge.
2. Proceed to unmerge the data.
3. View the summary of the two people to be unmerged and the reason they were merged.
4. Enter a reason to unmerge.
5. Finalize the unmerge or cancel.

See Also

Merging Guide

Notify Users of Watched Person Changes and Other Activities

FamilySearch Family Tree has the ability to watch and unwatch changes on a person, and to show a list of watched persons. The user who sets the watch on a person gets an email notification about each change. This allows Family Tree to easily keep users aware of changes to persons they are interested in.

FamilySearch does not offer the Watch feature in a public API. Therefore, application developers must assume the responsibility to notify their users of changes to persons they are interested in. Before important tasks are performed, the users should be notified of changes that have happened. Alternatively, the application could display the most recent changes in the change history every time the user views person summary or person detail information. Activity stats should also be reported for Sources and Discussions changes.

Programming Steps

• Compare FamilySearch data with application stored data.
  • Person data. Read Person
  • Etag value. Read Person Change Summary
  • Recent changes to Change History. Read Change History
• Additional Sample Code for Activity Stats.
  • Read Person Sources
  • Read Person Source References
  • Read Discussion References

User Interface Suggestion

Compare with Stored Person and Etag Values

1. The user requests to see person information.
2. Report the number of sources and discussions on the person.
3. Show possible differences between the partner data and FamilySearch data.
4. Prompt the user to do a detailed comparison and decide to update person data on the partner app.

Report on recent changes to Change History

1. The user requests to see person information.
2. Report the number of sources and discussions on the person.
3. List a summary of the latest changes on the request person.
4. Prompt the user to do a detailed comparison of changes and decide to update person data on the partner app.