.. highlight:: xml
.. index:: export

.. _export:

``export``
----------

The ``export`` task exports configuration from a domain. The task supports all functions of the WebGUI "Export configuration" screen and provides some additional features.

Both XML/XCFG and ZIP file formats are supported. The format is determined automatically based on the provided file extension. "xml" and "xcfg" are treated as XML, all other extensions are treated as ZIP.

``export`` supports the nested ``transform`` element containing the transformation actions described earlier. This can be used, for example, to replace actual values, such as port numbers with Ant/Groovy/Gradle variables. Later on, when the configuration is imported using ``import``, the variables will be automatically resolved. Note that ``transform`` can only be used with the XML configuration format.

DataPower embeds base64-encoded files into the exported XML configuration, including several WebGUI-related files. This makes it difficult to edit the configuration file or track changes.  The ``export`` task removes all files from the exported configuration by default. It also removes the "interfaces" and "export-details" sections of the exported configuration. Finally, ``export`` formats the configuration using indentation. Additionally, all objects in the exported file can be sorted alphabetically (by name and then by type) to preserve consistent ordering of objects. Sorting can be turned on by  setting ``sortObjects`` to ``true``.
As with ``transform``, these changes are only performed to XML configuration; configuration in ZIP format is saved unchanged. This feature can be turned off using the ``defaultTransform`` attribute.

In certain cases DataPower automatically creates "GeneratedPolicy" objects with generated names. These names create "noise" in the export file and complicate comparing different versions of the configuration. Generated objects don't need to be preserved in the export file, they can be excluded using the following transformation:

.. code-block:: xml

  <delete xpath="//GeneratedPolicies | //GeneratedPolicy" matchRequired="false"/>

Transforming and formatting XML configuration files makes it easier to store configuration under version control and to track the history of changes.

You can also provide a deployment policy as part of the export task. DataPower will add the policy to the resulting export configuration file. The policy will then be "activated" upon import.

Export and import can be used together to update configuration or to copy configuration between devices/domains. Simply run export first, save the configuration to a file and then run import using the same file.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Attribute
     - Description
     - Required
   * - file
     - Name of the file to which the exported configuration should be saved.

       The task will create directories containing the file if they don't exist.

       The file must have "zip" or "xml" or "xcfg" extension.
     - Yes
   * - classPattern
     - Regular expression defining what classes (types) to export, e.g., "WSGateway".

       If ``class`` is omitted, all classes will be matched.

       Specifying ``classPattern`` and ``namePattern`` attributes is equivalent to defining nested ``exportObject`` element.
     - No
   * - namePattern
     - Only the objects whose name matched this regexp will be exported.

       If ``name`` is omitted, all object names will be matched.
     - No
   * - namePatterns
     - Comma-delimited list of regular expression patterns.

       Only DataPower objects that match at least one pattern will be exported. Objects will be exported irrespective of their class (type).

       This attribute is useful when you want to export all objects based on a naming convention. It can also be used to export a list of uniquely named objects without having to worry about what their classes are.

       Note: this attribute is deprecated. Use the ``exportObject`` nested element instead.
     - No
   * - allFiles
     - If set to ``true``, export all files from the ``local:/`` filesystem.

       If not specified, only the referenced files will be exported.

       For export in XML format, this setting will be ignored unless ``defaultTransform`` is set to ``false``.

       Defaults to ``false`` (DataPower default).
     - No
   * - persisted
     - If set to ``true``, export only the persisted configuration.

       Defaults to ``false`` (DataPower default).
     - No
   * - deploymentPolicyFile
     - Path to the deployment policy file on the local machine. The deployment policy is automatically uploaded/configured on the device before the request is executed.

       The deployment policy will be embedded with the export file.
     - No
   * - deploymentPolicyName
     - Name of the deployment policy to include with the export/backup. The policy has to already be defined on the device.

       The deployment policy will be embedded with the export file.
     - No
   * - defaultTransform
     - If set to ``true``, apply default transformations to the exported XML configuration. This includes removing "/datapower-configuration/filesonly" and " /datapower-configuration/interface-data" elements and formatting the file using indentation.

       Defaults to ``true``.
     - No
   * - sortObjects
     - If set to ``true``, reformat the exported XML configuration file by sorting DataPower configuration objects in the file alphabetically by name and then by type. This allows for comparing DataPower configurations (especially if the configuration file is stored under version control). DataPower could arbitrarily re-order objects in the export file, which makes tracking changes difficult. ``sortObjects`` solves this problem.

       Note that DataPower requires all objects to be defined prior to being referenced. E.g., a rule action (StylePolicyAction) has to be defined before the processing rule (StylePolicyRule) in the export file. Therefore, in order to import a sorted exported file, you will need to run the import command with ``reimportOnError`` set to ``true``.

       Defaults to ``false``.
     - No

``exportObject`` Nested Element
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This nested element defines the objects that will be part of the export. Its two key attributes are ``class`` and ``name``. Both attributes are optional, and both support regular expressions. This gives you a lot of flexibility; you can define regexps matching classes, objects, or both.

If you omit both ``class`` and ``name``, all configuration objects of the domain will be exported. Likewise, if you do not provide any nested ``exportObject``, all objects will be exported.

``exportObject`` supports other attributes, such as ``includeDebug``. These attributes will be applied to all matched objects.

You can specify multiple ``exportObject`` elements within the same task. Alternatively, you can use "|" (OR) in your regular expressions. For example, you can use the following expression in "class" to export all Web service gateways and XML firewalls: ``(WSGateway|XMLFirewall.*)``.


.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Attribute
     - Description
     - Required
   * - class
     - Regular expression defining what classes (types) to export, e.g., "WSGateway".

       If ``class`` is omitted, all classes will be matched.
     - No
   * - name
     - Regular expression defining objects to be exported. Only the objects whose name matched this regexp will be exported.

       If ``name`` is omitted, all object names will be matched.
     - No
   * - refObjects
     - If set to true, include all objects referenced/required by this object.

       Defaults to ``true`` (DataPower default).
     - No
   * - refFiles
     - Include all files referenced by this object.

       Defaults to ``true`` (DataPower default).
     - No
   * - includeDebug
     - Include debug information in the export.

       Defaults to ``false`` (DataPower default).
     - No

``transform`` Nested Element
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``transform`` contains the transformation actions documented in :ref:`transform`. This element is optional. It can only be specified if exporting a configuration in XML format.

``namePattern`` Nested Element
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``namePattern`` element provides an alternative to specifying object name patterns using the ``namePatterns`` attribute.  It is useful when a regular expression pattern contains a comma, which is used as a delimiter in the ``namePatterns`` attribute.

You can specify multiple ``namePattern`` elements within the same task.

Note: ``namePattern`` element is deprecated. Use ``exportObject`` nested element instead.

.. list-table ::
   :widths: 20 80 8
   :header-rows: 1

   * - Attribute
     - Description
     - Required
   * - pattern
     - Export object with names matching this regular expression.
     - Yes

Examples
^^^^^^^^

The following example exports all objects with the name starting with "testService" and of the classes with the names starting with "WSG" (which would match "WSGateway").

.. code-block:: bat

  dpbuddy export -file services.zip -classPattern="WSG.*" -namePattern="testService.*"

.. code-block:: xml

  <dp:export file="${wsproxy.file}" allFiles="false" >
      <exportObject class="WSG.*" name="testService.*" />
  </dp:export>


You can find more examples under ``samples`` in your distribution or `online <http://myarch.com/dpbuddy-examples/>`_.