Admin Branches Queue

From TNG_Wiki
Jump to: navigation, search
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 pageRobin Richmond's Genealogy Database
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
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. The optional mod Inner Mod Menus displays an "Inner Mod Menu" in the TNG "inner menu" (just below the tab menu). The Inner Mod Menu is defined by this mod but is visible only if Inner Mod Menus is installed. It is also visible only to TNG administrators; never to end-users. I highly recommend that you install the Inner Mod Menus mod because Inner Mod Menus provide links to handy information - particularly to the mod settings blocks for this mod's options.
  2. This mod gathers data that can be used by the optional mod Show Mod Names, but there is no dependency on Show Mod Names
  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 Process in that it adds a tab that returns to the Secondary Processes menu if it was invoked from a Secondary Process.

Installation

In TNGv13, the mod's subfolder also contains critical files that contain the mod's language strings, which the mod does not add to standard cust_text.php files. Instead, the PHP code modified by this mod loads the language strings from files in the mod's languages/ subfolder. Read more about this technique.

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 Installation Details]

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.

Branch timestamps-before.png
Admin>>Branches>>Search After Installation of Admin Branches

See the visualizations in the Admin Branches wiki article for annotation.

Admin branches-after1.jpg
Admin>>Branches>>Search After installation of both Admin Branches and Admin Branches Queue
Branch timestamps-after1bt.jpg
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
    1. To the Wiki article (via the Wiki logo)
    2. To the section of the Wiki article describing the mod options, and
    3. Directly to the mod options themselves.
  • For Admin Branches Queue, which does not have branches, the links are
    1. To the Wiki article,
    2. 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 queue-after-innermodmenu.jpg
Admin>>Branches>>Edit After Installation of Admin Branches

See the Admin Branches Wiki article for more annotation of the two forms on this page:

  1. The upper form edits the Branch record, and
  2. The lower form (enclosed by a fieldset with the legend "Branch Action Form") executes various actions on this branch.
Admin branches queue-edit-after-admin branches.jpg
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
    1. 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:
    2. Indicates whether an action on this branch is currently in the processing queue.
    3. 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-after-both.png
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
    1. 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.
    2. The search can focus on the branch name or description, not both.
    3. Three checkboxes affect what is in the result table.
      1. 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.
      2. 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.
      3. Focus on dummy branches - A subsequent visualization will illustrate the effect of this checkbox
  • The results table
    1. 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)
    2. 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.
    3. 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.
    4. All actions other than "add" are highlighted in brown text.
    5. 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.
    6. 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
    1. 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.
    2. The Submit buttons were mostly used to test the queuing mechanism, but if an action goes awry, it may be appropriate to use them.
    3. 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.
    4. A visualization below shows how the text in the black box is replaced with the results of queued actions.
    5. 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-qactions1.jpg
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-qactions2.jpg
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-qactions3.jpg
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]
Admin branches queue-qactions4.jpg

Language Strings

This mod, like many of my newer mods, does not add strings to the standard TNG cust_text.php files. Instead, the language strings are stored in the languages subfolder of the mod's normal subfolder, in files named {language}_custtext.php (e.g. French-UTF8_custtext.php.) I'm using this nonstandard technique for several reasons, but there is a rarely-relevant downside that comes in to play only if you want to override the string value that the mod assigns to a language string. (Read about the problem and the solution.)

Revision History

Mod Version TNG Version Date Note
13.0.0.6 13.0-13.0.1 20 Nov 2020
  1. 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.
  2. The Reset button was working like a normal Reset button, not like other TNG Reset buttons.
  3. Tree column wasn't always appearing when it should
  4. Improved handling of queries when there are no branches in the database and when the specified tree has no branches
  5. 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
  1. In the Queue Actions program:
    1. Moved the buttons that check select all or clear all checkboxes to the column heading.
    2. 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.
    3. 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"
  2. Fixed a bug in admin_updatebranch.php; Would crash when a branch rule property was changed
  3. The variable $tableformat was used without being defined and was used without the dollar sign
  4. 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 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