Admin Branches Queue

From TNG_Wiki
Revision as of 20:16, 3 January 2020 by Robinrichm (talk | contribs)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

(formerly Branch Timestamps)

Admin Branches Queue
Summary Implements a queuing mechanism that can perform branch label operations for multiple branches in a batch that processes each branch in sequence. New database fields are used to record the time and action of latest 'add labels', 'clear labels', 'delete records', or 'edit' operation performed on each branch, whether the action is launched through a queue or 'manually' in admin_editoptions.php.
Validation
Mod Updated 3 Jan 2020
Download link v12.0.0.2.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 12.0.0.2
Min TNG V 11.0
Max TNG V 12.2
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)
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. This mod is dependent on Admin Branches, which also adds columns to the Admin>>Branches results table, and adds options to the Branch Editor.
  2. The optional Show Mod Names mod will use data saved by Admin Branches Queue to to display information about the mods that affect admin_branches.php and admin_branchedit.php if and only if Show Mod Names is installed.

Installation

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.

Admin Branches Queue uses, but is not packaged with, and does not install the shared Include file that supports Inner Mod Menus. Admin Branches Queue can get by without installing that module because Admin Branches Queue is dependent on Admin Branches, which is distributed with the Inner Mod Menu module, and can install it.

Admin Branches Queue uses the normal installation process.
[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 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.
    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 user.
      • 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 (and the buttons just above it) represent a second form, just like in all of the search pages for other database objects.
  • In the checkbox column, the "Contacts" and "hk" columns do not have checkboxes because they do not have branch rules (Ancestor generations 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 constiuent branches.
  • The branch 'Contacts' is not a true dummy branch, though it has no branch rule. Its counts are the result of specific edits to specific records.
    • The "Restore Branch" button is essentially the same as the "Relabel Branches" secondary procedure, though, of course, it applies to just one branch.
    • The "Restore Branch" button would be useful after a Gedcom Import, when the Record counts would be zero.
  • In the branch "coffman1", the last action was "clear", hence the record and index counts are zero. The People/Families counts 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 column is blank because there are no actions in the queue at the moment. See a visualization below.
  • 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-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

Revision History

Mod Version TNG Version Date Note
12.0.0.2 12.0+ 3 Jan 2019
  • 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 12.0.0.1 12.2 English
racine d'Alsace J-Louis Valory Pubic/Privat - Template 1 11.0.0.0a 11.1.1 French