.. 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 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. .. _exportOptions: 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 * - objects - Comma-delimited list of regexp patterns to export in the format "class:name, class:name". Class and name could be optional, e.g., "class, class" or ":name". Use ".*" to include all objects. - No * - exclude - Comma-delimited list of regexp patterns to exclude from export in the format "class:name, class:name". - No * - | classPattern | CLI alias: class - Regular expression defining what classes (types) to export, e.g., "WSGateway". Deprecated, use "objects" instead. - No * - | namePattern | CLI alias: name - Only the objects whose name matched this regexp will be exported. Deprecated, use "objects" 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 * - refObjects - If set to true, include all objects referenced/required by exported objects. Defaults to ``true`` (DataPower default). - No * - refFiles - If set to true, include all files referenced by exported objects. Defaults to ``true`` (DataPower default). - No * - includeDebug - Include debug information (probe data) in the export. This setting applies only to the objects defined by the namePattern/classPattern attributes/options. It does not apply to the nested ``exportObject`` elements. Defaults to ``false`` (DataPower default). - 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 * - objects - Comma-delimited list of regexp patterns to export in the format "class:name, class:name". Class and name could be optional, e.g., "class, class" or ":name". - No * - exclude - Comma-delimited list of regexp patterns to exclude from export in the format "class:name, class:name". - No * - class - Regular expression defining what classes (types) to export, e.g., "WSGateway". - No * - name - Regular expression defining objects to be exported. Only the objects whose name matched this regexp will be exported. - No * - refObjects - If set to true, include all objects referenced/required by exported objects. Defaults to ``true`` (DataPower default). - No * - refFiles - If set to true, include all files referenced by exported objects. Defaults to ``true`` (DataPower default). - No * - includeDebug - Include debug information (probe data) 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. 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 -objects "WSG.*:testService.*" -includeDebug .. code-block:: xml You can find more examples under ``samples`` in your distribution or `online `_.