GuidesAPI ReferenceChangelogHelp
Guides

Change History

Suggest Edits

The FamilySearch API provides a Change History resource for the Person, Couple Relationship, Child-and-Parents Relationship Change History and Tree resources.

The change history for a resource allows a view of the changes that are made to a resource by users over time. Changes are logged when adding, editing, or deleting. A change entry includes.

  • A way to identify the type of change using the subject, predicate and modifier
  • A reference to the contributor of the change.
  • A reason for the change that was provided by the contributor.
  • A timestamp for when the change occurred.
  • An old (or "original") value. In the case of a creation of a new value, however, no original value exists.
  • A new (or "resulting") value. In case of a deletion of a value, however, there is no resulting value.
  • A deleted (or "removed") value. In case of a creation of a new value or an update of an existing value, however, there is no removed value.

The Atom Feed

An Atom Feed is used to provide the set of changes for a resource. Each change is provided as an entry in the feed, which natively provides a timestamp. The contributor is provided as the author of the entry. The type of change is provided as the title of the change. If the change is an edit, the expected content will be the original and resulting values. If the change is a delete, the expected content will be the removed value. If it's an add, merge or undelete, only the resulting value will be returned.

You may determine that a previous value in a change is the correct value and you want to restore the original value. When a change is restored, its values are reapplied and a new entry is added. The original change will still be in the change history. If an entry does not contain a restore link, the change is not able to be restored.

Each entry provides a custom ChangeInfo element that provides the reason for the change that the contributor gives, as well as identifiers for the original, resulting, and removed values, if applicable. The values themselves are provided in the content of the entry.

A "parent" change, such as a merge of two persons, causes cascading changes to happen. If a change has a parent, then the change ID of the parent change is provided in the ChangeInfo element.

Change Types

The type of change can be identified using the objectType, operation and objectModifier attributes. The objectType identifies the type of object to which the operation applies, such as a birth. The operation is the action that was taken on the change, such as create, edit or delete. The objectModifier is optional and describes whether the change happened on a person or a relationship.

View an example of a person change history request.

Interacting with a CET Tree Change History

You can retrieve a page of changes for a CET Tree by making a GET request the CET Change History endpoint. This endpoint supports two different query parameters to control the paging.

  • from
    The from parameter is a page token to indicate where in the tree change history to begin returning change history results.
    A response from a request to the Tree Change History that contains a next link, indicates that more changes are available. The next link includes the from parameter to be used to get the next page of changes.
  • timestamp
    The timestamp parameter is a page token to indicate where in the tree change history to begin returning change history results. Results with a timestamp equal to or greater than the timestamp are returned. The timestamp must be a UNIX timestamp in GMT.

Note that while both the from and timestamp parameters can be passed to the Tree Change History endpoint, from takes precedence over timestamp. If neither parameter is passed to the endpoint, the first page of changes from the tree change history will be returned (which normally are changes from the initial data loaded into the tree by the application).

Sub-Changes

Some changes returned by the Tree Change History endpoint consist of a “parent” change followed by associated sub-changes. The parent change, combined with the associated sub-changes are considered a single change.

For example, a Person Created change (the “parent” change) contains just the id of the newly created person. It is followed by one or more associated sub-changes, such as Gender Added, Birth Name Added, Burial Added, etc.

Each change has a changeInfo object which contains a parentobject, which contains a resourceId field. The “parent” change and associated sub-changes are linked together in the feed by setting the changeInfo -> parent ->resourceId field in the sub-changes to the value of the id field in the parent change. When a change is encountered in the feed without a parent field or a parent field without a resourceId field in the changeInfo object, or the last change in the feed is encountered, the parent change is complete. All sub-changes associated with a parent change will be in a single page. Sub-changes do not cross page boundaries.

Tracking Tree Change History over the lifecycle of a CET

It is essential to properly track and manage the timestamp and/or from query parameter values to ensure changes aren't lost between requests to the CET Change History endpoint.

Once the CET is provisioned with all the data from the tree in your application, save the current timestamp. Without that timestamp to pass to the CET Change History endpoint, the change history results for the data provisioned by the application will be returned. By providing the timestamp saved when data provisioning is complete, those changes will not be returned and the application can focus on processing changes made via FamilySearch to the CET.

For requests to the CET Change History Endpoint that take place after the first request, the from parameter should be used.

Choreography to track changes over the lifecycle of the tree

Tree Upload steps:

  1. Create the CET
  2. Load the data into the CET
  3. Save the current timestamp

First request to the CET Change History endpoint after initial data load:

  1. Request first page of changes using the timestamp saved after the initial data load
  2. Process the changes
  3. While the response has a next link
    1. Request the next page of changes using the next link
    2. Process the changes
  4. Save off the from parameter to use the next time a request is made to the CET Change History endpoint
    1. To do this, you will need to get the id field from the last result.
    2. Truncate all characters in that field starting at the first underscore in the field
    3. Save the resulting value to be used as the from query parameter for the next request to the CET Change History endpoint
    4. Example:id from last result = 3ab071e0-0743-11ef-a151-79be1178d374_0_0 - from parameter to save = 3ab071e0-0743-11ef-a151-79be1178d374

Subsequent requests to the CET Change History endpoint:
Follow the steps above for subsequent requests to the CET Change History endpoint but use the saved from query parameter for the first request rather than a timestamp saved after the initial data load.

Updated about 2 months ago