In my last projects I faced different challenges in the area of how to manage environment-specific artefact configurations that need to be adjusted during rollout of a particular service component. As a result from that, I decided to write down my experiences and solution approaches regarding the corresponding topics. This article is the starting point for a short blog series dealing with different challenges in this area, where the following topics will be covered:

  • General: Using configuration files for customizing service deployments
  • Adjust environment-specific configurations at deployment time
  • Evaluating environment-specific configurations at runtime
  • Security: Approaches for credentials management

Configuration files in Servicebus

During its lifecycle a specific service component needs to pass different quality gates to ensure quality, correctness and stability before it will be approved for production rollout. For that reason deployments to different environments have to be done. This usually means changes in configurations like service endpoints or timeout parameters, which must be possible without changing a components implementation and rebuilding the component. In Oracle Servicebus this can be achieved by using so called configuration files (aka customization files in OSB 11g). With those it is possible to consistently change service properties and configurations for implementation artefacts like proxy services, service pipelines and business services. Within a configuration file you define actions like replace or search and replace to adjust the corresponding configurations.

Generating a basic configuration file can be done using Servicebus console.


As it can be seen in the screenshot above the services that should be adjusted by the configuration file can be selected. Doing so, a file is generated containing replace rules for all configurations that are adjustable.

One thing to notice, when working with Servicebus configuration files is that actions, which are used to replace parameters may throw errors at deployment time, if services are referenced explicitly by name and the referenced services are:

  • not part of the current deployment,
  • already deployed on the server yet.

Approaches for using configuration files

Depending on the requirements, it can be chosen between a local and a global approach while working with configuration files. The main differences regarding these approaches is the level of granularity in which adjustments are possible, the way the configuration file is defined and the way how configuration files are organized.

Central configuration management using property files

A common detail for both approaches: The configuration file is used in a template style, where specific configurations are expressed as properties, like hostnames or ports.The values for the properties are defined in environment-specific property files. At deployment time, the property file for the target environment is used for replacing the corresponding properties in the configuration file template. This can for example be done by using the maven replacer plugin. Using that approach ensures that only one configuration file needs to be maintained, instead of one per environment.

A property file may look like the following:


Local configuration file approach

A local approach demands an explicit configuration file per Servicebus project. So in case a new service is implemented, a new configuration file needs to be created, which should be explicitly used for this service. In addition the central property files have to be adjusted to contain the newly created properties.

Because every project has its own configuration file, the approach is very powerful regarding the granularity of how configuration parameter replacements can be defined, as the replacements are clearly related to a specific service. One difficulty of this approach is that an explicit configuration file needs to be maintained per service, which can become a bit messy.

In the following an example for a fine grained, service-specific action is shown:


 Service URI

 Service URI Table

 Service Retry Count

Global configuration file approach

Using a global approach, only one central configuration fileis needed, which defines the replacements for all services. So if a new service is created, only the central configuration file and the property files need to be adjusted, to replace the respective configurations of the new service.

As the configuration file is global and used every time a service is deployed, there are limitations regarding the actions to be used and so also regarding the configuration parameters that can be replaced. It works without any problems, when all actions used do not reference a service by name explicitly. The actions should only specify the type of service, which should be touched (proxy or business service). So those replacement rules are generic and very flexible.

Usually configuration files defined in this style are clear and comprehensible, but limited regarding the granularity of the replacements. It is perfectly fine and easy to manipulate service endpoints (hostname, ports, URLs), but properties like HTTP connection timeout or other numeric configuration parameters are hard to replace using global configuration files, because usually those configurations are specific to a explicit service.

An example for a generic action is a search and replace, which may look like the following:



The decision, if the local or the global approach is more applicable, should be clarified depending on the requirements in a particular project. In most of the projects, in which I was involved, the global approach described in this article was adequate. Usually it is sufficient to just replace information regarding the service endpoints. But if more control regarding replacements is needed, the local approach is definitely the one to prefer.

In the next article of this series, it will be shown, how to deal with configurations, which cannot be directly manipulated with the configuration files. An example for that is that depending on the current environment a different API key is needed in the header of the HTTP request.

Alle Beiträge von Sven Bernhardt

Sven Bernhardt is a technology enthusiast who works for OPITZ CONSULTING as the Chief Architect on the Corporate Development team. In this role, he manages the technology portfolio and develops Best Practices and Guidelines. In addition, Sven supports his colleagues in implementing Software solutions for Customers. Sven regularly speaks at various conferences about technology or architecture topics. He also shares his thoughts and experiences by writing articles and blog posts. In addition, he's a Kong Champion.

4 Kommentare

  1. Pingback: SOA & BPM Community Newsletter August 2016 | SOA Community Blog

  2. Pingback: Servicebus 12c: Using configuration files for customizing service deployments by Sven Bernhardt | SOA Community Blog

  3. Thanks This is very helpful.
    Could you refer to the article mentioned in the conclusion „In the next article of this series, it will be shown, how to deal with configurations, which cannot be directly manipulated with the configuration files. An example for that is that depending on the current environment a different API key is needed in the header of the HTTP request.“

Schreibe einen Kommentar