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.

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.

Notes:

• 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 the object. If you do not have sufficient permissions, the export fails. For more information, see Granting Automation Engine Authorizations.
• The system checks if the file already exists before starting the export. If the file 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.

Important!

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

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

Additionally, the file system needs to be accessible (NFS; mount command) but it is not important on which computer it is located. This is the only way to assure that the actually required file is used.

Syntax

EXPORT (Folder, File [,Include_External_Objects])
EXPORT (Object, File [, ,Include_Referenced_Objects])

Parameters

• Folder
  Name of the folder (with complete path specifications) to export
  Format: script literal or script variable

• Object
  Name of the object(s) to export
  Format: script literal or script variable
  Note: You can use the wildcard characters * (any) and ? (exactly one character)

• File
  Name of the file (with complete path specifications) in which the objects are to be exported
  Format: script literal or script variable

• 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.
  Allowed values:

  • Y
    Includes external objects
  • N (default)
    External objects are not exported
    

• 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.
  Allowed values:

  • Y
    Referenced objects are exported recursively.
  • N (default)
    Referenced objects are not exported
  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)

Return Codes

• 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 action to take if the export fails. For more information, see Script Elements for Error Handling.

Examples

The following examples export all objects with names starting with MM.DAY. The scripts use a script variable 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")

 

See also: