Exporting/Importing Objects

You use the Export/Import functions to transfer objects from one Client to another within the same Automation Engine system, from one Automation Engine system to another or from an Automic Automation on-premises environment to Automic SaaS. The object definitions are exported to either an XML or a JSON file that can be exchanged between different platforms. You can import and export objects either from the Automic Web Interface (Process Assembly perspective and Global Search dropdown list), using the following script elements: IMPORT and EXPORT or through the AE REST API.

Automic Automation provides various methods to transfer data. Some of them require you to have access to the AE database. For this reason, you will use one or the other depending on the type of environment that you have:

  • On-premises and AAKE environments

    Since you can have access to the AE database, you can use any of the available options (export/import objects, Transport Case in combination with the AE DB Utilities, Transport Case to export and then simply import it).

  • Automic SaaS

    You do not have access to the AE database in Automic SaaS. This means that if you want to transfer data from an on-premises environment to Automic SaaS, you cannot use the Transport Case in combination with the AE DB Utilities.

This topic touches on the difference between transporting and exporting/importing objects and explains in detail the Export/Import functionality.

Important!

  • To import the XML file, the target Automation Engine system must have at least the same Service Pack version as the source system.

  • The import function for XML data is downwards compatible. Importing objects from older versions into newer ones is supported. Importing newer XML data schemas into older Automation Engine systems is NOT possible.

  • Automic Automation supports Unicode to enable Universal Language Support and uses UTF-8 for this purpose. If you import objects from older versions that do not support Unicode, Automic Automation reads the legacy encoding and converts it to UTF-8. This means that the imported objects will display any special characters correctly.

Restrictions when Importing/Exporting Objects

  • Authorizations that are granted at object level (Authorizations Page ) cannot be exported.

  • For security reasons, passwords cannot be exported either.

  • For information about the limitations as to the number of objects that can be exported at the same time, see MAX_EXPORT_COUNT.

  • For information about the file size limitations of the imported file, see MAX_IMPORT_SIZE.

This page includes the following:

Differences between Transporting and Exporting or Importing

The purpose of the Import/Export and Transport Case functions is very similar. However, there are important differences that you must know to be able to make the right choice:

  • When importing objects you can select the folder in AWI which the objects should be stored. When transporting, the folders, subfolders and objects are transferred to exactly the same locations in the target Client/System.

  • Importing/exporting might cause a heavy workload for the Dialog Process (DWP), see Dialog Processes. As the Transport Case loads directly to the database, this is the better choice if you have access to the database (as is the case, for example, in an on-premises environment) and you want to transfer large amounts of data.

  • Transporting data is also recommended if you want to carry out mass changes in the file that is created for transporting. For example, you want to transfer all the objects in your test system to your production system. The name of the objects contains the TEST_ prefix and you want to replace it everywhere with the PROD_ prefix. You can do so via the AE DB Change utility, see AE DB Change.

Exporting Objects

You can export objects individually or you can select multiple objects and export them in bulk. You can also export folders and a combination of files and folders. In either case, one single file called export.xml or export.json (depending on the format that you selected to export it) is created. This file contains all the object-relevant data. It also contains the original folder structure. It is saved to your Downloads folder.

Some objects (Workflows, Schedules, and so on) reference other objects. When you export them, you can decide whether to include the referenced objects in the export.xml/export.json file or not. This option is only available when you export these objects individually and not in bulk.

You can export objects from the following areas of the Process Assembly perspective:

Area in Process Assembly What you can export

My Favorites

  • Folders on the Explorer pane
  • Folders in the My Favorites main list
  • Objects in the My Favorites main list

User Catalog
  • Folders on the Explorer pane
  • Folders in the main list
  • Objects in the main list

Recently Used

Objects in the Recently Used main list

Transport Case

Objects in the Transport Case main list

Folder structure
  • Folders in the Explorer pane except the <No Folder>
  • Folders and objects in the main list

You can also export Queues from the Administration perspective.

Exceptions

Objects that are referenced in the following ways are not exported, even when you export referenced objects:

  • 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)

To Export Objects

  1. Select the folder, object or combination of both and right-click to select one of the following:

    • Export

    • Transfer > Export

    The Export Objects dialog is displayed.

  2. In Format, specify the format in which you want to export the object definitions, whether XML or JSON.

  3. Click Export Objects.

    The objects that you want to export can contain references to other objects, for example Workflows, Schedules, PromptSets, etc. The  Export with references option lets you export those objects AND all the objects that they have references to.

    Important! The following objects are EXCLUDED from this option: Client (CLNT), Server (SERV), Agent (HOST), Login (LOGIN), Folders (FOLD), and Store (STORAGE) objects. That is, when you export an object and select Export with references, all referenced objects are exported with it except for the ones mentioned in this note.

  4. Click the Export Objects button. This saves the exported file to the Downloads folder in your computer. It is called exported.xml, exported.json or exported.zip (if you have exported a STORE object, see Exporting STORE Objects). The file can be imported as is in the target system.

  5. If this folder contain links to other objects that are outside the structure you are exporting, an additional dialog is displayed prompting you to confirm whether you want to export those objects too.

Exporting STORE Objects

Exporting STORE objects is slightly different because they contain text and/or binary files. When you export a STORE object, a ZIP file is created and saved to the Downloads folder. The ZIP file includes the following:

  • The export.xml file with the information about the STORE object (and about any other object if you have selected multiple ones).

  • A separate export file for each file within the STORE object. They are exported without file extension. You can add the extension if you want to open them from outside the Automation Engine.

    If you import the ZIP file into a different Client or system, the Automation Engine automatically recognizes the file formats and displays them correctly in the imported STORE object.

Importing Objects

You can then import the XML, JSON or ZIP file into a different Client, AE system or Automic SaaS environment. You can replace existing objects with the ones that you are importing and keep folder links, if available. If you are importing folders with sub folders, their structure is kept.

Important!

  • (for STORE object imports) The name of the XML file contained in the ZIP file must be export.xml when importing files from previous Automation Engine versions.

  • You can import objects to any folder of the Process Assembly perspective except the <No Folder>.

To Import Objects

  1. Right-click anywhere on the location to which you want to import and right-click to select one of the following:

    • Import

    • Transfer > Import

    The Import Objects dialog is displayed.

  2. In File click the upload icon and search for the file you want to import.

    You can only select ZIP, JSON and XML files.

  3. Select Settings: Replace existing objects if you want to overwrite existing objects with the ones that you are importing.

  4. If you have selected Replace existing objects, an additional option is displayed, namely Keep existing folder links. Select this option to preserve any existing object links as they are in the target system. This means that links to objects in Favorites, Dashboards, etc. will be preserved as-is in the target system, and you will not have to recreate them.

    If an object is imported in a different folder than its existing home folder in the target system, the home folder will not be changed, but instead a link will be created in the target folder.

  5. Click the Import Objects button.

    If you are replacing existing objects, they are not created here though. The already available ones are replaced by the new ones.

    A message is displayed indicating which objects have been imported and/or replaced. Click Close to return to the Explorer.

Importing Dashboards

If you export a Dashboard object from My Dashboards, and then import it, the imported Dashboard object is then available in the Public Dashboards. If necessary, right-click the Dashboard and select Move to My Dashboards.

For more information, see Working with Dashboards

Importing Calendars

The following considerations are important when importing Calendars:

  • If you are importing Calendar A and Calendar B contains Calendar Events that refer to A, you must also import those Calendar Events.

  • Calendars are recalculated after each import. If this calculation takes place before the Calendar Events have been read, error messages might occur. You can ignore them, no manual interference is required.

For more information, see Calendars (CALE).

Size and Number of Objects

The maximum allowed size of the XML and ZIP import files in KB is set on Client 0 in the MAX_IMPORT_SIZE key in the UC_SYSTEM_SETTINGS - Systemwide Settings VARA object. As and administrator user, you can also limit the maximum number of objects that should be exported at once. Use the MAX_EXPORT_COUNT key for this purpose.

Editing the Generated XML Files

Various tools are available that can be used to edit the generated XML files. If you use Notepad, take into account that it creates additional header information if exported objects include special characters (such as titles with German U umlauts) in order to display them. This changes the content of the XML. Thus, the Automation Engine cannot guarantee that importing will provide the results you expect.

See also: