EXPORT

Use the EXPORT script function to export objects or folder structures to an XML file on a server where the Automation Engine, specifically the work processes, are running.

Overview

When you export folder structures, the XML file includes information about the folder structure at the top of the file. The exported content includes all contents of the folder structure:

  • Folders

  • Non-folder objects

  • Sub-folders

  • Linked objects

When you import the content, a new folder ##INCLUDED_EXTERNALS## is created on the same level as the dedicated folder on the target system. Linked objects are stored in the ##INCLUDED_EXTERNALS## folder. For more information, see IMPORT.

Important Considerations

  • Do not use EXPORT for mass transport. Use the Transport Case when you need to move large amounts of content. For more information, see Transporting Data.

  • To export an object, you must be authorized to read it. If you do not have sufficient permissions, the export fails. For more information, see Granting Automation Engine Authorizations.

  • The system checks whether the file already exists before starting the export. If it exists, it is overwritten. If the file is write-protected, the export cannot be carried out.

  • This script function writes all open transactions of the script to the AE database. For more information, see Script Processing.

  • Information about the export is stored in the activation report of the object that calls the export.

  • In distributed AE environments, work processes run on different computers, so you must define on which computer the export is made:

    • (Windows) Specify the UNC path. The server should run under an appropriate domain user so that the UNC names can be accessed.

    • (UNIX) Specify the absolute path in UNIX notation.

    Additionally, the file system must be accessible (NFS; mount command), although it does not matter on which computer it is located. This is the only way to ensure that the required file is used.

Syntax

EXPORT (Folder, File [, Include_External_Objects])

EXPORT (Object, File [, , Include_Referenced_Objects])

Parameters

Parameter Description Format Allowed Values Default Value
Folder Name of the folder (with complete path) to export Script literal or script variable n.a. n.a.
Object Name of the object(s) to export.
Note: You can use the wildcard characters * (any) and ? (exactly one character).		 Script literal or script variable n.a. n.a.
File Name of the file (with complete path) in which the objects are exported Script literal or script variable n.a. n.a.
Include_External_Objects

(Optional, folders only)

 Includes external objects in the export.
Note: The parameter is ignored when the object type is not a folder.		 n.a.

  • Y — Includes external objects.

  • N — External objects are not exported.

 N
Include_Referenced_Objects

(Optional)

 Includes objects used by the exported object, such as tasks in a Workflow or PromptSet objects. Do not use this parameter for folders or with wildcards.
Note: Objects referenced in the following ways are not exported, even if you set the parameter to Y:
  • Login, User, User Group, and Agent objects
  • Variable objects referenced in attribute fields using curly brackets {VARANAME}
  • Objects referenced in Pre- and Post-conditions on the task level in a Workflow
  • Objects referenced in script functions other than :INC
  • Objects located in Client 0 (for example, UC_* VARA in data reference of PromptSets, Agent objects in Jobs)
 n.a.

  • Y — Referenced objects are exported recursively.

  • N — Referenced objects are not exported.

 N

Return Codes

Return Value Condition
0 Successful export
20693 Object does not exist
21723 Target file exists and is write-protected

Tip: Use the :ON_ERROR script statement to define the action to take if the export fails. For more information, see Script Elements for Error Handling.

Examples

The following examples export all objects whose names start with MM.DAY. The scripts use script variables to pass the object name and file name to the EXPORT function.

(Windows)

:SET &OBJECT# = "MM.DAY*"

:SET &FILE# = "\\PC\AE\EXPORT\Test_export.xml"

:SET &RET# = EXPORT(&OBJECT#, &FILE#)

(UNIX)

:SET &OBJECT# = "MM.DAY*"

:SET &FILE# = "/opt/ae/export/Test_export.xml"

:SET &RET# = EXPORT(&OBJECT#, &FILE#)

The following example exports a folder structure:

:SET &RET# = EXPORT("\TESTFOLDER\EXPORT_STRUCTURE", "\\PC\AE\EXPORT\Test_export.xml", "Y")

The following example exports a Workflow with references:

:SET &RET# = EXPORT("EXAMPLE_WORKFLOW", "\\PC\AE\EXPORT\Test_export.xml", "Y")

EXPORT Script Function in AAKE

In AAKE, the :EXPORT command works inside the WP container. To make the file available outside the container, mount a Persistent Volume (PV) for the container. If an existing PV for logs or traces is configured, it can be used to export the files.

You can export the file to the POD's log or trace folder, located at /usr/server/temp/log/ and /usr/server/temp/trace/ respectively. For example:

:SET &RET# = EXPORT(&OBJECT#, "/usr/server/temp/log/<file>.xml", "Y")

Because of the PV configuration, the exported file is automatically placed in the PV folder on the server where the pods are running.

See also:

Related Script Elements

IMPORT

seealso

Exporting/Importing Objects