View source for HowTo:Transfer Data from UBIK 3 to UBIK 4

With {{UBIK}} Server version 4, much has changed on database level. We had to sacrifice direct downward compatibility with respect to older database versions in order to gain new possibilities (see [[Dynamic_Live_Mode]]).

In order to upgrade a {{UBIK}} Environment from version 3.7 to version 4, it is necessary to create a new database and to transfer the data from the old database to the new one. Here's how.

<!-- DO NOT REMOVE THIS -->{{Template:HowTo/Begin}}<!-- DO NOT REMOVE THIS -->

= General =
== Enhanced Instance Data Transfer ==
Since Version 5.0.0 the Instance Data Transfer has been enhanced.
* The Instance Data Transfer now supports transfers from any source database (version 3.7 or later).
* Instances that have changed in the source system since the last transfer will be updated in the target system when performing a new transfer.


A detailed description of how to transfer data from an {{UBIK}} 3 environment to an {{UBIK}} 4 is provided in the "Transfer Data from UBIK 3 to UBIK 4" tab.

[[Category:How-To|Transfer Data from 3.7 to 4.0]]
[[Category:Install|Transfer Data from 3.7 to 4.0]]
[[Category:Installing|Transfer Data from 3.7 to 4.0]]
[[Category:Server|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.0|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.2|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.3|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.4|Transfer Data from 3.7 to 4.0]]

= Transfer Data from UBIK 3 to UBIK 4 =
<!-- DO NOT MODIFY THE NAME OF THIS SECTION, BUT REMOVE IT IF NOT REQUIRED -->

== Save all meta definitions to a SmartStudio Project ==
* Make sure the database is updated to 3.7.3 (recent fixes in uids require a database update to this version)
* If you don't need the CUI plugin, delete all meta classes related to CUI from your 3.7 database before continuing. The same is true for any other structure or content you don't want transferred.
* Make sure your SmartStudio version 3.7 has all the plugins required for your project.
* Open SmartStudio version 3.7.
* Open a new, empty Project.
* Connect to the old {{UBIK}} 3.7 Environment.
* Open a new Transport Container worksheet.
* Right-click to open the context menu and click "Load all MetaClasses".
=> Now, all MetaClasses and MetaProperties are added to the Transport Container. This can take a while.
* After loading all the meta definitions is finished, save the Transport Container to the Project.
* Save the Project to the file system.

{{Hint|Make sure to use the newest SmartStudio versions from the release portal (also for 3.7)!}}

== Create an empty {{UBIK}} 4.0 database ==
* Create a new, empty database for your {{UBIK}} 4 Environment. It has to be on the same server as your old database (or a copy thereof).
* Make sure your SmartStudio version 4 has all the plugins required for your project. 
* If you haven't removed the CUI meta classes from your 3.7 database before loading the meta classes into the SmartStudio project, you also need the CUI plugin.
* Open SmartStudio version 4.
* Open the previously created Project.
* Connect to the new (and empty) {{UBIK}} 4 Environment.
=> SmartStudio now asks you to upgrade the empty database to version 4. Confirm the upgrade dialog. {{UBIK}} now creates all the basic system definitions in the previously empty database.

{{Hint|You might get an MSDTC related error. In that case you need to enable the MSDTC: https://learn.microsoft.com/en-us/biztalk/adapters-and-accelerators/adapter-sql/configure-msdtc-on-sql-server-and-adapter-client}}

== Transfer the previously copied meta definitions ==
* Open the Transport Container with all the 3.7 meta definitions from the Project.
* Merge & Save the Transport Container to the Environment.
=> All the meta definitions should be available in the new {{UBIK}} 4 Environment. Now we just have to transfer the instance data.

{{Hint|Known issue: SmartStudio assumes the relation data meta class of a relation has the same name. If the relation was renamed (but not the data meta class), a new data meta class with the same name will be created for the relation. In that case, you might have to set the correct data meta class after the transfer (all meta classes are transferred, just the reference might be wrong). The new data meta class with the same name as the relation can be deleted then.}}

{{Hint|Known issue: SmartStudio doesn't know about the Meta Property's "Serialize" property, which adds an additional column for file references. After migrating the meta definitions to your {{UBIK}} 4 Environment, please set this property to true manually if needed. }}

== Remove obsolete MetaClasses ==
* Some old meta classes have been transferred, but we can just delete them:
** System.Main.SYSTEMSETTINGS

== Make sure all languages are configured ==
* Open the Bulk Editor for the Language Meta Class (using SmartStudio or regular Studio) in your new 4.0 Environment.
* Enter all required languages (if you had more than 2).
* It is only important that there are enough languages, you can modify them afterwards.
=> Now, there should be as many languages as there were in the old 3.7 Environment.

== Transfer all instance data ==
* Open the "Instance Data Transfer Wizard" using the "Environment" menu.
* Follow the wizard's instructions until the end.
=> The wizard copies all the instance data from the old 3.7 Environment to the new {{UBIK}} 4 Environment.

{{Hint|If the transfer keeps failing after some time, the maximum transaction timeout configured on your machine might be the issue: https://stackoverflow.com/a/21274884 or https://thecodesaysitall.blogspot.com/2012/04/long-running-systemtransactions.html }}










== Maintain languages ==
* All languages have been transferred from the old 3.7 Environment.
* Now, there might be duplicate entries. 
* Remove all language objects you don't need and make sure the details (index, primary language) are set correctly.
=> Now, all translations should be displayed correctly; please check.

== Optional: Maintain customizing ==

In case your customizing doesn't compile even after removing the obsolete meta classes, this might help.

* Copy your custom code library from your old DB to the new one.
* If a class cannot be found, please make sure it doesn't have the namespace "System". Alternatively, you can use "Sys." as a prefix in the custom code to find the class.

Also, some method signatures have changed, so we have to adapt custom code if these methods are used:

* For most View related methods, the parameter "bool sorted" does not exist anymore; it can be removed.
* The UBIKClassList does not derive from List anymore. If you're using it as List in your custom code, you have to adapt this, using UBIKClassList instead.

If you're stuck, please ask a developer.

== Optional: Maintain system object customizing ==
Most likely, you won't need to do anything here, but if you changed system meta objects in your old 3.7 Environment, additional adaptions might be necessary.
* In the unlikely event that there were custom changes to system objects like the NAMEDBASECLASS, please check whether anything is missing.
* Custom property values or relations must be amended manually.
* Custom code and icon can be restored by linking to the correct Display Data object, which was transferred.
* Ask a developer if you need help.

<!-- DO NOT REMOVE THIS -->{{Template:HowTo/End}}<!-- DO NOT REMOVE THIS -->

[[Category:How-To|Transfer Data from 3.7 to 4.0]]
[[Category:Install|Transfer Data from 3.7 to 4.0]]
[[Category:Installing|Transfer Data from 3.7 to 4.0]]
[[Category:Server|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.0|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.2|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.3|Transfer Data from 3.7 to 4.0]]
[[Category:Version 4.4|Transfer Data from 3.7 to 4.0]]