16.4. 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:

<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.

16.4.1. Attributes/Options

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

16.4.2. 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.*).

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

16.4.3. transform Nested Element

transform contains the transformation actions documented in Using DPBuddy to Transform DataPower Configuration and XML Files. This element is optional. It can only be specified if exporting a configuration in XML format.

16.4.4. 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.

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

16.4.5. 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”).

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

<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.