EXPORT

Script Function: Exports objects to an XML file

Syntax

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

Syntax

Description/Format

Folder Name of the folder (with complete path specifications) which you want to export.
Format: script literal or script variable

Object

Name of the object(s) to be exported (with wildcard characters)
Format: script literal or script variable

The wildcard characters "*" and "?" can be used. "*" stands for any, "?" for 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

Allowed values: "Y(es)" or "N(o)"

Default value: "N"

If you set this value to "Y", external objects are exported as well.

Relevant for folders only. The parameter will be ignored in combination with other object types.

Include_Referenced_Objects

Allowed values: "Y(es)" or "N(o)"

Default value: "N"

If you set this value to "Y", referenced objects are exported as well (recursively). Referenced objects are objects used by the given object such as tasks in a workflow or PromptSets.

Objects that are referenced in the following ways are not exported, even when you use this parameter and value "Y":

  • Login, User, 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 system client 0000 (e.g. UC_* Vara in data reference of prompt, HOST objects in jobs)

Not supported with folders or wildcard characters.


Return code

"0" - Export was successful
"20693" - The object does not exist
"21723" - The target file exists and is write-protected

Comments

With this script function you can export objects or folder structures to a specific XML file. The return value of the script function is zero, if the export was successful.

When you export folder structures, the XML file will contain folder structure information at the top of the file.
During export, all folder and non-folder objects and sub-folders as well as linked objects are included in the export.

When importing, a new folder ##INCLUDED_EXTERNALS## will be created on the same level as the dedicated folder on the target system.
Linked objects will be stored in the ##INCLUDED_EXTERNALS## folder.
For details on import also see information on the script element IMPORT.

The importing and exporting functionality is not suitable for mass transports! Use the Transport Case instead for this purpose.

With the script statement :ON_ERROR you can determine the reaction to an incorrect export. As before, you can analyze the error with the script functions for error handling. The script will continue to be processed. It is also possible to cancel the processing of the script.

Before the export starts, the system checks if the file already exists. If this is the case, it will be overwritten. If the file is write-protected, the export cannot be done.

 The export also fails when the user does not have the authorization "Read" (R) for the object.

Further information on exports is kept in the activation report of the object that calls up the export.

In a distributed AE environment (work processes run on different computers) you can not determine on which computer the export will be made. We therefore recommend specifying the UNC path under Windows. Please note that the server should run under an appropriate domain user so that the UNC names can be accessed. For UNIX server, the absolute path must be indicated in UNIX notation. Additionally, the FileSystem 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.

The script statement causes all open transactions of the script to be written to the AE database.

Examples

In the following example for Windows and UNIX, all objects with names starting with "MM.DAY" are exported. Object name and file name are transferred to the function as script variable.

For Windows:

:SET &OBJECT# = "MM.DAY*"
:
SET &FILE#  = "\\PC\ ae \EXPORT\ ae _export.xml"
:
SET &RET#   = EXPORT(&OBJECT#,&FILE#)

For UNIX:

:SET &OBJECT# = "MM.DAY*"
:
SET &FILE#  = "/opt/ ae /import/ ae _export.xml"
:
SET &RET#    = EXPORT(&OBJECT#,&FILE#)

The following example exports a folder structure:

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

This example exports a workflow with references:

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

See also:

Script element Description

IMPORT

Imports objects from an XML file

Script Elements - Handle Objects

Importing and Exporting Objects

About Scripts
Script Elements - Alphabetical Listing

Script Elements - Ordered by Function