Admin Branches Queue

Admin Branches Queue
Summary	Implements a queuing mechanism that can perform batch execution of multiple branch label operations.
Validation
Mod Updated	17 Nov 2020
Download link	v13.0.0.6.zip TNG 13.0 v12.0.0.2a.zip TNG 12.0 See older versions in the Revision History
Download stats
Author(s)	Robin Richmond
Homepage	this page
Mod Support	My Mod Support form or TNG Community Forums
Contact Developer	My Mod Support form
Latest Mod	13.0.0.6
Min TNG V	11.0
Max TNG V	13.0.1
Files modified	ajx_labels.php, admin_branches.php, admin_editbranch.php, admin_updatebranch.php, English cust_text.php. Installs: rrbranchesqueue_dbsetup.php, rrbranchesqueue_status.php, rrbranchesqueue_ajx.php, rrbranchesqueue_dequeue.php, rrbranchesqueue.php, rrbranchesqueue_restore_ajx.php
Related Mods	Admin Branches (required), Add Name to PersonID, Admin Secondary Processes, Inner Mod Menus
Notes

Purpose of the Mod

To make it easier to rebuild (relabel) multiple branches from their branch rules, and to know whether branches have been or need to be rebuilt. This mod

• Installs database fields and AJAX programs that mark Branch operations with timestamps in the TNG Branches table, so that administrators can know when or whether a Branch has been updated or cleared.

1. Implements a simple queuing mechanism that allows site administrators to queue tasks that Add (aka Rebuild) or Clear branch labels. This queuing mechanism is of particular importance on large sites, where Branch operations take a long time.
2. Modifies the Admin>>Branches>>Search results screen to show the status of each branch.
3. Adds queuing options to the Admin>>Branches editor.
4. Installs a Branch Queuing application from which an administrator can directly run some Branch operations, and can queue Branch operations to run in the background.
   • This program is similar to the Admin>>Branches>>Search program, and is launched from a tab labeled "Queue Actions"
5. Provides a way for branches to be rebuilt accurately after a Gedcom Import.
   • The issue here is that the native Gedcom Import Secondary Process to "Relabel Branches" uses the old branch index (the branchlinks table), but the Gedcom Import can change who belongs in a branch, and thus make the branch index obsolete.
   • Thus, this mod simplifies and optimizes the process of running complete branch label rebuilds, using the branch rules (e.g. ancestor generations, descendant generations, etc.)

Mod Options

none

Compatibility

This mod is compatible with Add Name to PersonID, Tree ID Mod, and TreeID-One Column, and depends on Admin Branches. Is is not compatible with Branches Sort mod because Admin Branches has a direct conflict. But the goal of Branches Sort mod, to sort related branches together in the Admin Branches Search results table, is only achieved if the related branches use the common BranchID at the very beginning of their BranchIDs. The Queue Actions program supplied by this mod can focus on all of related branches.

Related Mods

1. An Inner Mod Menu, which provides handy links from TNG pages directly to mod documentation and a mod's Mods Settings Block. (Inner Mod Menus are visible only to TNG Admins; never to end users.)
2. The Mods Used feature, which captures a list of mods that affected the code used to display a TNG page. (This is analogous to the Mod Manager Analyzer feature that reports which mods affect a given TNG file, but that applies at run-time.
3. This mod is dependent on Admin Branches, which also adds columns to the Admin>>Branches results table, and adds options to the Branch Editor.
4. This mod coordinates with Add Name to PersonID and Admin Branches because they all want to make changes to the main SQL query. The three mods share a flag that allows just one of the mods to make all of the SQL changes that all three mods need.
5. This mod coordinates with Admin Secondary Processes in that it adds a tab that returns to the Secondary Processes menu if it was invoked from a Secondary Process.

Installation

This mod's language strings are defined, distributed and files in its mod subfolder rather than in its .cfg file. TNG programs affected by this mod then load language strings from those mod subfolder files rather than from cust_text.php files. This non-standard technique for handling language strings has several advantages, including that

1. It loads language strings only into the pages that need them rather than into all TNG pages, and
2. It simplifies the process of defining and editing translations.

This non-standard technique should be invisible to you unless you want to define a translation or override any of this mod's string values.
Read more about this technique, the simplified translation process, and the procedure for defining site-specific overrides to its language strings.

Files Installed

1. rrbranchesqueue_dbsetup.php - A script that sets up the new database fields that track queuing. It is launched from the mod description block within the Mod Manager List.
2. rrbranchesqueue.php - The queuing app launched from the new "Queue Actions" tab. It lists selected branches and allows the user to enqueue jobs that rebuild (i.e. label) or clear the labels from multiple branches.
3. rrbranchesqueue_ajx.php - An AJAX program to queue a list of branches for processing. Invoked by rrbranchesqueue.php.
4. rrbranchesqueue_dequeue.php - An action script called by admin_editbranch.php to remove a job from an action queue. Invoked from admin_branchedit.php.
5. rrbranchesqueue_status.php - An AJAX program that checks the status of the queued branch tasks. Invoked from admin_branches.php and rrbranchesenqueue.php
6. rrbranchesqueue_restore_ajx.php - An AJAX program to relabel one branch by copying the branch index; similar to the secondary process that relabels all branches.

[Show Standard Installation Process]

Requirements

• A working TNG installation.
• An installed current version of the Mod Manager.
• You should backup files listed in the panel on the right.

Procedure

1. Remove and delete previous version of this mod.
2. Backup the files updated by this mod. They are listed in the panel at the upper right.
3. Download the .zip file, Extract its .cfg file to the mods folder.
4. Follow the normal automated installation for Mod Manager, as shown in the example Mod Manager - Installing Config Files.

Problems?

1. Try using the Mod Manager Remove capability
2. Contact me through My Mod Support form.

[Hide Details]

Visualizations

Admin>>Branches>>Search Before installation of either Admin Branches or Admin Branches Queue The buttons at the bottom of this form generate cascading pop-up forms that I find confusing. The Admin Branches mod changes that workflow so that more actions can be taken without popups.

Admin>>Branches>>Search After Installation of Admin Branches See the visualizations in the Admin Branches wiki article for annotation.

Admin>>Branches>>Search After installation of both Admin Branches and Admin Branches Queue

Admin>>Branches>>Search The Inner Mod Menu Both Admin Branches and Admin Branches Queue generate Inner Mod Menus in the Admin>>Branches search form, and in Admin>>Branches>>Edit. The two menus are consolidated in one menu as shown here. For Admin Branches, which has mod options, the links are To the Wiki article (via the Wiki logo) To the section of the Wiki article describing the mod options, and Directly to the mod options themselves. For Admin Branches Queue, which does not have branches, the links are To the Wiki article, To a section of the Wiki article that says what has changed in Admin>>Branches In Admin>>Branches>>Edit, the only difference is that the last link for Admin Branches Queue goes to a section of the Wiki article that describes the changes made to that program.

Admin>>Branches>>Edit After Installation of Admin Branches See the Admin Branches Wiki article for more annotation of the two forms on this page: The upper form edits the Branch record, and The lower form (enclosed by a fieldset with the legend "Branch Action Form") executes various actions on this branch.

Admin>>Branches>>Edit After both mods have been installed. The Branch Edit page has three HTML forms, each of which is surrounded by a fieldset. The first form is largely intact from the native program. The third form is from the Admin Branches mod. Admin Branches Queue creates the "Form for Action Results and Queue Manipulation", which is outlined in orange in the screenshot. This form Show the results of the the most recent branch action - whether it was queued or was executed by clicking on the buttons in the "Branch Action Form" below. The middle form: Indicates whether an action on this branch is currently in the processing queue. Has a button that removes the current action from the queue. This button is visible only if there is a job in the queue.

Admin>>Branches>>Queue Actions Page After installation of both mods This page is similar to the Branch Search page in that it lists all of the branches that match a search, and lets you select or clear checkboxes for each branch. But unlike the Branch Search Page The Search form The tree selection box shows the last Gedcom Import date for each tree. That date is important to both the program and the user in deciding whether a branch needs to be rebuilt. The search can focus on the branch name or description, not both. Three checkboxes affect what is in the result table. Count labels in each branch - As with the branch record counts that Admin Branches added to the Admin>>Branches>>Search results, by default, the records are not counted, because counting can take too long on a very large database. Instead, a simply Y or N is displayed by default. Show branch-restricted users - This is represented by the very last column of the results. This screen shot was generate from a test database, so most of the branches have no users. In another environment, displaying this column might make sense only if the search string focused on one or two branches. Still, it is important to realize that not all branches will necessarily have users. Some branches, such as "Contacts", "Ancestors", and perhaps "Hazlet" (which contains ancestors only) are defined simply to identify sets of people in the tree, and are not intended for users. Focus on dummy branches - A subsequent visualization will illustrate the effect of this checkbox The results table In the checkbox column, the "Contacts" and "hk" columns do not have checkboxes because they do not have branch rules (i.e. ancestor or descendant generations values) The branch 'hk' is a true 'dummy branch', as it is a substring of 'hk-hutch' and 'hk-kuyk' (two closely related families that intermarried). As with most dummy branches The Actual record count is the union of it constituent branches, which overlap, hence the record counts are not the sum of the constituent branch record counts. There are no records in the index, thus the counts are highlighted in red. But, in this case, the difference between the records counts and the index counts are normal, so the highlighting is essentially extraneous. The branch has never had an action performed on it, since its whole purpose is to reflect the actions of its constituent branches. In the branch "Durbahn", the last action was "clear", hence the record and index counts are zero. The counts in the People/Families column are non-zero; they reflect the number of records that were cleared. All actions other than "add" are highlighted in brown text. The "Clear" action could have been launched from the Branch Edit page, or from this page. There is no way to know. The same is true for all "add" actions. The Queued Actions columns is blank because there are no actions in the queue at the moment. See a visualization below. Actions and Results of Actions The "Immediate Action" buttons use Ajax to enqueue add or clear actions for checked buttons. The results of queued actions are shown in the black box near the bottom of the screen, but are not reflected in the results table until the page is reloaded. See a visualization below. The Submit buttons were mostly used to test the queuing mechanism, but if an action goes awry, it may be appropriate to use them. This page does not have a way to remove a queued action, though it should. To remove an action from the queue, you must go to the Branch Edit page for the branch whose action you want to remove from the queue. A visualization below shows how the text in the black box is replaced with the results of queued actions. Reflecting the use of this page as a testing ground for the queuing mechanism, there are several notes at the bottom of the page. These notes could and may be in this Wiki article, as well.

Admin>>Branches>>Queue Actions Page Reflecting some queued actions This screen clip was generated by refreshing the page quickly after actions were queued by the "Queue to add labels" button. Note that the "hk-hutch" branch is being processed, and the "hk-huyk" and "Marwil" branches are queued up to be processed next.

Admin>>Branches>>Queue Actions Page After queued actions have completed. The results of a set of queued actions appears in the black box below the results table. It is important to realize that if you were to refresh the page to reveal the queued actions, as reflected by the screen clip just above, this result message will not appear. To see the results of queued actions in the black box, you must wait until all of the queued tasks have been completed. But you are certainly not required to wait. You can move on to other tasks. Also importantly, since the Immediate Action buttons show results in the black box, but do not refresh the page, the the results table still reflects the search results from before the actions were queued, and shows the checked boxes for the branches that were queued.

Admin>>Branches>>Queue Actions Page Showing a 'dummy branches' search (This screen clip comes from a different database than the previous ones.) The results show each (in this case, two) dummy branch and their constituent branches]

Language Strings

As noted above, this mod's language strings are defined, distributed and files in its mod subfolder rather than in its .cfg file. TNG programs affected by this mod then load language strings from those mod subfolder files rather than from cust_text.php files. This non-standard technique for handling language strings has several advantages, including that

1. It loads language strings only into the pages that need them rather than into all TNG pages, and
2. It simplifies the process of defining and editing translations.

This non-standard technique should be invisible to you unless you want to define a translation or override any of this mod's string values.
Read more about this technique, the simplified translation process, and the procedure for defining site-specific overrides to its language strings.

Revision History

Mod Version	TNG Version	Date	Note
13.0.0.6	13.0-13.0.1	20 Nov 2020	Coordinates with the new Admin Secondary Processes Mod by adding a "Return to Secondary Processes" tab if it was invoked by a Secondary Process button. The Reset button was working like a normal Reset button, not like other TNG Reset buttons. Tree column wasn't always appearing when it should Improved handling of queries when there are no branches in the database and when the specified tree has no branches See the .cfg file's Revision History for other changes
13.0.0.5	13.0	2 Aug 2020	Upgraded to TNGv13, with just a few straightforward code changes Set the version number to 5 to coordinate with Admin Branches, on which this mod depends. To coordinate among Add Name to PersonID, Admin Branches and Admin Branches Queue over the main SQL query in admin_branches.php, all three mods use a shared flag to determine which one will output the entire query with all tables and fields that they all need.
12.0.0.2a	12.0+	21 Mar 2020	In the Queue Actions program: Moved the buttons that check select all or clear all checkboxes to the column heading. Added a checkbox that tells the "Queue to Clear Labels" action to clear "all" of the branch's labels by scanning the entire People and Families tables. When the box is not checked, the Clear operation uses the branch rule. The earch results now use the "Count Branch Labels" mod option (defined by the Admin Branches mod) to determine whether to (initially) display label counts vs the flag that indicates simply that "there are labels" Fixed a bug in admin_updatebranch.php; Would crash when a branch rule property was changed The variable $tableformat was used without being defined and was used without the dollar sign Put a nowrap span around 'T-[days}" in date fields and omitted time of day if the date is more than 7 days ago.
12.0.0.2	12.0+	3 Jan 2020	Renamed to Admin Branches Queue Renamed the mod & files installed by this mod to have the common prefix rrbranchesqueue Removed most of the testing activity from the "Timestamps Test App", and changed its name. In what is now the "Queue Actions" page: Changed several of the notes and labels. (Many of them are not translated) Added the ability to select or unselect all branches "All branches" excludes branches without a labeling rule (i.e. no ancestor or descendant count) Branches without a labeling rule and 'with' records in the branch index (the branchlinks table) have a "Restore Branch" button that copies the index to People and Families records, like the Relabel Branches secondary process. Added an Ajax program to restore one branch from its index.
Branch Timestamps v12.0.0.1	12.0+	15 May 2018	No functional changes; made compatible with TNGv12.
Branch Timestamps v11.0.0.1	11.0-11.1.2	5 Mar 2018	No functional changes - Removed the second line from the cust_text.php target location search string, and replaced a message with a translation string.
Branch Timestamps v11.0.0.0a	11.0-11.1.2	31 May 2017	New mod. Beta status

Sites using this mod

If you download and install this mod, please add your TNG site to the table below:

URL	User	Note	Mod-Version	TNG-Version	User-language
Robin Richmond's Genealogy Database	Robin Richmond	Mod developer	13.0.0.6	13.0.1	English
racine d'Alsace	J-Louis Valory	Pubic/Privat - Template 1	11.0.0.0a	11.1.1	French
The Cole / Tanner Family Tree	David Cole	Public/Private	see here	see here	EN, DE, FR, ES, NL