Tutorials

This section shows some tutorials on how to use and modify mDIS.

Add values to a list

In a form fields that contain value lists are recognizable by a little 'sheet icon' next to the input field.

To select a value, click into the input field:

💡 Tip: There are two different kinds of value lists: single select and multiple select

To edit the entries of the value list, click on the button next to the input field:

• To add a new value, fill out the fields on the top 'Abbreviation', 'Description', 'Sort Index' and click on the button "Create". 'Abbreviation' will save the value in 'Display' and 'Description' will save into 'Remark'.
• To edit an existing value click on the pen button, change the values and click on "Save".
• To delete an entry, click on the delete button and confirm.

Import values to an existing value list

In case a lot of new values should be added to a list, it would be very cumbersome to enter each value individually. Therefore, an importer for value lists is available.

1. Open the sidebar and choose "File Upload".

   

2. Upload csv-file to upload directory

   • Either click on the area with the bluish dotted line and select the file on your system or drag & drop the file into the area. -> The uploaded file occurs in the upload directory.

     TIP

     Make sure that the .csv-file follows the template for upload. Don't delete or rename column headers. The columns must be ";" separated. The list_id must be an existing list in the database. Ask the mDIS administrator for help, if it is not clear where to find this ID.

   

   • Check the box next to the uploaded file and scroll to the bottom of the page.

3. Import value list

   

   • Click "IMPORT DATA".

   • A dialogue box will open. Click on the red highlighted "Importer" and select "Import CSV for Value Lists (DisListItem)".

   • First, only test data. The box of "Only test data, do NOT import" should be checked by default.

   • Click "START IMPORT"

     

   • A new tab should open, telling you that the test was okay. Close this tab again.

     

   • Uncheck "Only test data, do NOT import" and select "Stop at first error".

   • Click "START IMPORT"

   • A new tab should open, telling you that the import was successful.

     

4. Check if new values are available in the list

   • Open the form where the list with the new values is available and click "NEW" or "EDIT".

   • Either start typing one of the new values in the field which contains the value list.

     

   • Or click on the sheet icon next to this field.

     

   • The list will open.

   • Check, if the new values are available. They usually are listed at the top.

Import records to an existing table

In case a lot of records should be added to a table, it would be very cumbersome to enter each record individually. Therefore, an importer is available.

1. Open the sidebar and choose "File Upload".

   

2. Upload csv-file to upload directory

   • Either click on the area with the bluish dotted line and select the file on your system or drag & drop the file into the area. -> The uploaded file occurs in the upload directory.

     TIP

     • Make sure that the .csv-file is prepared correctly. All pseudo fields must be omitted and the columns must be ";" separated.
     • Also be aware that the combined_id needs to be filled in the document. Otherwise the parent ID for the parent record must be filled.
     • It is easier to prepare the table, if it is exported in 'Export full records as CSV file' with at least one record as placeholder and modified that for import. Ask the system administrator for help if necessary.

   

   • Check the box next to the uploaded file and scroll to the bottom of the page.

3. Import values

   

   • Click "IMPORT DATA".

   • A dialogue box will open. Click on the red highlighted "Importer" and select "Import CSV records for one table".

   • Also specify to which table the data should be added. E.g. select “CurationSectionSplit”.

   • First, only test data. The box of "Only test data, do NOT import" should be checked by default.

   • Click "START IMPORT"

     

   • A new tab should open, telling you that the test was okay. Close this tab again.

     

   • Uncheck "Only test data, do NOT import" and select "Stop at first error".

   • Click "START IMPORT"

   • A new tab should open, telling you that the import was successful.

     

4. Check if new records are available

   • Open the form where the new records were added to.
   • Either filter for the new records or open the 'list of records' and look manually for the new records.

Install offline mDIS (virtual box on Windows)

WARNING

Please make sure that you have administrator privileges on the host system and are allowed to install new software.

This guide shows how to set up your PC for using mDIS with Virtual Box Manager.

TIP

This guide is valid for Windows 10 and Virtual Box Manager 7.0.

Name	Definition
Host	Computer on which Virtualbox is installed
Guest	Virtual computer emulated by the Virtualbox Service/Process running on the host computer.
VM	Virtual Machine, appears to run "inside" the host.
.ova-file	A single file containing exported VM configuration, Guest Operating System, mDIS components, and data such as predefined mDIS users (initially, no Science Data)

Installation

In order to install and run a virtual box on a Windows operating system, some things need to be checked and modified. Those tasks are only necessary once.

1. Ensure that the hardware support for Virtualization is set to “enabled” or “on” in the BIOS.

   Otherwise the VirtualBox software will not run, or will be extremely slow.

   • When the computer is booting up from the black screen, press Delete, Esc, F1, F2, or F4. Each computer manufacturer uses a different key but it may show a brief message at boot telling which one to press. If you miss it the first time, reboot and try again. It helps to tap the key about twice a second when the computer is coming up. If you are not able to enter the BIOS via this method, consult your computer’s manual.
   • In the BIOS settings, find the configuration items related to the CPU. These can be under the headings Processor, Chipset, or Northbridge.
   • Check if virtualization is enabled; the setting may be called VT-x, AMD-V, SVM, or Vanderpool. If disabled, enable Intel VT-d or AMD IOMMU if the options are available.
   • Save your changes and reboot.

2. Make sure that Microsoft’s Hyper-V is turned off

   Hyper-V and the virtual box management software cannot co-exist. Virtualbox guests will not boot.

   • To disable Hyper-V , go to "Control Panel" -> "Programs and Features" -> Left Sidebar -> "Turn Windows Features On and Off".

   

   • A long selection list of optional Windows Features will appear. Check off "Hyper-V". Check the list for more entries containing "Virtualization". Turn them off as well.
   • Reboot the Windows Host.

3. Download and install the current version of the free VirtualBox software

   • https://www.virtualbox.org/wiki/Downloads (opens new window)

   

   The VM requires around 10GB of hard disk space on the host. When entering data and uploading files, the required hard disk space will increase.

   • Run the platform packages installation and follow the instructions. After finishing the installation successfully, install also the Extension Pack. With the newest versions the Extension Pack may be already included in the main installation and does not be installed separately.

4. Set up Network Preference and Port Forwarding of the Virtual Box Manager (Version 7.0)

   • Open the Virtual Box Manager by double clicking on the icon.
   • Go to File (upper left corner on the screen) -> Tools -> Network Manager
   • The Network Manager opens.
   • Open the tab "NAT Networks" (red arrow 1). If no network is available click “create” (red arrow 2) and then “properties” (red arrow 3).

   

   • The "Properties" open at the bottom of the screen. There are two tabs “General Options” and “Port Forwarding”. In General Option you can rename the network. Make sure DHCP is enabled. Then go to “Port Forwarding”.
   • Manually enter the port forwarding rules according to the screenshot below. To create a new row click the green plus on the right side.

   

   WARNING

   Keep in mind that the guest IP needs to be changed to reflect the running VM system. If the Virtual Box is restarted and mDIS cannot be accessed from the host system, check if the guest IP has changed!

5. Import and adjust an existing Guest Virtual Machine

   A pre-configured basic Virtual Box will be provided by the OSG team during the Data and Sample Management Course. That box is a .ova file type and needs to be imported into the VirtualBox Manager.

   • Open the VirtualBox Manager and click on File on the upper left corner -> Import Appliance.

   • A new window opens. Select the .ova file and click next.

   • The next window shows you the appliance setting. Usually, it is not necessary to change anything. But it may be handy to rename the appliance, e.g. to avoid duplicates. To rename, double click on the name displayed in the virtual system. It is also possible to modify the storage location of the base folder which will host the virtual machine. Click on the path (C:\Users\Username\VirtualBox VMs) and choose another directory. That can be useful, if you are working on a computer with more than one hard disk partitions and limited hard disk space.

   • Then click “Import”. The import will need several minutes depending on the size of the box.

     

   • The next step is to adjust the settings to fit the computer. Most setting are already made and don’t need to be changed, but a few adjustments are necessary. Right click on the imported box and choose settings.

   • A new window with a sidebar on the left opens. In “General” the mDIS appliance can be renamed.

   • In “System” it is possible to change the Base Memory, CPU, etc. Usually don’t change anything, but make sure that at least about 2 Gb of RAM are assigned for the virtual machine guest.

   • In “Network” make sure that the right Network is chosen. That should be the Network you had defined in your VirtualBox Manager before, e.g. mDIS NatNetwork.

   • In “Shared Folder” make sure that the directory to your Upload folder is correct. Double click on the name and choose the correct directory. If no Upload Folder exists, enter a new one in any location (e.g. C:\Users\UserName\Documents\Upload). Make sure the folder is named "Upload". Click ok.

     

   TIP

   The Uploads folder allows the communication and the data exchange of the Host System (Windows, Mac, etc.) with the Guest System (Ubuntu). That means that whatever files (excel, png, pdf,…) you want to import into mDIS needs to be stored here first.

6. Start and adjust the virtual box

   • To start the box select it in the Virtual Box Manager and choose start. Wait for the system to boot. The credentials for login will be given to you during the Data and Sample Management Course.

     

   • There are two things that needs to be checked and adjusted.

     1. Make sure that the PC timezone settings are the same as the timezone you are working in. mDIS safes all times in UTC calculated from your PC time.
     2. Make sure the keyboard layout fits your needs.

     WARNING

     It may be necessary to have sudo rights (like administrator rights in Windows) in order to be able to change anything. Make sure to have the password.

   • In order to change either the timezone or the keyboard layout, click on the 3x3 grid in the lower left corner of the Ubuntu desktop.

     

   • An overlay opens. Type 'date time' in the search field -> click enter and select "Date & Time".

   • A new window with the Date & Time settings opens. Select the timezone of the drill site.

     

   • To change the keyboard layout, click on the language abbreviation in the upper right corner of the Ubuntu desktop and select the correct layout.

     

   • If the correct layout is not available, click on "Keyboard Settings"

   • A new window opens. Add a new keyboard layout, clicking the + icon. Close the window.

   • Now the new keyboard is available from the desktop.

     

7. Port forwarding within the virtual box

   • If only a single person will work in the box, everything is good to go now. Open a browser in the virtual box and type in localhost. The mDIS login screen will open.

   • But, it is also possible to access mDIS from the host system's internet browser or it can be used in a local network giving different persons on different computers the possibility to use mDIS simultaneously. In that case check the port forwarding settings.

   • On the lower right corner of the Ubuntu Desktop are several icons. Hover above the network symbol with the mouse (see arrow). An overlay with the IP address becomes visible. Write down this address.

     

   • Open the "Port Forwarding" tab in the Virtual Box Manager again. File -> Tools -> Network Manager -> tab "Port Forwarding".

   • Check if the Guest IP4-Address matches with the Guest IP in the Port Forwarding tab. If yes, do nothing. If no, update the Guest IP by double clicking it and manually change the Guest IP4-Address. Press Apply.

   • If mDIS is used on the Host-System of the same computer where the VirtualBox is running, just open a browser and type “localhost:8888” in the address line -> click enter.

   • If mDIS is used from another computer, make sure it is in the same network and that the computers in the network are visible. Then open a browser and type in the IP4-Address of the Host-System (not the Guest IP in the virtual box!). -> click enter.

   💡 Where to find the IP4-address of the host system: In Windows click on Start Menu, type cmd in the search box and press enter. A terminal window will open: type 'ipconfig /all' and press enter. A long list will appear. Look for the IPv4 Address. If internet is available open a search engine in a browser and type 'what is my ip'-> press enter.

Template Manager

WARNING

Only users with developer or administrator rights are able to work with the template manager.

The Template Manager allows to create, edit or delete tables and input masks directly in mDIS with no programming skills. It is accessible by selecting 'settings' (1.) in the burger menu. To open the Template Manager click on 'GO TO TEMPLATE MANAGER' (2.).

The Template Manager opens on the main page containing different elements:

1. Cards of models and forms: Each card contains a database table, some modifications (e.g. behaviors) and the input masks (forms). It is possible to download, duplicate, edit or delete models and forms separately.
2. Filter: There are a lot of different cards available. It is possible to filter for a selection of cards by the corresponding Table Set.
3. New data model template: That is the starting point for creating a new model. Select an existing Table Set or define a new one by just typing a new Table Set name in the Table Set field and press 'create'.
4. Upload: It is possible to upload already existing models and forms from other mDIS instances. Just drag and drop the downloaded files into the area surrounded by a greenish dashed line.

Modify tables with the Template Manager

As mDIS developer or administrator (e.g. at an offline drill site) it can be necessary to add some columns or change the datatype of a field.

1. Open the Template Manager.
2. Filter for the Table Set that contains the table to be modified (e.g. Geology). Within the Table Set Geology only 3 cards remain available.
3. Click 'edit' (orange pen symbol) on the card to open the model.

A model opens that contains 5 basic elements:

1. Model overview: Shows the name of the Table Set, the name of this data model and the name of the database table. Furthermore, the parent data model can be selected or edited if necessary.
2. Columns: Select existing columns to modify or add a new one by pressing 'ADD COLUMN'.
3. Indices, relations and behaviors: Here it is possible to specify links to data in other tables (relations) or to add an automatic counter for a columns (behavior). For more information have a look at the mDIS Template Manager section of the documentation.

Edit existing columns

To have a closer look at an existing column, click on the little triangle on the far right side next to the column name. The details of this column will open. It is possible to rename the column, the label and the description, which is displayed in the input mask. Furthermore, it is possible to change the data type (e.g. from string to integer), define a maximum character size or if this column is required. The validator is only useful for integer or double data type fields to define that e.g. a value is always positive (>0). The unit of the value can be entered, e.g. meter [m], in Unit or it is possible to define a Default Value, which will prefill this field on opening a new record. Calculate (PHP code) is more complex as it is necessary to have at least basic programming skills.

After editing columns, scroll to the end of the model page and click 'SAVE & GENERATE'

Add a new column

To add a new column click on 'ADD COLUMN' on the top of columns. A popup appears to enter the column name. After doing so, click 'OK'. The new column appears at the end of the column list. Open it with a click on the little triangle next to the column name. Fill all fields that you want to fill and select the appropriate data type.

If all new columns are added, scroll to the end of the model page and click 'SAVE & GENERATE'

TIP

It is also possible to create completely new models. Select a Table Set or type a new one in the 'New data model template' box and press 'create'. A new model without any columns will open. Adding columns works like explained above. The set up of relations and behaviors is a more advanced task. This is explained in detail in mDIS Template Manager.

Modify input masks with the Template Manager

WARNING

Only users with developer or administrator rights are able to work with the template manager.

tdc