Synchronize Configuration

Configuration changes to a running DistrictBuilder application may happen in the config.xml file, or in the http://<servername>/admin/ django admin interface. Until the feature described in #303 is implemented, manual steps must be performed to synchronize the running application configuration with the config.xml file.

The config.xml file contains all the information required to create a new instance of DistrictBuilder, and may be run multiple times with no side-effects if config.xml is synchronized with the running application configuration. The running application configuration, however, cannot write to config.xml (see issue #303 for this feature request). This results in a one-way flow of settings from the config.xml to the running application configuration.

Warning

Running the setup script on a config.xml that is not synchronized with the running application configuration may result in duplicate Geolevels, Subjects, or Score related database entries. Please use caution, and back up your database if you are unsure if your config.xml is synchronized with you running application configuration prior to running the setup management command.

Configuration via config.xml

Configuration settings saved to config.xml are always possible to propagate into a running application configuration by running the database synchorization command. To write settings from the config.xml file into the running application configuration, either of these commands will work (these commands assume that you have a configuration XML file in docs/):

python setup.py ../../docs/config.xsd ../../docs/config.xml -d

OR

./manage.py setup -c ../../docs/config.xml -d

You may always include a -v2 parameter to report verbose information to the console as the management command proceeds. Please see the docs/INSTALL file for more options to the setup management command.

Configuration via /admin

Changes to the running application configuration via the http://<servername>/admin do not always necessitate synchronization. If you are certain that you will not use any of the setup command-line commands in the future, synchronization to the config.xml file is not strictly necessary for a stable running application.

However, if you are setting up a DistrictBuilder app, you will often be running the setup command-line commands multiple times, and alternatively tweaking the running application configuration. In this use-case, it will be extremely important to migrate settings from a running application configuration into config.xml.

These XML sections relate directly to the django admin settings pages:

• LegislativeBody
• Region
• Subject
• ScoreFunction
• ScorePanel
• ScoreDisplay
• Validation/Criteria
• GeoLevel (attributes only)

These XML sections do not relate directly to django admin settings pages:

• GeoLevel/Shapefile
• GeoLevel/Files
• Templates
• Project

These sections are covered more in the Configuration wiki page.

The most important part about synchorization is ensuring that the relationships between the Scoring configuration items are consistent. These are all keyed on the XML id, so XML validation will fail if the ids do not match -- this may assist new administrators when configuring many scores at once.

Example: Add A New Subject

This section will walk you through a demonstration of uploading the subject data, and what steps should be taken to synchronize the configuration afterwards.

1. Log in to the django admin: http://<servername>/admin.

2. Click on the "+ Add" button next to "Subjects", in the "Redistricting" section.

3. Click on the "Subject template CSV" link, and wait for the empty district index file; save this file to your computer.

4. Open the saved file, and change the second column from "Subject 1" to "The Newest Subject"; save the file.

5. Back in the django admin, click on the "Continue" button.

6. Select "Browse", and select the empty district file.

7. Click on "Upload". The ingest process will take many minutes -- while on this page, the messages will reflect the processing stages.

8. When the process completes, the "Please Wait..." button will change to "Continue"; click this button.

9. The adjustable fields for the subject are displayed:

   • Name: the_newest_subject
   • Percentage denominator: (none selected)
   • Is displayed: (unchecked)
   • Sort key: 22
   • Format string: ''
   • Version: 1

10. To synchronize the config.xml with the current app at this time, open up config.xml in your favorite editor.

11. Navigate to the <Subjects> element.

12. Add a new <Subject> element that reflects the subject that was just uploaded:

13. Save the config.xml file with the new Subject element.

Note: this configuration is the minimal configuration that will synchronize with the app. This subject should be configured with some Calculators & ScoreFunctions to be really useful. If any ScoreFunctions or ScoreDisplays are created, they will need to be synchronized with the configuration as well.

Example: Check For Changes

In order to check for changes in a running application (say, where there are separate data administrators and system administrators), these steps will help you identify which Subjects have been changed.

1. Log in to the django admin: http://<servername>/admin.
2. Click on the "Subjects" item in the "Redistricting" section.
3. Open up the config.xml file in a separate screen or window.
4. Check the number of Subjects at the bottom of the table in the django admin interface. The django admin interface reports the number of each type of database object, so at the bottom of the page, there should be text similar to: 22 subjects. Record this number.
5. Check the number of <Subject> configuration elements in the config.xml file. The count of <Subject> configuration elements should match the number of <Subject> elements recorded in step #4.
6. If the number of elements from #5 do not match, adjust the config.xml accordingly. You may have to delete some <Subject> elements, or you may have to add some <Subject> elements.