Distribution of Modifications
8 minute read
Underlying Principle
In Docusnap, it is possible to export customizations made to the database structure, the meta objects and the data entry screens and to apply them to other databases and Docusnap installations without much effort by importing them in the other environment.
You can export and import customizations via the Docusnap Management.
Namespace
Namespaces in customizing mean that each extension of the metaschema (tables, views, data tree objects) can be provided with a namespace. This way, all objects belonging to a larger customizing can be linked to each other. This is especially useful if a specific customizing should be exported and other customizings exist in this database. In the course of the export, the specific namespace can now be selected and the associated tables, views and data tree objects exported.
Exporting the Database Structure and the Meta Objects
In order to export a meta schema, Docusnap must be connected to the database that contains the corresponding schema. By clicking on the Export schema button in the Customizing area, the Export metaschema dialog is opened. In the Path field, a storage location can be selected. In the field Namespace it is selected whether All or only a certain namespace should be exported. If a namespace is selected during export, all objects, tables and columns of this namespace and those with empty namespaces are taken into account. By clicking the Export button the current schema will be exported. A new file with the extension .dsu is created at the selected location, which contains the customizations made to the current Docusnap database.
Importing the Database Structure and the Meta Objects
Previously exported customizations of the meta schema can be imported into another database using a wizard. To do so, Docusnap needs to be connected to the target database at the time of the import process. By clicking the Import Schema button on the Customizing area, you can open the associated wizard that helps you specify further settings.
If a namespace was used when exporting the customizing, the import dialog now also shows which object is assigned to which namespace.
Select File
The first step in the wizard is to select the previously exported file which contains the modified meta schema. When you click the button, a file selection dialog opens where you can open the desired .dsu file.
Check Objects
The second step of the wizard displays all meta objects contained in the selected file that will be imported. All objects contained in the file are taken into account. Due to potential dependencies between the objects, manual selection is not possible at this point. If certain objects are not needed, they can be removed after the import is complete in the Manage Objects area.
Before importing, Docusnap checks whether there are any conflicts with existing objects in the database. It checks whether the object name and object type ID already exist. Such conflicts are highlighted with a red symbol and a corresponding error message.
Typical Conflict Cases
Object name and object type ID already exist
This case occurs when a meta schema is imported again – usually with content changes or extensions. In this situation, both the object name and the object type ID match existing entries.
Recommended solution: The option Overwrite existing objects (name & type ID already exist) should be used. This ensures that existing nodes are not newly created, but specifically updated. The existing structure remains intact, and new content from the import is added or replaced as needed.
Object type ID already exists
In this case, the object type ID used in the import is already assigned in the database – but for an object with a different name. This may have been caused, for example, by your own customizing or by other meta schemas.
Recommended solution: Use Resolve object type IDs with conflicts dropdown to select the option Reassign object type IDs with conflict. This will automatically assign all affected objects with new, available type IDs. This ensures that existing objects remain unchanged and that the import model is cleanly integrated.
Object name already exists
This situation typically occurs when a meta schema was previously imported and new type IDs were assigned during that process. If the same meta schema is later imported again – for example, after extensions or modifications – the object names match those in the system, but the type IDs do not.
Recommended solution: From the Resolve object type ID conflicts dropdown, select the option Assign object type IDs from the database based on the object name. This way, the objects in the import are linked to the already existing type IDs – provided the names match. The existing structure is then recognized and extended instead of creating new, duplicate nodes.
Checking individual nodes before applying a global solution
Before applying a global conflict resolution, all imported nodes should be carefully reviewed. It may be necessary to edit certain objects manually – for example, if they have been specifically customized or are used multiple times.
By clicking Adjust object, the corresponding edit dialog will open. There, the object name can be changed or a different type ID can be assigned. To resolve a conflict with the object type ID, it is recommended to use the Next free ID button to automatically assign an ID that has not yet been used.
Check Tables
The third step of the wizard lists all tables that are present in the selected file and that will be imported into the target database. The following figure shows a table called xtServiceLevelsSLA which does not exist in the Docusnap system schema. The tHosts table, in contrast, belongs to the system schema. A field was added to it where users can enter additional information.
The Metatables to be imported list displays all tables that are either user-defined or have been customized by adding user-defined fields or by editing existing fields. When you select a table in the upper list, all added or modified columns of the selected table will be displayed in the Fields of Selected Table list below.
If a table does not yet exist in the target database, the table will be created with all its fields. If the table already exists, this list shows only the columns that are still missing. Docusnap will never delete fields that, while existing in the database, are not associated with that table in the schema file. All tables and fields will be imported during the import process. It is not possible to exclude individual tables or fields from being imported.
If a field already exists in the target database, but has a different data type than that of the definition in the import file, the field will be highlighted in red in the corresponding list. When you click the table in the upper list, Docusnap will display the columns in the lower list, highlighting the fields that still have problems in red. To perform the import process, change the data type in either the target database or the source database. However, the data type can only be changed by deleting the affected column and re-creating it with the other data type. Please note, that all data in this field will be deleted from the database. If you change the field in the source database, you need to re-export the schema file to make sure that the updated data will be imported. If you change the field in the target database, however, it is sufficient to only delete the field, since it will be re-created by importing the source file, this time with the appropriate data type from the source database.
Summary
The last step of the wizard shows a summary of all objects and tables to be imported. By clicking the Back button, you can change the selection, if required. To import the objects and tables into the target database, click the Finish button.
Distributing Data Entry Screens
Customized or newly created data entry screens are not automatically distributed by means of a wizard, since they are independent from the database in use. Instead, they will be loaded from the respective local or team settings. In order to make these changes available to multiple users, these users need access to the corresponding .dsu files. If team settings are used, it is usually sufficient to copy the modified .dsu files to the DataEdit subdirectory of the team settings directory, unless this has been done automatically when saving the data. If local settings are used, the corresponding files will always have to be distributed manually.