Automation Engine Script Guide > Ordered by Function > Handle Objects > IMPORT

IMPORT

Script Function: Imports objects from an XML file.

Syntax

IMPORT(File [,[Folder], [Object Setting], [Link Setting]])

Syntax

Description/Format

File

File name with full path specification for the object import.
Format: script literal or script variable

Folder

Name of the folder in which the objects should be stored.
Format: script literal or script variable

Object Setting

Setting for the handling of existing objects.
Format: script literal, script variable or number

Allowed values: "0" (default value), "1"
"0" = Existing objects are skipped.
"1" = Existing objects are overwritten, which may be folder or non-folder objects.

Link Setting

Setting for the handling of existing folder links or external objects.
Format: script literal, script variable or number

Allowed values: "0", "1" (default value)
"0" = Existing folder links are ignored, external objects will not be imported.
"1" = Existing folder links are kept, external objects are imported.

This parameter is only relevant when the Object Setting "1" is selected.


Return codes

"0" - Import process was successful.
"20657" - The target folder does not exist.
"20692" - The file does not exist.
"21724" - File access is not possible due to missing authorization.
"21729" - Import not possible. The XML file to be imported does not have the required AE format.
"21730" - The imported XML file does not meet the required encoding.
"21732" - Error occurred during import. Further information is provided in the activation log.

Comments

This script function can be used to import objects or folder structures from an appropriately formatted XML file.

Do no use the import and export function for mass transports. Use the Transport Case for this purpose.

When you import folder structures, the XML file will contain folder structure information at the top of the file. During import, all folder and non-folder objects, linked objects as well as sub-folders are included and a new folder ##INCLUDED_EXTERNALS## will be created on the same level as the dedicated folder on the target system. Linked folder and non- folder objects will be stored in the ##INCLUDED_EXTERNALS## folder.

Non-folder objects are not treated as objects during import. Therefore import settings apply only to folder objects.

Objects are created in the specified folder. If there is no such folder or if the parameter is missing, the objects are stored in <No folder>.

You can use the script statement :ON_ERROR in order to determine the reaction to an erroneous import. You can still use the script functions for error handling in order to analyze the import. Script processing continues. You can also cancel processing.

The XML file's standard size is 1024 KB, the maximum file size is 30720 KB. The administrator can specify a different size in the key "MAX_IMPORT_SIZE" of the variable UC_SYSTEM_SETTINGS.

More detailed information about the import process is written to the activation report of the object that calls the import.

 The import process fails if you do not have a write access to the object or the target folder.

Attention: Imports to the folder "Version Management" are not allowed.

In a distributed AE environment (work processes run on different computers) you cannot determine the computer on which the import takes place. Automic recommends specifying the UNC path under Windows. Note that the Server must run under an appropriate domain user so that the UNC names can be accessed. If you use a UNIX Server, you must specify the absolute path in UNIX notation. The file system must also be accessible (NFS; mount command) but it is irrelevant on which computer it is located. Doing so is important in order to ensure that the required XML file is used. 

This script statement causes all the script's open transactions to be written to the AE databaseA database is an organized collection of data including relevant data structures..

Example

The following example skips objects that already exist in the import process. File and folder name are passed on to the script function as a script variable. 

:SET &FILE#  = "\\PCUC4\UC4global\IMPORT\uc4_import.xml"
:
SET &FOLDER# = "IMPORT/JOBS"
:
SET &RET#    = IMPORT(&FILE#,&FOLDER#,"0")

Example for importing a folder structure:

 

Example for UNIX:

:SET &FILE#  = "/opt/UC4/import/uc4_import.xml"
:
SET &FOLDER# = "IMPORT/JOBS"
:
SET &RET#    = IMPORT(&FILE#,&FOLDER#,"0")

 

See also:

Script element Description

EXPORT

Exports objects to an XML file.

Script Elements - Handle Objects

Importing and Exporting Objects

About Scripts
Script Elements - Alphabetical Listing

Script Elements - Ordered by Function