.. highlight:: xml
.. index:: import, importBuddy

.. index::
   pair: import; transformFiles
   pair: import; transform

.. _import:

``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 :ref:`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 :ref:`transform`. 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:

.. code-block:: xml

  <dpExclude class="GeneratedPolicy" />


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

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

   * - Attribute
     - Description
     - Required
   * - file
     - File to import. This could be a zip or an xml/xcfg file.
     - Yes
   * - 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
   * - 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
   * - 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`` 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`` is not used or when the imported file is XML, ``workDir`` is ignored.

       Defaults to ``${java.io.tmpdir}/dpbuddy/import``. :term:`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
   * - transformOnly
     - If set to ``true``, DPBuddy will transform the files according to the nested ``transform`` element, 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
   * - assertObjectsUp
     - If set to ``true``, upon completing the import, DPBuddy will invoke the :ref:`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 check after the import is done. DPBuddy will invoke :ref:`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
   * - 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
   * - 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
   * - 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
   * - domainComments
     - Sets the comment field of the target application domain to this value. You can `use this attribute <http://myarch.com/dp-services-versions/>`_ 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
   * - 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



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 <http://myarch.com/dpbuddy-examples-import-export/>`_.

.. code-block:: bat

   dpbuddy import -file dpconfigs/WSProxy.zip

.. code-block:: xml

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

.. _transformFiles_12_1_3:

``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 <http://ant.apache.org/manual/Types/patternset.html>`_. 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``:

.. code-block:: xml

   <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 :ref:`transform`.