import

import is the main task for updating DataPower configuration. It imports previously exported configuration and files into a DataPower domain. The input for import can be created using WebGUI or DPBuddy’s export task. The functionality supported by import is similar to “Import Configuration” available from WebGUI. import can handle a stand-alone XML configuration file or a zip file containing both configuration and files to be uploaded to the DataPower file system.

Upon completion, import prints a report with the list of all updated configuration objects and files.

buddyImport is the alias of “import”. Eclipse Ant editor gives warning when dp:import is used as it confuses it with the Ant’s built-in import task. dp:buddyImport can be used to avoid this.

import allows for specifying Ant/Groovy/Gradle variables in any text node or an attribute of the deployment policy file. Any XML file used in transformation can also utilize references to Ant/Groovy/Gradle variables.

import supports transformation actions described in Transforming DataPower Configuration. Transformations can be applied to XML import files or to the files inside a ZIP archive.

In certain cases DataPower automatically creates “GeneratedPolicy” objects with generated names. Generated policies may cause import to fail. If this is the case, you need to delete generated policies from the export file by adding the following directive to the transform:

<dpExclude class="GeneratedPolicy" />

Attributes/Options

Attribute	Description	Required
file	File to import. This could be a zip or an xml/xcfg file.	Yes
overwriteFiles	If set to true, overwrite existing files with the files included with the import. Defaults to true for zip files and to false for xml/xcfg configuration files.	No
overwriteObjects	If set to true, overwrite existing objects with the objects defined as part of this import. Defaults to true (DataPower default).	No
rewriteLocalIp	If set to true, the local address bindings of services contained in the import package will be rewritten to match the equivalent interfaces of the device. Defaults to false (DataPower default).	No
dryRun	If set to true, run import in “dry run” mode. Defaults to false (DataPower default).	No
resolveVars	If set to true, attempt to resolve variables (${}) inside the export file. DPBuddy will raise an exception if any variables/properties remain unresolved. This setting is equivalent to defining an empty transform nested element. Defaults to false.	No
transformDefs	File to load transform definitions from. Definitions are specified in XML (Apache Ant) format described in Transforming DataPower Configuration. The file could contain multiple “transform” elements, each with its own “id” attribute.	No
transformId	ID of the transform definition (transform XML element) in the transform definitions file.	No
applyUpdatesTo	List of DataPower configuration class names and object names to update in HOCON format, e.g., ‘XMLFirewallService: fw1, WSGateway: proxy2’. The actual updates (what element to update and the values) are defined by the “updates” option.	No
updates	Updates to apply to elements of the objects specified by ‘applyUpdatesTo’. HOCON format is used to specify element names and values, e.g., ‘LocalPort:8090, RemoteEndpointHostname: myHost’. This means that the “LocalPort” element of all objects matched by “applyUpdatesTo” will be set to “8090”.	No
transformOnly	If set to true, DPBuddy will transform the files according to the nested transform element or the transformDefs option but it will not execute the import itself. In this mode, the task does not connect to DataPower. This is convenient for developing/troubleshooting transform actions. Defaults to false.	No
workDir	Path to the directory used to hold temporary files. DPBuddy will unzip the content of the zip file into this directory. This is needed when transform/transformDefs is used to transform configuration files contained inside a zip file. Note that DPBuddy cleans this directory every time the import task is executed. If transform/transformDefs is not used or when the imported file is XML, workDir is ignored. Defaults to ${java.io.tmpdir}/dpbuddy/import. java.io.tmpdir is a Java system property. It usually defaults to /tmp on Unix and \Users\<user name>\AppData\Local\Temp on Windows.	No
deploymentPolicyFile	Path to the deployment policy XML file on the local filesystem. The deployment policy is automatically uploaded/configured on the device before import is executed. This file could be a direct export of the deployment policy object. Note that DPBuddy will attempt to resolve “${}” variables inside the deployment policy file. If this is undesirable (e.g, if the variables are going to be resolved by DataPower using deployment policy variables), import the deployment policy using a separate “import” command. The deployment policy XML file must contain a single deployment policy; no other configuration objects are allowed.	No
deploymentPolicyName	Name of the existing deployment policy to use for the import operation. The policy should already exist on the device.	No
deploymentPolicyVars	Name of the deployment policy variables to use with the deployment policy. The variables object should already exist on the device. Note: this requires Version 7 of DataPower firmware.	No
checkpoint	Creates checkpoint with this name before the import.	No
rollbackOnError	If set to true, roll back the domain’s configuration to the last checkpoint (if it exists), in case of any import or verification errors. Use it in conjunction with the checkpoint attribute. Defaults to false.	No
failOnError	If set to false, don’t fail the build in case of import errors. Defaults to true.	No
reimportOnError	If set to true, attempt to re-run import in case of import errors. Use this setting if you exported your configuration with sortObjects option set to true. Defaults to false.	No
reset	If set to true, reset the domain’s configuration before the import. Note that this will wipe out all objects and services in the domain. Defaults to false.	No
quiesce	If set to true, quiesce the domain before the import. Defaults to false.	No
unquiesce	If set to true, un-quiesce the domain after the import is completed. Defaults to false.	No
assertObjectsUp	If set to true, upon completing the import, DPBuddy will invoke the assertState task to verify that all objects in the domain are in “up” state. Defaults to false.	No
assertPorts	A comma-delimited list of ports to checkOld after the import is done. DPBuddy will invoke assertOpenPorts task to verify that all ports in this list are assigned to active services. If this is not the case, DPBuddy will raise an exception.	No
domainComments	Sets the comment field of the target application domain to this value. You can use this attribute to specify the build date, version number and other tracking information. You can view this value from DataPower WebGUI by navigating to the “Application Domains” screen from the “default” domain.	No
domainPatterns CLI alias: domains	Comma-delimited list of regular expression patterns defining what domains to apply the command to. Use ‘.*’ for all domains except the default. Use ‘.*,default’ to include the default domain. Defaults to the current domain. The current domain is specified using the dpDomain property or domain attribute of the task.	No

Examples

This is a simple example of the import task. See samples/ant-tasks/import-export.xml file located in your DPBuddy distribution or online.

 dpbuddy import -file dpconfigs/WSProxy.zip
# Apply transforms defined in an external file
dpbuddy import -file dpconfigs/XMLFirewall.xml -save -transformDefs transformDefs.xml -transformId "set.fw.port"
# Change local port, turn off the debug mode for the firewall
dpbuddy import -file dpconfigs/XMLFirewall.xml -updates "LocalPort:3087, DebugMode:off" -applyUpdatesTo "XMLFirewallService:testFirewall"

<dp:import file="${wsproxy.zip.file}" />

transformFiles Nested Element

transformFiles defines what files to transform by the transformation actions contained in the nested transform element. transformFiles can only be used if the imported file is “zip”. For XML import file transformation actions will be applied to the file referenced in the file attribute of the task.

transformFiles inherits all the attributes and elements of the Ant patternset. You have to define your include/exclude patterns in such a way that only XML files will be selected by the patternset. DPBuddy will attempt to apply all transformation actions to all matched files.

Usually, transformations are applied to the DataPower configuration file typically named “export.xml” in the zip file. In this case, you just need to specify “export.xml” in the includes of the transformFiles:

<transformFiles includes="export.xml">

transformFiles has to contain at least one transform element, as explained earlier in this document.

If transformFiles is omitted and the imported file is “zip”, transformation actions will be applied to “export.xml” inside the zip file. If “export.xml” does not exist, an error will be thrown.

You can specify multiple transformFiles, thus applying different transformation actions to different files.

transform Nested Element

transform contains the transformation actions documented in the section Using DPBuddy to Transform XML Files Transforming DataPower Configuration.