.. highlight:: xml
.. index:: Managing Environment Variables

.. _managing_env_vars:

Managing Environment-Specific Configuration Settings
====================================================

A typical organization uses multiple DataPower devices, and multiple domains in each device. Usually, at least one device is used for development and testing; multiple devices could be used in production.

Different devices have different IPs, ports and potentially other parameters (environment settings). DPBuddy provides an extensible and flexible mechanism for managing environment settings. This mechanism can be used instead of or in addition to any traditional approach for managing environment settings, such as specifying all settings for a given environment in a separate file.

DPBuddy supports two different formats for defining environment settings: :ref:`HOCON <hoconConfig>` and :ref:`name=value properties <environment_properties>`.  HOCON/JSON is much more powerful and expressive than properties and thus recommended for complex configurations.


.. _environment_task:

``env``/``device`` Attribute/Option and ``environment`` Task
------------------------------------------------------------

The environment name is specified using the ``env`` attribute/option or the ``dp.env`` property. The ``env`` attribute/option is supported by all DPBuddy tasks/commands. DPBuddy also supports ``device`` attribute/option and ``dp.device`` aliases. ``env`` and ``device`` can be used interchangeably; it's up to the user to decide which name to use.

DPBuddy also comes with the ``environment`` task described below. This task should be used if environment settings are used for non-DPBuddy tasks (e.g., if you want to "echo" the value of a property). In all other cases ``env``/``dp.env`` is sufficient.

``dp.env`` globally defaults the environment name to its value for all DPBuddy tasks and commands.

The environment name can contain one or multiple elements separated by ".". The trailing dot is not needed.

Once the environment name is set, DPBuddy provider will use this name for locating HOCON objects and for dealing with property prefixes.

The ``environment`` task can be called multiple times within a build file. Each invocation will override the name defined earlier.

The environment name defined using ``env`` attribute will only apply to the task where it was specified. In this case, the environment won't be set globally.

You can also undefine the environment name using the ``environment`` task by specifying an empty string as the value: ``name=""``.

Note that the DPBuddy's environment settings resolution mechanism does not propagate to Ant sub-projects. If you invoke another Ant file or target using ``Ant`` or ``AntCall``, make sure to invoke ``environment`` in this sub-project.

Attributes of the ``environment`` Task
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - | name
       | prefix
     - Name of the target environment.

       An empty value (name="") will disable the DPBuddy's environment settings resolution mechanism.
     - Yes
   * - providerClass
     - Property provider implementation. The class has to implement the ``org.apache.tools.ant.PropertyHelper.PropertyEvaluator`` and ``com.myarch.propertyselector.PropertyProvider`` interfaces.

       Defaults to DPBuddy's property provider.
     - No

Examples
^^^^^^^^

Using ``environment`` with HOCON configuration:

.. code-block:: xml

  <dp:confText>
    dev: {proxy.port: 8080}
    test: {proxy.port: 7070}
  </dp:confText>
  <dp:environment name="test" />
  <!-- Will print 7070 -->
  <echo>{proxy.port}</echo>


Using ``environment`` with properties:

.. code-block:: xml

   <!-- DataPower url is defined at the device level -->
   <property name="devtestdevice.dp.url" value="https://devtest.dp" />
   <!-- Each WS proxy has its own port in each of the domains -->
   <property name="devtestdevice.devdomain.wsproxy.port" value="8082" />
   <property name="devtestdevice.testdomain.wsproxy.port" value="9082" />

.. code-block:: xml

   <!--Provide our name to DPBuddy's provider for property resolution-->
   <dp:environment name="devtestdevice.devdomain" />

.. code-block:: xml

   <!-- dp.url should point to devtest.dp url -->
   <echo message="dp.url value: ${dp.url}"/>
   <!-- the value of the port should be the one for the devdomain -->
   <echo message="wsproxy.port value: ${wsproxy.port}"/>