Configuration Sync

This is a feature available for v1.6.2. It allows for exporting and importing partial profiles. These partial profiles can then be used to replicate configuration changes from one system to another or to package.

Exporting partial configurations

Note that we had to make a few changes in the change logging to make this feature possible, so this may not work as well as it should for config changes made before June 2016.

There are a few options in app.conf that control what exactly gets exported. They are as follows:

• configuration_export_only_system_displays -- if set to 1, only system displays are exported
• configuration_export_only_system_search_forms -- if set to 1, only system search forms are exported
• configuration_export_exclude_lists -- list of list codes to exclude from configuration export

The defaults should work for most setups.

via command line

The export-profile utility now has an additional optional parameter -t/--timestamp that can be used to limit the export to configuration elements changed after that timestamp. The parameter should be a Unix timestamp, typically a 10 digit number. You can find out the current unix time by running

date +%s

In a terminal. You can also easily convert past dates into timestamps:

date -d"2016-01-28T10:00" +%s

Once you have your timestamp you can run the exporter like so:

support/bin/caUtils export-profile -t 1465287584

Or, if you want to redirect the output to a file ~/foo.xml:

support/bin/caUtils export-profile -t 1465287584 -o ~/foo.xml

via web service

The same functionality is also available via web service:

curl -XGET 'http://administrator:dublincore@localhost/service.php/model/exportConfig?modifiedAfter=1465287584'

Importing partial configurations

If you have a partial configuration, either created by hand or via the export tools described above, you can apply those changes to existing systems that have data in it.

These changes can, in certain cases, cause data loss or severe configuration issues. Make sure to backup your database before you do this and verify all the changes before you start entering data again!

Put your partial profile in install/profiles/xml and then run

support/bin/caUtils update-installation-profile -n <name_of_your_profile>

The script will not ask for confirmation, so make sure to backup everything before you run it!

How it works

The script will generally try to find existing records for the profile definitions (lists, list items, UIs, etc.) by idno or code and, if it will update/overwrite them. For most things it's assumed that the whole "surrounding" element is present in the partial profile, so if you want to change just a single element in a container, you will still have to put the entire container in the partial profile. For lists, you will at least have to put the entire hierarchy path for the changed item. The same goes for almost everything else. The partial configuration exporter described above will do all of this for you.

If the script can't find an existing record, it will just create a new one as if this were the initial install. That way you can add new fields, UIs, lists, etc. without disrupting anything else. Just make sure you don't reuse any identifiers (codes/idnos).

Putting it together: Automatically push/replicate configuration changes to another system

If you have multiple systems running off the same configuration you can put the two above features together to automatically push configuration changes from one master system to all other systems. This is another script in caUtils that can be used like this:

support/bin/caUtils push-config-changes -t http://yourclient/ -u configsync -p topsecret -s 1464870539

The options are:

	--targets (-t)      Comma- or semicolon separated list of target systems to push changes to. We
	                    assume the same service account exists on all of these systems

	--username (-u)     User name to use to log into the targets. We assume the same credentials
	                    can be used to log into all target systems.

	--password (-p)     Password to use to log into the targets. We assume the same credentials can
	                    be used to log into all target systems.

	--timestamp (-s)    Timestamp to use to filter the configuration changes that should be
	                    exported/pushed. Optional.

This script will utilize the partial configuration exporter and importer described above. All communication is done via HTTP web services.

Note that you should not use your administrator login to do this. It's highly recommended to create a separate user account for this and only give it access to the Model JSON service!

Also, be sure to create backups of your client/target systems before you attempt to do this!

The timestamp is only used for the very first push to that system. After that the master system will store the last push timestamp and use that instead. The -s parameter is a fixed offset/"starting point" of sorts. We assume that you set up all your systems using the same profile at some point. The starting point could be 2 seconds after that setup.

sphinx2022