How to apply configuration changes to a Production environment

We've designed Brief Connect's configuration system with both flexibility and stability in mind, particularly when it comes to managing changes across multiple environments, including your critical production environment. This guide outlines our recommended approach to ensure consistency, reliability, and empower your business administrators.

Understanding Brief Connect's Configuration Philosophy

Configuration in Brief Connect is treated as a portable object. This means that the entire set of configurations for your instance can be easily exported from one environment and imported into another. This is a deliberate design choice to support the common practice of maintaining multiple non-production environments (e.g., development, testing, staging) alongside your live production environment.

The core principle is to ensure that configuration remains consistent across these environments as much as possible, reducing unexpected behaviours and simplifying troubleshooting.

The Import/Export Process: Ensuring Consistency and Control

When you import a configuration file that has been exported from a different Brief Connect environment, the system allows for controlled updates. You can import the new configuration file, and it will be stored alongside your existing configurations. The previously active configuration file is retained. Crucially, you have the option to either make the newly imported configuration active immediately or to import it without activating it at that point. This provides a valuable safety net and control over when changes take effect.

We've implemented this approach for several key reasons:

1. Maximising Compatibility: By importing the complete configuration set, you ensure all settings are aligned, preventing conflicts or inconsistencies that could arise from partial updates.
2. Managing Interdependencies: Many elements within Brief Connect's configuration are interrelated. For instance, Organisation configurations often have dependencies with Permission settings. A complete import/export process ensures these relationships remain intact and functional, avoiding issues that could occur if configuration elements were applied in a piecemeal fashion.
3. Version Control and Rollback: Retaining previous configurations allows for easier review and, if necessary, a quicker rollback to a known good state.

Recommended Workflow for Configuration Changes

While we strongly encourage business administrators to be actively involved in tailoring the Brief Connect configuration to meet their specific organisational needs, it's crucial to align these activities with a structured environment management process.

Our recommended workflow is as follows:

1. Originate Changes in Upstream Non-Production Environments: All configuration modifications should begin in your most upstream non-production environment (e.g., your 'development' or 'test' environment). This is where business admins can safely experiment, define, and refine settings using the admin panel.

2. Promote Configuration Downstream via Export/Import: Once changes are finalised and validated in an upstream environment, the configuration should be exported from that environment and then imported into the next environment in your pipeline (e.g., from 'development' to 'test', and then from 'test' to 'production').

3. Utilise the Export/Import Feature Exclusively for Promotion: We strongly recommend using the built-in export/import configuration feature exclusively for transferring configurations downstream. Avoid manually replicating changes in downstream environments (including production) via the admin panel.

4. Why not manually replicate changes?

   • Risk of Human Error: Manually inputting changes across multiple environments significantly increases the likelihood of errors, omissions, or inconsistencies. A small typo or a forgotten setting can lead to unexpected behaviour in production.
   • Ensuring Identical Configuration: The export/import feature guarantees that the exact configuration tested and approved in a non-production environment is the one deployed to production. This eliminates discrepancies.
   • Efficiency and Speed: Exporting and importing a configuration file is significantly faster and less labour-intensive than manually recreating numerous settings.
   • Auditability: Using the export/import mechanism provides a clearer audit trail of when and what configurations were applied.

5. Empower Business Administrators: Business users can and should be empowered to perform these export and import operations, provided they have the necessary access permissions and it aligns with your internal governance policies. To facilitate this, ensure your business administrators have appropriate access to all relevant upstream (non-production) environments.

Streamlining Configuration Imports into Production

To support this structured approach, we advocate that configuration imports into your production environment be treated as an allowed and streamlined process. These configuration deployments should generally not require the same level of extensive Change Advisory Board (CAB) approvals as feature updates or underlying code changes. They are, in essence, the promotion of already tested and validated settings options.

We strongly recommend however testing configuration changes extensively before pushing to production. It's also critical that the configuration changes are tested on a non-production environment that closely replicates the production instance - specifically, the application version (often called the "Staging" environment). This ensures tht configuration changes are compatible with the version of Brief Connect deployed to production and there are no breaking changes.