Read Implementation Guide

Read Change History

The change history for a person or relationship can be read. Each entry in the change history contains details about the change.

Assumptions

  • The system must have some logged history regarding a single person or relationship.
  • You must have the ID of the person whose history you want to read.

Programming Steps

  1. Read Person Change History
  2. Display the Change History Log.

User Interface Suggestions

  1. Display the following information for each change history item of the selected person.
    • Title
    • Description
    • Date
    • The user who made the change with a link to the user profile
    • Reason for the change

  2. Limit the number of Change History items displayed to an initial maximum value. Allow the user to view more until all items have been listed.

Additional options not required for certification may include the following.

  • For each Change History item, offer to restore the state of the person or relationship to an earlier state. See Change History and Person Restore in Family Tree.
  • Sort changes by date.
  • Provide a link to FamilySearch using "/#view=personChangeLog&person=[PID]" from a Person Summary or Person Detail Page where the [PID] is the FamilySearch Person ID (XXXX-XXX). This URI is subject to change. FamilySearch may be providing a more persistent entry point to the FamilySearch page that will utilize ARK links.




Read Discussions

Discussions and comments that have been created for a person in the FamilySearch Family Tree can be read. The discussion details and comments included in the discussion can be listed. The details include the description, the contributor, and the contribution date.

Assumptions

  • You have the person ID of the person whose discussions you want to read.
  • A discussion with content has been added to the target person.

Programming Steps

  1. Read a discussion.
  2. Read the discussion comments, and display the content.
  3. Repeat for remaining discussions.

User Interface Suggestions

  1. Display the descriptive information of a discussion.
  2. Show or hide the content of the discussion.




Record Hinting

After associating a person in your application with a FamilySearch Family Tree Person ID (PID), this PID can be passed to the FamilySearch Hinting API to receive a list of historical records matching the vital and relationship data of that person. FamilySearch provides a page where the user can review historical records and optionally attach them to the FamilySearch person. You can then use the FamilySearch API to retrieve the newly attached sources and any newly added persons.

Programming Steps

  1. Search for hints using the Person Match FamilySearch API resource. You must specify the collections query parameter in order to obtain hints from the hinting system.
  2. Redirect to the Possible Matches detail page on FamilySearch.
    https://familysearch.org/ark:/61903/4:1:{PID}?context=recordHints

    or

  3. Redirect to the Attach Historical Records to Family Tree page on FamilySearch.
    https://familysearch.org/ark:/61903/4:1:{PID}?context=sourceLinker&hintId={hintURI}

User Interface Suggestions

OPTION A: Redirect the User to the Possible Matches Detail Page on FamilySearch

  1. Display an option to initiate a hints request or automatically perform hints requests at predetermined points in the application.
  2. Notify the user that record hints have been found as a result of a hints request.
  3. The user requests to see the hints and is redirected to the Possible Matches detail page. A message could be displayed indicating that a FamilySearch page will be opened.

OPTION B: The Application Provides Its Own Record Hints Page

  1. Display an option to initiate a hints request or automatically perform hints requests at predetermined points in the application.
  2. Notify the user that record hints have been found as a result of a hints request.
  3. The user requests to see the hints.
  4. Create and present to the user a screen substantially similar to the following.

    The 4 or 5 star rating for each hint could also be shown.

  5. For "View all Possible Matches", direct the user to the Possible Matches detail page on FamilySearch. A message could be displayed indicating that a FamilySearch page will be opened.

    For "Review this Hint", direct the user to the Attach Historical Records to Family Tree page on FamilySearch.




Read Memory Comments

Comments on a memory can be read and displayed to the user.

Assumptions

  • The user is signed in to FamilySearch.org through the third-party application.
  • The user has selected a memory to view the comments.

Programming Steps

  1. Prompt the user to view the comments of the selected memory.
  2. Read comments on the memory. (Memory comments are also available by a link in the reply to reading a memory.)

User Interface Suggestions

  1. Display a list of memories and allow the user to select a memory.
  2. The user selects an option to display the memory comments (or cancel).
  3. Display the comments.




Read Memories Attached to a Person in FamilySearch Family Tree

Users can view a list of memories that are attached to a person in FamilySearch Family Tree. The following details of a memory can be displayed:

  • Title
  • Description
  • Contributor
  • Time stamp
  • Other metadata
  • Comments

Assumptions

  • At least one memory has been attached to the FamilySearch Family Tree person whose memories you want to view.
  • You know the person ID (PID) of the person whose memories you want to view.

Programming Steps

  1. Read the list of memories attached to a person, and display them. Optionally, read memories by type. Memory types include photos, documents, stories, and audios.
  2. Allow the user to select a memory to view.
  3. Read the memory details, and display them.

User Interface Suggestion

  1. Show a list of memories for a person in the FamilySearch Family Tree.
  2. The user selects a memory to view from the list.
  3. Display the following memory information:
    • Title.
    • A thumbnail, if available, with a link to view the memory.
    • Description.
    • An option to view the memory details.
  4. The user selects the option to view details.
  5. Identify the people referenced in the memory, and provide the option to view each person and to view comments on this memory.
  6. Finish viewing, and return to the memories list.




List Memories Personas

A person is identified in a memory by creating a persona. You can read a list of personas on a memory.

Assumptions

  • The user is signed in to FamilySearch.org through the third-party application.
  • The app has obtained the memory ID of a memory.

Programming Steps

  1. Obtain the list of personas that are tagged on the targeted memory.
  2. Display the personas.

User Interface Suggestions

  1. Display a list of memories of a person. (a list could also be done for memories created by the current user.)
  2. Allow the user to select a memory.
  3. Display the list of personas.




Read Memories Contributed by the Authenticated User

Apps can allow users to perform the following tasks:

  • View all of the memories the user created.
  • Navigate through multiple memories, and select a memory to view the details.
  • View the details of a memory, including:
    • Metadata (title, description, contributor, timestamp, and so forth).
    • Comments.

Assumptions

  • The user is authenticated as a FamilySearch user.
  • The user has previously contributed a memory.

Programming Steps

  1. Read the list of memories submitted by the current authenticated user, and display a list.
  2. Allow the user to select a memory to view.
  3. Read the memory selected by the user, and display it.

User Interface Suggestions

  1. Display a list of the user's memories.

  2. The user selects a memory from the list.

  3. Display the following information:

    • Title.
    • A thumbnail, if available.
    • Description.
    • An option that can be selected to show the memory's full details.
  4. The user selects the option to see additional information.
  5. Display the following information according to the type of memory:
    • Full picture, story, or document.
    • People in the memory.
    • Comments.
  6. The user can hide the details and exit viewing the memory.




Read Person Details and Relationships

Details can be read about a person and those who are related to that person such as spouses, parents, and children.

Assumptions

  • You must have the person ID of the person you want to view.

Programming Steps

  1. Read a person and display the information.
  2. Read spouse and display the information.
  3. Read a parent and display the information.
  4. Read child and display the information.

User Interface Suggestions

  1. Show information about the person.
    • Name
    • Person ID
    • Sources that are tagged to the vital conclusions
    • Vitals include name, gender, and dates and places of birth, christening, burial, and death.
  2. Offer the option to view relationships.
  3. Show the following information about spouses, children, parents, and siblings.
    • Name
    • Event date
    • As applicable indicate relationship type: preferred spouse, preferred parents, biological, adopted, guardianship, foster, or step.
    • Date entered, reason statement, contributor and the last modified date.
    • Sources that are attached to the relationship.




Read and Start a Pedigree from Family Tree

The app reads, links, and copies person data for multiple generations from Family Tree beginning at a designated person. Starting a pedigree is sometimes known as:

  • Starting a tree
  • Copying a tree
  • Importing a tree
  • Seeding a tree

Start with the current user or another ancestor, and add generations from that person. The user should be allowed to select the scope of the copying or accept a reasonable default.

Assumptions

  • The persons are being copied to a new third-party tree or extending a branch where there are no persons, so there is no need to check for matches or duplication between the FamilySearch tree and the third-party app tree.
  • Any person that is having generations added must previously be linked to a FamilySearch Person ID.

Programming Steps

  1. Request an ancestry for a number of generations for either the signed-in user or a selected person ID.
  2. Parse and display the person data and relationships with a chart or a tree.

User Interface Suggestions

  1. Display a choice to add generations to the signed-in user or a linked person that is lacking ancestors.
  2. Display the following parameters that can be entered to set the criteria for the download.
    • generations The number of generations being queried. Default of 4 and maximum of 8.
    • marriageDetails Yes or No selection to include the marriage details for each person that is being downloaded.
    • person The PID of the person whose ancestry is to be read. The default is the signed-in person.
    • personDetail Additional person details are downloaded for each person in the ancestry.
    • spouse This entry also provides the ancestry of the spouse.
  3. Ask the user to confirm or change the above parameters.

  4. Upon confirmation, initiate the read request, and show a progress bar or other indicator to communicate the progress and approximate time remaining.

  5. Display the results of the query in report form or a pedigree.

  6. SAVE or CANCEL the downloaded information.

See Also

../api/tree/Ancestry_resource




Read Person Portrait

Users can access a FamilySearch Family Tree person portrait by requesting the thumbnail (Portrait), multiple sizes (Portraits), or the thumbnail and an URL address with a default image returned (Portrait with Default) when there is no portrait image.

Assumptions

The user is signed into the third-party application and knows the person ID of a FamilySearch Family Tree person. The Person ID can be obtained from a previously matched and linked person or by requesting it from the user.

Programming Steps

Request one of the following:

User Interface Suggestions

  1. The person portrait image can be shown on a
    • Person Summary Page
    • Person Detail Page
    • Pedigree or another family chart page




Person Search and View

An app can allow users to:

  • Search for a person in FamilySearch Family Tree by entering parameters. This is done in order to obtain the person ID which is needed to perform tasks such as:
    • Displaying a person's information.
    • Selecting the starting person of a pedigree.
    • Attaching a source, memory, or artifact to a selected person.
  • Search the FamilySearch Family Tree for possible duplicates of a person based on selected criteria. This is done in order to merge or delete duplicates.
  • Search the FamilySearch Family Tree for possible matches of a person not yet in the Family Tree. This is done in order to associate a person in a third-party application with a person in the FamilySearch Family Tree.

Assumptions

  • The user has authenticated with FamilySearch.
  • If using the JavaScript SDK functions, you must have access to the JavaScript SDK.

Programming Steps

  1. Search by parameters to find a Family Tree person.
  2. Read a Family Tree person that you found.
  3. Search for duplicates within FamilySearch Family Tree.
  4. Search for possible matches to a person in Family Tree.

User Interface Suggestions

This shows how you could search for a person in the FamilySearch Family Tree, and check for duplicates.

  1. Enter person search parameters (name, event, relations), then SEARCH, or enter the Family Tree person ID to VIEW a person.

  2. Display the search results for review.
  3. The user selects the person that they are looking for.
  4. The user chooses to VIEW the person information, SEARCH FOR DUPLICATES, or CANCEL. NOTE: If you have an application tree person that you want to match with a Family Tree, you would search for possible matches instead of search for duplicates.

User Interface Suggestions for JavaScript SDK Apps

Note: If a FamilySearch access token has not been previously obtained at the time an SDK function is called, the SDK function will take necessary steps to obtain one in order to complete the function.

  1. Obtain the actual Family Tree Person ID.
  2. Call the getPerson SDK function.
    The person data is returned.
  3. Collect desired search parameters (name, birth date, etc.) of a person from the user.
  4. Call the getPersonSearch SDK function.
    The search results are returned.
  5. Display the search results and ask the user to select one.
    The user selects the desired person.
  6. Call the getPersonMatchesQuery SDK function.
    The search results are returned.
  7. Display the search results and ask the user to select one.
    The user selects the desired person.




Read and View Sources Contributed by the Authenticated User

Authenticated users can read sources they stored along with attribution information. Attribution if available consists of the following information.

  • Contributor
  • Last modified date
  • Reason statement

Assumptions

  • The user has previously contributed a source.
  • You know the Person ID of the person whose sources you want to read.

Programming Steps

  1. (Optional) Read the source box collection of the current user, and display the results.
  2. Read the sources attached to a person, and display them.
  3. Read source details of a source, and display them.

User Interface Suggestions

  1. Request to see the sources attached to a person.
  2. Display the list of the sources.
    The user reviews the list of sources.
  3. (Optional) Read the source box collection, and display the list of sources.
  4. The user reviews a list of sources, and selects one of the items in the source list.
  5. Read the selected source, and display the title, URL, citation (partial), and provide an option to see the full details of the citation.
  6. Allow the user to see additional information that includes the full citation, notes, and full attribution that includes last contributor, date, and reasons (if available).
  7. Allow the user to exit and return to the sources list.




Change Language

Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.