Managing Complicated Configuration Files

Having a single, monolithic configuration file for AMPS is great for simple environments, but as an instance grows to include multiple teams or applications it's often desirable to partition the config into individual components with different maintainers.

[Edit: This article discusses how to manage complicated configuration files in versions of AMPS prior to 5.2.  In 5.2.0.0 and later versions, the AMPS configuration component itself offers an easy-to-use mechanism for including external configuration snippets.]

For example, let's say you have two teams, 'a' and 'b', that want to maintain their own SOW topics.  You could have a single configuration file, but one team could easily alter the other's topic configuration in undesirable ways (accidents happen!)  Ideally, you'd have a team-a-topics.xml and a team-b-topics.xml that could be maintained by their respective teams and included into the larger configuration file.

You can do that using inline DTD entity references, like this:

<?xml version="1.0" ?>
<!DOCTYPE AMPSConfig [
<!ENTITY team-a-topics SYSTEM "team-a-topics.xml" >
<!ENTITY team-b-topics SYSTEM "team-b-topics.xml" >
]>

...

     <TopicMetaData>
         &team-a-topics;
         &team-b-topics;
     </TopicMetaData>

This tells AMPS's config parser to replace the entity reference "&team-a-topics;" with the file "team-a-topics.xml".  The file includes just the raw XML segment you want included -- don't put the version header ("<?xml version="1.0" ?>") at the top of the snippet you're including.

Want even more power?  Let's say you want to control some functionality based on environment variables.  You might have some administrator Actions defined in a file that you want to optionally control if they're included or not.  Putting a full XML Actions config in an environment isn't a great solution, but choosing which snippet file to include using the environment variable works great.

You'd start off with a file actions-config-yes.xml which contains your Action block (or any other configuration segment you want optionally included.  Then, you'd create an empty file called something like actions-config-no.xml.

Then, you would define a inline DTD reference as we did above, like so:

<?xml version="1.0" ?>
<!DOCTYPE xml [
<!ENTITY action-config SYSTEM "actions-config-${INCLUDE_ACTIONS}.xml" >
]>

Then, when you're starting AMPS, you just define the INCLUDE_ACTIONS environment variable to "yes" or "no".  Easy!

INCLUDE_ACTIONS=yes  ./ampServer config.xml

This article shows you how to use inline DTD entity references and environment variables to take complete control over how your AMPS configuration/environment is assembled.