[Rt-commit] rt branch 5.0/docs-dump-initialdata-move-config created. rt-5.0.2-71-g993e0f3413

[BPS Git Server]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "rt".

The branch, 5.0/docs-dump-initialdata-move-config has been created
        at  993e0f34132dde14432675f7058a4d3ba65b8e47 (commit)

- Log -----------------------------------------------------------------
commit 993e0f34132dde14432675f7058a4d3ba65b8e47
Author: Jason Crome <jcrome at bestpractical.com>
Date:   Thu Feb 17 09:31:01 2022 -0500

    Document steps to generate initialdata changes file
    
    rt-dump-initialdata has a way to generate JSON initialdata files containing
    a set of changes made in the RT database. It requires running a set
    of commands, so document all of the steps in the process.

diff --git a/docs/initialdata.pod b/docs/initialdata.pod
index def6dc0ab3..809199aacd 100644
--- a/docs/initialdata.pod
+++ b/docs/initialdata.pod
@@ -481,10 +481,10 @@ Here is an example of using a subroutine reference as a value for Object:
         Object      => sub {
             my $GroupName = 'SomeQueue Group';
             my $group     = RT::Group->new( RT->SystemUser );
-    
+
             my( $ret, $msg ) = $group->LoadUserDefinedGroup( $GroupName );
             die $msg unless $ret;
-    
+
             return $group;
         },
         Content     => {
@@ -586,4 +586,82 @@ No C<Final> elements will be used.
 
 =back
 
+=head1 Automatically Generating Initialdata to Migrate Changes
+
+If you have RT instances running in multiple environments like dev,
+test, and production, you may want to pilot new configuration in dev,
+then move that configuration to production once it is validated.
+RT provides tooling to help export just new configuration changes as
+Initialdata and then load it into other environments.
+
+Note that for systems with very large databases, the generated initialdata
+files can be extremely large. With such systems, the process described below
+can take much longer and require more resources than on a typical RT system.
+
+=head2 Validate Your Starting Data
+
+It is good practice to run the L<rt-validator> tool to identify and resolve any
+errors in the RT database before starting:
+
+    /opt/rt5/sbin/rt-validator --check
+    /opt/rt5/sbin/rt-validator --resolve # If necessary
+
+=head2 Create a Baseline Checkpoint
+
+You can then create an initial export of your current configuration
+using the L<rt-dump-initialdata> utility. The generated Initialdata
+file will contain all of your current configuration, but no ticket,
+asset, or article data.
+
+    /opt/rt5/sbin/rt-dump-initialdata --sync
+
+When finished, you'll have a directory and file in the format F<yoursite.com:YYYY-MM-DD/initialdata.json>.
+
+=head2 Make Configuration Changes
+
+Make changes to your RT configuration through the web interface. You
+might add a new queue, create a new group, and add rights for that
+group on your new queue. All of these will be saved in the dev system
+database as you work.
+
+=head2 Export Changes as Initialdata
+
+When you've completed the changes you want to migrate to another RT,
+re-run L<rt-dump-initialdata>, providing the first export file as an
+argument.
+
+    /opt/rt5/sbin/rt-dump-initialdata --sync --directory changes/ \
+        --base yoursite.com:YYYY-MM-DD/initialdata.json
+
+A new output directory must be provided if you are making a diff file on the
+same day as the original configuration dump file was produced.
+
+You will now have a new directory, F<changes/>, with two files.
+F<initialdata.json> is the full dump of configuration data, and F<changes.json>
+has only that data which changed since the original dump. The initialdata file
+is JSON, so you can view it with a regular text editor. Before migrating changes
+to the target RT instance, you can review the contents. You can even edit the
+file directly if you need to add or remove some data.
+
+=head2 Importing Data
+
+By default, RT is not configured to import JSON data. The JSON format handler needs
+to be enabled before the change file produced in the prior step can be imported.
+See L<etc/RT_Config.pm#l#InitialdataFormatHandlers> for details on enabling the
+JSON format.
+
+Copy F<changes.json> to your target server and run the following:
+
+    /opt/rt5/rt-setup-database --action insert \
+        --datafile path/to/changes.json
+
+The new configurations you made in development will now be available in your
+new environment.
+
+It is recommended that you make a database backup of your target RT before
+importing configuration changes. See L<docs/system_administration/database>
+for more information.
+
+=back
+
 =cut

-----------------------------------------------------------------------


hooks/post-receive
-- 
rt