|
|
| (28 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| | {{Third-party addon}} | | {{Third-party addon}} |
| − | {{man warn|Not for all versions of Gramps|Released for Gramps 5.1.x and Gramps 5.2.x. This documentation is derived from the ''[https://www.grampsweb.org/administration/sync/ Synchronize with Gramps]'' section of the '''[https://www.grampsweb.org/user-guide/ Gramps Web User Guide]'''. Their page should be considered the definitive reference.}} | + | {{man warn|Not for all versions of Gramps|Released for Gramps 5.1.x / 5.2.x and 6.0.x. This documentation is derived from the ''[https://www.grampsweb.org/administration/sync/ Synchronize with Gramps]'' section of the '''[https://www.grampsweb.org/user-guide/ Gramps Web User Guide]'''. Their page should be considered the definitive reference.}} |
| − | [[File:GrampWebSync_Intro51.png|thumb|right|450px|Gramps Web Sync]] | + | |
| | + | [[File:GrampWebSync-tool-addon-Introduction-tab-60.png|thumb|right|450px|"Introduction" tab of "Gramps Web Sync" tool]] |
| | + | The {{man label|Gramps Web Sync}} tool is an addon for Gramps that allows you to synchronize a '''Gramps (for desktops)''' database with Family Tree data on a [[Gramps Web|'''Gramps Web''' (for Servers)]], database including media files. |
| | | | |
| − | Gramps Web Sync is an addon for Gramps that allows to synchronize a '''Gramps (for desktops)''' database with Tree data on [[Gramps Web|'''Gramps Web''' (for Servers)]], including media files.
| |
| | == Purpose of this tool == | | == Purpose of this tool == |
| − | This tool was specifically written to harmonize the tree data between a "Gramps Web" instance and a "Gramps for Desktops" instance. Gramps Web is much younger than the desktop version, so not all the interface for the desired features have been created. | + | This tool was specifically written to harmonize the family tree data between a "Gramps Web" instance and a "Gramps for Desktops" instance. Gramps Web is much younger than the desktop version, so not all the interface for the desired features have been created. |
| | | | |
| − | Make no mistake, maintaining synchronization is '''''hard'''''! And this tool is not magic, it does not make the process simple but it ''is'' easier than the alternatives. | + | {{man note|Make no mistake, maintaining synchronization is {{man menu|hard}} !|And this tool is not magic, it does not make the process simple but it ''is'' easier than the alternatives.}} |
| − | <!--
| |
| − | {{man note|Important Note|This tool this requires that the Family Tree being merged must be a Gramps Family Tree ''derived from a version'' of the currently loaded Family Tree.}}
| |
| | | | |
| − | A situation occurs occasionally after giving someone a copy of your tree in our native [[Gramps XML]] format. Then each person makes changes to the copy in their possession using Gramps locally. (You can verify the Trees differ and log those revisions with the [[Addon:Database_Differences_Report|Database Differences]] addon report.)
| + | ==Gramps Web installation and account setup== |
| | + | Before you can start to use the {{man label|Gramps Web Sync}} tool addon it requires a working Gramps Web installation has been setup and also requires a Gramps Web account with owner privileges. |
| | | | |
| − | Programmers call this a 'fork.' (As in: when travelers come to a 'fork in the road' and each chooses different paths.) But the bottom line is that you now have two tree variants derived from a common Tree and you want share your updated Tree. You can't just give the person a fresh copy of your Tree because then their changes would be overwritten.
| + | The {{man label|Gramps Web Sync}} tool addon can be installed like any other addon; see {{man label|[[Third-party_Addons#Installing_Addons_in_Gramps|Installing Addons in Gramps]]}}. |
| | | | |
| − | At some point, you may want to merge the forks into a common tree... without losing the useful changes from either tree. That synchronization is what this tool is designed to facilitate. It depends on the two Trees sharing common internal handles (not just the user-editable IDs) to simplify ignoring unchanged records. Then the tool focuses you on just the changes.
| + | There are no installation (or user interface options) on the Gramps Web side because the {{man label|Gramps Web Sync}} tool communicates directly with that the Gramps Web webservice's native restful API. |
| − | | |
| − | But say the other user doesn't use Gramps, so you exported with [[Gramps_and_GEDCOM|GEDCOM]] (or another format) and got it back? Sorry... this tool won't be any easier than a manual merge after a standard import. You'd still need to hand compare every record.
| |
| − | | |
| − | The derived trees need not be limited to those edited by someone else. I often take a copy of my tree on my laptop when traveling and sometimes I make updates while on the road. But then I may forget to copy it back to my home desktop computer until after I've made more updates. This tool helps to merge these back together.
| |
| − | {{man warn|1=Warning: Data Corruption Risk |2=Mass changes mean more potential for mangling the data. Back up your current tree BEFORE using this tool to merge.<br />If something goes wrong, you will have a way to go back and start over. See [[How to make a backup|make a Gramps XML backup]].}} | |
| − | -->
| |
| − | ==Installation==
| |
| − | The addon requires a Gramps Web account with owner privileges, Gramps 5.1 running on Python 3.7 or newer.
| |
| − | | |
| − | The tool can be installed like any other version 5.1 Addon tool; see {{man label|[[Third-party_Addons#Installing_Addons_in_Gramps|Installing Addons in Gramps]]}}. Specifically, the [https://github.com/gramps-project/addons/blob/master/gramps51/download/GrampsWebSync.addon.tgz GrampsWebSync.addon.tgz] archive download is available for [[{{man version}}_Addons#Manually_installed_Addons|manual installation]] or via the [[{{man version}}_Addons#Installing_Addons_in_Gramps|'''Third party addons management''']] section of the {{man menu|Edit ➡ Preferences}} of the Gramps Desktop.
| |
| − | | |
| − | There is no installation (or user interface options) on the Gramps Web side because it communicates directly with that webservice's native restful API.
| |
| | | | |
| | ==Usage== | | ==Usage== |
| | | | |
| − | Once installed, it is run by using the {{man menu|Tools -> Family Tree Processing -> Gramps Web Sync...}}.
| + | You access the tool by using the menu {{man menu|Tools -> Family Tree Processing -> Gramps Web Sync...}}. |
| − | | |
| | | | |
| | === Running Gramps Web Sync === | | === Running Gramps Web Sync === |
| | [[File:UndoHistoryWarning-Tool-dialog-52.png|thumb|right|350px|Batch Tool warning]] <!-- https://gramps.discourse.group/t/only-some-tools-warn/4324 --> | | [[File:UndoHistoryWarning-Tool-dialog-52.png|thumb|right|350px|Batch Tool warning]] <!-- https://gramps.discourse.group/t/only-some-tools-warn/4324 --> |
| − | The tool will start with an 'Undo history warning' that suggest that you back up your work. | + | The tool will start with an '''{{man label|[[Gramps_{{man version}}_Wiki_Manual_-_Error_and_Warning_Reference#Undo_history_warning|Undo history warning]]}}''' dialog that suggest you {{man button|Stop}} and backup your work, then select {{man button|Proceed with the tool.}} |
| | {{-}} | | {{-}} |
| − | You are then presented with the Synchronization Assistant dialog will the stages of Synchronization. The first tab introduces the process.
| + | ====Introduction tab==== |
| | + | [[File:GrampWebSync-tool-addon-Introduction-tab-60.png|thumb|right|450px|"Introduction" tab of "Gramps Web Sync" tool]] |
| | | | |
| − | See the '''[https://www.grampsweb.org/user-guide/sync/ Synchronize with Gramps]''' page on the ''Gramps Web User Guide''' for further instructions.
| + | You are then presented with the ''Synchronization Assistant''s dialogs first '''Introduction''' tab that details the processes stages of Synchronization, select {{man button|Next}} to continue. |
| − | [[File:GrampWebSync_Login51.png|thumb|center|604px|Account Login Settings]]
| |
| − | <!--
| |
| − | When you have selected a file to import, the main tool window comes up and some progress meters pop up indicating the import and comparison process. When this is complete you end up with a three part window. The bottom part provides control and 'Action' buttons and a hint that changes depending on what you are doing.
| |
| | | | |
| − | ==== Control buttons ====
| + | {{-}} |
| − | | |
| − | {{man button|Help}} brings up this wiki. | |
| − | | |
| − | {{man button|Edit import}} allows editing of the selected item. Any changes are temporarily saved in your imported data, and will be kept only if that data is merged into your current tree. If your editing creates new items, they will appear in the top pane list when you finish editing. Changes here cause the 'Action' to be cleared, so be sure to choose an Action when finished.
| |
| − | | |
| − | {{man button|Unmark}} clears any current Action. If an item remains unmarked when you are done, it will be treated as if 'Ignored', that is, there will be no changes to your tree for that item.
| |
| − | | |
| − | {{man button|Ignore}} sets the action for the item so that there will be no changes to your tree for that item. This is the same as leaving the item unmarked, but makes it clear that you have looked at that item.
| |
| − | | |
| − | {{man button|Done}} tells the tool that you are finished marking the various actions. The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it.
| |
| − | | |
| − | The remaining buttons are considered 'Actions' and depend on the Status of the item.
| |
| − | | |
| − | {{man button|Add}} appears for items with an 'Added' status. When added, the imported data will be added to your current tree.
| |
| − | | |
| − | {{man button|Delete}} appears for items with a 'Missing' status. When selected, the data in your tree for this item will be deleted.
| |
| − | | |
| − | {{man button|Replace}} appears for items with a 'Different' status. When replaced, the imported data for the item will completely replace the same data in your current tree.
| |
| − | | |
| − | {{man button|Merge Original}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the original item are retained. The portions of the data that cannot be merged will remain as it is in your current tree data.
| |
| − | | |
| − | {{man button|Merge Import}} appears for items with a 'Different' status. When selected, the imported data for the item will be merged with the original tree and the IDs of the imported item are used. The portions of the data that cannot be merged will be replaced by the import data.
| |
| − |
| |
| − | When you select an 'Action' with one of the buttons, a hint will appear that states the action in more detail.
| |
| | | | |
| − | You can change the 'Action' at any time on any item, it may be instructive to see the results of choosing the various choices in the lower pane.
| + | ====Login tab==== |
| | + | [[File:GrampWebSync-tool-addon-Login-tab-60.png|thumb|right|450px|"Login" tab of "Gramps Web Sync" tool addon]] |
| | | | |
| − | In general I recommend that you start marking your items with the 'Different' items first. Within these, doing '''Families''' and '''Persons''' first will usually minimize the amount of work to merge your tree. This tool starts up with the sort set to put these items first, so starting at the top is easy.
| + | On the '''Login''' tab provide your Gramps Web credentials to be used for the Synchronization then select {{man button|Next}} to continue. |
| | | | |
| − | === Automatic Mark ===
| |
| | | | |
| − | This tool includes the ability to automatically mark those items that are 'referred to' by the item you are currently marking. For Example, if you {{man button|Add}} a person, the events, notes, media, citations and families that the person refers to will also be added. The same process is applied for each of the various 'Action' buttons.
| |
| − |
| |
| − | The marks that are automatically generated are shown in the top pane action column with a '*' preceding the action.
| |
| − |
| |
| − | Occasionally you may mark items that create a conflict in the automatic marking. For example you {{man button|Add}} a person that refers to a media, and then later {{man button|Ignore}} a person that also refers to the same media. In this case, the media item will be marked with a '?' and the action that tends to conserve more data will be used. This means that Adds have priority over Ignore, Ignore over Delete etc.
| |
| − |
| |
| − | You should review any items marked this way to make sure that you agree with the program.
| |
| − |
| |
| − | Note that families and persons in particular usually have a lot of references to other families or persons. In fact if your imported file contains a whole new branch of your family tree, selecting any one of the people or families in that branch will automatically mark all the new people and families at once. This is usually desirable, but not always.
| |
| − |
| |
| − | ==== Automatic mark with Families ====
| |
| − | This tool is not ideal for selecting only parts of a tree for merging, but it can be done. If you wish to include a person, but not his family (spouse and children) then you can uncheck the {{man label|Automark Families}} checkbox. This applies to all persons found via the Automark as well. The effect is that you can get ancestors (if {{man label|Automark Parent Families}} is checked) included but not all the descendants of those ancestors.
| |
| − |
| |
| − | If you wish to get a set of spouses and descendants included when adding a person but not all the ancestors of the spouses, then you can uncheck the {{man label|Automark Parent Families}} checkbox and leave the {{man label|Automark Families}} unchecked.
| |
| − | If you don't want any family or parent families automatically included, leave both {{man label|Automark Parent Families}} and {{man label|Automark Families}} unchecked.
| |
| − |
| |
| − | === Finishing up ===
| |
| − | When you have marked up as many items as you want and reviewed the automatic marks to make sure they are what you desire, you can press the {{man button|Done}} button.
| |
| − |
| |
| − | The tool will bring up a confirmation dialog, allowing you to save your work, cancel and return to marking, or abandon it. If you abandon, your markings are lost and no changes are made to your current tree.
| |
| − |
| |
| − | If you decide to save your work, the tool will perform a series of checks as it saves your work. These checks make sure that any conflicts that may have been created will not result in errors in your database. For example, if you selected a person to add, but decided to ignore a note attached to that person, the tool will 'clean up' the reference to the note on the person before saving it.
| |
| − |
| |
| − | == FAQ ==
| |
| − | ;Why would I want to use the {{man button|Edit import}} button?
| |
| − | : If you had an item with a difference, where both the current tree and the imported tree made changes. Because of some limitations of Gramps and this tool, you cannot choose between current and imported for every detail within an object. For these details, you can only choose to keep your current data with {{man button|Ignore}} or {{man button|Merge Original}}, or use the imported data with {{man button|Replace}} or {{man button|Merge Import}}. In either case some changes will be lost. For example, if you have edited a Person and added a Nickname, and the imported tree had edited the same person to add a LDS Ordinance, you can only keep the information for one side. In this case you might want to edit the imported person to change it to add the Nickname so that data will not be lost.
| |
| − |
| |
| − | ;Why does the import file have to be derived from the same original source?
| |
| − | : If it is not, then the matching process will not find any items that are the same or even different. Every item in the import file will end up showing as 'Added', and every item in the current tree will show as 'Missing'. You can use this tool to add in part or all of the imported data, but it is not ideal for this purpose. You would be better importing the data into a new tree, using all the Gramps views and filters to find what you do or don't want, make any deletions or edits and export to a new XML before importing that into your tree the usual way.
| |
| − |
| |
| − | ;When would it make sense to use 'Merge Original' vs 'Merge Imported'?
| |
| − | : The difference between 'Merge Original' or 'Merge Imported' is which Gramps IDs are kept as the final object. If you would like to keep your starting family tree the way you have set it up, use Merge Original. If you think that the imported tree is better, has better IDs etc, then use the Merge Imported.
| |
| − |
| |
| − | ;Why can't you use a GEDCOM file as the import source?
| |
| − | : One of the things that make this tool work is that every 'object' in the Gramps database has a unique ID called a handle (this is different than the ID shown in the GUI for each object). The tool can compare objects with matching handles relatively easily, much more easily than guessing if John Smith in your tree is the one from 1722, 1854, or 2012.
| |
| − | : At this time Gramps GEDCOM import and export has no way to save these handles to make this sort of matching possible. A few of the other family tree tools can import and export the so called '_UID' GEDCOM tag (which is not standardized) which might be usable for this, but most tools will simply discard them or modify them to be unusable. Even if these were available and not lost in translation, Gramps data model does not always match with GEDCOM data model. So a GEDCOM export/import, even without any changes made by the user, would have a lot of differences.
| |
| − |
| |
| − | -->
| |
| | {{-}} | | {{-}} |
| | | | |
| − | == Notes ==
| + | {{man warn|Beyond this it is recommended to see the current instructions|'''[https://www.grampsweb.org/user-guide/sync/ Synchronize with Gramps]''' page from the '''Gramps Web User Guide''' for further information.}} |
| − | <!--
| |
| − | If you are not sure exactly what an imported tree contains, you should use Gramps to examine it before using this tool. Import the tree into a new family tree, and look it over with the various charts (I like the relationship chart myself) to see if there are branches that you don't want. It is frequently easier to use Gramps filters or editing tools to remove items than to use the tool to exclude them, although the tool will suffice for simpler cases. Even then you should take notes on the IDs of people or families that you don't want, to make it easier to find them with this tool.
| |
| − | | |
| − | This is a new tool and fairly complex. Please report any issues or desired enhancements to paulr2787 at gmail.com
| |
| − | | |
| − | I have included a French translation of the tool, mostly as a test of the internationalization code. Since I don't speak French (USA Texas version of English only), please excuse my French.
| |
| − | -->
| |
| | | | |
| | ==See also== | | ==See also== |
| Line 130: |
Line 46: |
| | * Category search for [https://gramps.discourse.group/search?expanded=true&q=sync%20%20%23gramps-web sync] | | * Category search for [https://gramps.discourse.group/search?expanded=true&q=sync%20%20%23gramps-web sync] |
| | * [https://gramps.discourse.group/c/gramps-web/28 Category] | | * [https://gramps.discourse.group/c/gramps-web/28 Category] |
| | + | * [[Addon:Gramps_Web|Gramps Web]] |
| | <!-- | | <!-- |
| | * [[Addon:Database_Differences_Report|Database Differences Report]] - allows a mostly complete comparison between the currently opened database (Family Tree) and a Gramps XML file. | | * [[Addon:Database_Differences_Report|Database Differences Report]] - allows a mostly complete comparison between the currently opened database (Family Tree) and a Gramps XML file. |
