Transporting Data

move object definitions from on-premises to Automic SaaS, transport case and importing or exporting objects, transport case, exporting and importing objects

As an administrator, you use the Transport Case to move object definitions from one Automation Engine system to another, from one Client to another one within the same system, or from an on-premises system to an Automic SaaS instance. You do this in the following phases:

  1. Add objects to the Transport Case in the originating system.

  2. (On-premises systems only) Unload the contents of the Transport Case. This requires access to the AE database in the originating system, see AE DB Unload.

  3. Optionally, modify the object definitions outside Automic Automation, see AE DB Change.

  4. Load the object definitions into the target system. You have two options:

    • Using the AE DB Load Utility. This requires access to the AE database in the target system.

      Important! If you are moving your object definitions from an on-premises system to an Automic SaaS instance you CANNOT use this option because you do not have access to the AE database in Automic SaaS.

    • Importing the object definitions directly from AWI in the target system. Use this option to move object definitions from an on-premises system to Automic SaaS.

When you transport objects, a file is created that contains all the data of all affected objects. The file is not a 1:1 export of the database tables and it is therefore not easy to read.

Important!

  • You need the Access to Transport Case privilege to be able to use this function.
  • You can only add objects to the Transport Case. Adding folders is not possible.
  • The Transport Case functionality is downward, but not upward compatible. Transporting objects from older versions and service packs into newer ones is supported. Transporting newer Transport Cases into older Automation Engine systems, including an older service pack of the same version, is not supported.

This page includes the following:

Differences between Transporting and Exporting/Importing

difference between transport case and importing / exporting

  • When importing objects you can select the Automation Engine system folder in 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 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.

Transport Case Terms

These concepts are only relevant for the transporting option.

  • Unloading

    definition of unloading object definitions through the transport case

    After moving the objects to the Transport Case, you unload them. This means that the object data is written to a text file called UC_DATA.TXT that can be transferred (unloaded) from the original to the target database. This file is stored on a location that you can specify in the INI file, see Utility DB Unload. You use the DB Unload utility for this purpose.

  • Loading

    definition of loading object definitions through the transport case

    The file created by the unload process mus then be transferred (loaded) to the target system or Client. You use the DB Load utility for this purpose.

Options to Transport Objects

There are various options to transport object definitions. The option(s) that you can use depend on the type of environments from which and to which you want to move the objects.

Transporting Objects Using the Transport Case and the AE DB Utilities

how to move objects with the Transport Case

Use this method to move object definitions from one Client to another Client within the same on-premises Automic Automation system, or from one on-premises Automic Automation system to another. You need access to the originating and to the target AE databases. This means that you CANNOT use this method to move from an on-premises system to Automic SaaS.

To Move Object Definitions Using the Transport Case and the Utilities

  1. Add the objects to the Transport Case.

    1. In the Process Assembly perspective on the Explorer list select one or more objects.
    2. Right-click and select Transfer > Transport. This option is also available from the Global Search drop down list, see Using the Global Search for Objects and Tasks.

    The objects are not actually moved to the Transport Case. Rather, a reference to them is copied and displayed there. They are now registered for transport but you can still work with them in the Transport Case page.

  2. Unload the Transport Case. For this purpose, use the AE DB Unload utility, see AE DB Unload. This creates a text file in a Transport Case-specific format is stored in the output folder that you have define in the OUTPUT= INI file entry. For more information, see Utility DB Unload.

    After unloading, the objects are not removed from the Transport Case. If you want to remove objects or empty the case, do one of the following:

    • To remove individual objects select one or more, right-click and select Remove from Transport Case.
    • To empty the case, right-click anywhere on the list and select Clear Transport Case.

    The Transport Case of system client 0 displays all objects that should be transported.

  3. Optionally, modify the exported data using the AE DB Change utility. For more information, see AE DB Change.

  4. Import loaded or modified data using the AE DB Load utility of the target system. For more information, see AE DB Load. It automatically recognizes the loading type and triggers Working with Requests .

    Specify if you want to keep the same Clients (for example, if you import to a different database) or if the utility should import all objects to one particular Client. You also have the option whether or not to clean the transport folder.

    The objects are stored in the target Client at the same location and with the same folder structure as in the original Client. If the folders do not yet exist, they are created automatically.

    Note: The AE DB Load utility does not validate whether the object definitions in the text file are correct or not. If one or more objects are broken, the utility still loads them to the target system.

To Cancel Transport Registration

  1. Select one or more objects in the Transport Case.
  2. Right-click and select Remove from Transport Case.

Transferring Objects by Combining the Transport Case, the AE DB Unload Utility and the Import Function

This method combines the Transport Case and the AE DB Unload and (optionally) AE DB Change utilities to extract the data from the original system, and the Import function in the target system. This method requires access to the database of the originating system. However, no access to the database of the target system is required. Therefore, you can use this method to transfer data from an on-premises system to Automic SaaS. You can use this method both from AWI and through the REST API. For more information, see REST API Reference.

To Transfer Objects Using AWI

  1. Add the objects to the Transport Case.

    1. In the Process Assembly perspective on the Explorer list select one or more objects.
    2. Right-click and select Transfer > Transport. This option is also available from the Global Search drop down list, see Using the Global Search for Objects and Tasks.

    The objects are not actually moved to the Transport Case. Rather, a reference to them is copied and displayed there. They are now registered for transport but you can still work with them in the Transport Case page.

  2. Unload the Transport Case. For this purpose, use the AE DB Unload utility, see AE DB Unload. This creates a text file in a Transport Case-specific format is stored in the output folder that you have define in the OUTPUT= INI file entry. For more information, see Utility DB Unload.

    After unloading, the objects are not removed from the Transport Case. If you want to remove objects or empty the case, do one of the following:

    • To remove individual objects select one or more, right-click and select Remove from Transport Case.
    • To empty the case, right-click anywhere on the list and select Clear Transport Case.

    The Transport Case of system client 0 displays all objects that should be transported.

  3. Optionally, modify the exported data using the AE DB Change utility. For more information, see AE DB Change.

  4. In the target system, right-click anywhere in the Process Assembly > Explorer and select Import. The Transport Case file contains the object definitions and their target folder locations. This means that the imported objects will be available in the same location in the target system. For more information, see Importing Objects.

    Important! When importing object definitions, the system runs validates those definitions. If the text file contains one or more broken objects, the Import will fail

  5. The Automation Engine analyzes the definitions of all the imported objects and creates then in the target folders as defined in the file. If errors, occur, an error message indicates it.

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

Important! You can also use the REST API to add object definitions to the Transport Case.

Transferring Objects Using the Transport Case and the Export and Import Functions

This method combines the Transport Case with the Export and Import functions available in AWI. No database access is required, which means that you can use this method to transfer data in all scenarios.

To Transfer Objects Using the Transport Case and Exporting/Importing

  1. Add the objects to the Transport Case.

    1. In the Process Assembly perspective on the Explorer list select one or more objects.
    2. Right-click and select Transfer > Transport. This option is also available from the Global Search drop down list, see Using the Global Search for Objects and Tasks.

    The objects are not actually moved to the Transport Case. Rather, a reference to them is copied and displayed there. They are now registered for transport but you can still work with them in the Transport Case page.

  2. Either in the Transport Case list or in the Transport Case node in the Explorer pane, right-click and select Export Transport Case.

    An export.xml file with the object definitions is saved to your Downloads folder.

  3. In the target Client, right-click anywhere in Process Assembly > Explorer and select Import. For more information, see Importing Objects.

For information about the file size limitations, see MAX_IMPORT_SIZE.

Permission Checks

Automic Automation performs ACL checks to ensure that only Users with the necessary permissions can transfer/import data both through AWI and through the REST API. To be able to successfully transfer/import the data, the following must be true:

  • The administrator User that transfers the data must have the Access to Transport Case privilege in their User definition.

  • The administrator User that imports the Transport Case must have more permissions than the Users and User Groups that they are importing.

Transferring Objects by Exporting/Importing Them

You can always use this method to move objects between Clients in an AE system or between different AE systems, whether you have access to the AE database or not. Use this method if you do not want to move large amounts of object definitions.

For a detailed description of how to export and import object definitions, see Exporting/Importing Objects. For information about the limitations to the number of objects that can be exported at the same time, see MAX_EXPORT_COUNT. For information about the limitations to the size of the file that can be imported, see MAX_IMPORT_SIZE.

Transferring Objects Using the REST API

You can always use this method to import/export object definitions and move them from one Client to another or from one AE system to another, whether you have access to the AE database or not. The AE REST API provides an endpoint for this purpose.

Recommendations when Transporting Data

recommendations to move objects from one system to another

  • When exporting/exporting, huge amounts of data are moved in the database. Ensure that sufficient database space is available and note that the whole process can take a while. In some cases, it can affect the performance of basic operations.

  • Although they are possible, parallel unloads are not advisable and should be avoided.

  • To avoid that database locks caused by the DB Load utility obstruct the Automation Engine, make sure that no activities are running on the target Client when loading the object data to the target system.

    If you decide to transport objects to a system/Client with running activities, the performance will be temporarily impacted. To avoid bottlenecks, turn off the following:

    • Version Management (variable: UC_CLIENT_SETTINGS, Validity key: VERSION_MANAGEMENT)
    • Revisioning, see AE DB Revision Report

  • Loading Objects to Client 0

    Take into account that the objects available in Client 0 are also available in all other Clients.

  • Transporting Users and User Groups

    When transporting Users and User Groups, their passwords are automatically reset to "pass".

    When loading Users, the system verifies whether the User Groups they belong to are already available either in the target Client or in the Transport Case. If they are available, it creates a link to them. If not, a warning is written to the log file of the AE DB Load utility. When loading User Groups, the system neither checks whether their Users are already available nor creates any links to existing ones. Therefore, it is recommendable to transport User Groups first and load the Users afterward in a separate transport file.

  • Transporting authorizations at object level

    On the Authorizations Page of the object definition, Users are granted rights at object level. You can transport these authorizations by using the start parameters of the AE DB Load utility. By default, the transport is canceled if the specified Users are missing. This default behavior can be changed with the corresponding start parameters. Therefore, it is recommendable to transport Users first. For more information, see Defining the Authorizations Page.

  • Loading Notifications

    Users and User Groups are used in Notifications. If you transport these objects at the same time, it is possible that Notifications are loaded first. In this case, the system starts searching for the Users or User Groups used in those Notifications. If they are not yet available, the Notifications are loaded but without the User and User Group references. Therefore, load Users and User Groups first and Notifications in a second loading process in a separate file.

  • Loading Authorizations

    When transporting authorizations at object level, the transport is by default canceled if the specified users are missing. The administrator can change this default behavior by using the corresponding start parameters of the loading program AE DB Load. For more information, see Defining the Authorizations Page and AE DB Load (UCYBDBLD.EXE).

  • Transporting Calendars

    Let's suppose that you want to transport Calendar A, which uses Calendar Events defined in Calendar B. For Calendar A to work properly in the target system/Client, you must also transport the Calendar Events it is referencing even if you are not going to transport Calendar B.

    Calendar objects are re-calculated after each transport, see Calendars (CALE). This can cause occasional error messages in the log file if the Calendar was re-calculated before the Calendar Events it uses have been read. These messages can be ignored because there is a subsequent calculation of Calendar Events without any manual interference being required.

See also: