---
title: "MXSyncUtility User Manual v1.4.3"
canonical: "https://servicedesk.maxgeo.com/space/LogChief/2214625291/MXSyncUtility%20User%20Manual%20v1.4.3"
format: markdown
---
# TABLE OF CONTENTS
> Macro (toc)
**Licence Agreement**
The use of DataShed5, DataShed5Admin, MXSyncService and MXSyncUtility is subject to a licence agreement with maxgeo. The software may only be used or copied in accordance with the terms and conditions of that agreement.
**Disclaimer**
maxgeo will not accept any liability arising from the use of DataShed5, DataShed5Admin, MXSyncService and MXSyncUtility software or any other software product mentioned in this manual, nor for any technical or editorial errors or omissions in this manual.
# > Macro (anchor)
Introduction
Synchronization is an integral part of the maxgeo cloud solution. It provides a means for transporting data from remote systems to a centralized hosted environment and for interrogating the hosted system for relevant operational data. The MXSyncUtility software provides a client-side interface and transport mechanism for synchronizing data to and from the DataShed5 hosted environment via the MXSync Service.
> Macro (anchor)
Figure 1 - Synchronization HLD> Macro (anchor)
> Macro (anchor)
## > Macro (anchor)
Acronyms and Abbreviations
| | |
| --- | --- |
| Acronyms | Definitions |
| DB | Database |
| DMZ | Demilitarized Zone. A physical or logical subnetwork that contains and exposes an organization's external-facing services to a usually larger and untrusted network (e.g. the Internet). |
| HLD | High Level Design |
| HTTPS | Hypertext Transfer Protocol. A protocol for secure communication over a computer network which is widely used on the Internet |
| MDS | Maxwell Data Schema |
| MX | maxgeo |
| URL | Universal Resource Locator. A reference or address to a resource on the Internet |
> Macro (anchor)
## > Macro (anchor)
Definitions
| | |
| --- | --- |
| | Definitions |
| DataShed5 | A solution which gives Maxwell cloud customer web-based access to the Hosted MDS data. |
| DataShed5Admin | A solution which gives maxgeo cloud customer web-based access to administer DataShed5 access |
| MXSyncService | A solution which gives Maxwell cloud customer an interface for accessing MDS data via REST API methods. |
| MXSyncUtility | maxgeo Synchronization Utility that communicates with the MXSyncService. |
# > Macro (anchor)
Technical Requirements
## > Macro (anchor)
Hardware Requirements
- **Processor**: At least Multi Core CPU over 2.0GHz (Recommended)
- **Memory**: 4GB Ram (minimum)
- **Disk Space**: 5GB Free HDD Space
## > Macro (anchor)
Software Requirements
- > Macro (anchor)
**Windows Operating System**
Windows 7 SP1 (Minimum)
Windows 10 (Recommended)
- **.Net Framework 4.6.1**
## > Macro (anchor)
Database Requirements
- **Cloud Database: MDS 466 Database and later:**
Microsoft SQL Server 2019
Microsoft SQL Server 2020
(Express or Standard Editions) (32 or 64-Bit version)
# > Macro (anchor)
Installation
1. Close LogChief
2. Double click the installer (exe or msi)
3. Click “Next”
4. Read through and Agree to the Software Licence to proceed with the installation. Click “Next”
5. Select Install Folder
6. Installer is ready to Start, Click “Next”
7. Click “Finish” to complete the installation
# > Macro (anchor)
Using the Maxwell Synchronization Utility
## > Macro (anchor)
> Macro (anchor)
Interface Components
The MXSyncUtility is comprised of two main interface components, the main window and the extended configuration window. The main window presents the main visual interface for interacting and analyzing synchronization operations, whilst the extended configuration window provides the options for configuring the application and synchronization settings.
Figure 2 - MX Synchronization Utility
## > Macro (anchor)
Main Window
Figure 3 – Main Window Components
### > Macro (anchor)
Main Menu & Quick Navigation
#### Main Menu
To access the main menu, click the user icon
from the top left of the main window. This will open a menu with the following options as illustrated in Figure 4 - Main Menu Option .
> Macro (anchor)
Figure 4 - Main Menu Options
Table 1 - Menu Options
| | |
| --- | --- |
| Menu Option | Description |
| Modify Host URL… | Modifies the target URL for MXSyncService |
| New Configuration… | Clears the “System Settings” for setting up a new configuration |
| Load Configuration… | Loads a pre-existing configuration file |
| Create Configuration via LogChief | Administrator menu option to generate an MX Sync configuration for a selected LogChief configuration database |
| Change Admin Password… | Opens the Change Admin Password dialog |
| Connect… | Redirects the main window panel to the user login page |
| Disconnect… | Once connected this menu item will allow the user to log out from DataShedWebService. |
| About | Navigates to the application About screen. |
| Exit | Closes the application |
##### Modifying the host URL
The host URL can be modified by selecting the “**Modify Host URL…**” item from the main menu. This menu item is only enabled when the current user is logged out from the MXSyncService. Once the Cloud URL is committed, it will appear at the top section of the “System Settings” form of the extended configuration window. The MXSyncService URL can be requested through the maxgeo servicedesk.
Figure 5 - MXSyncService host URL entry field
##### Loading an existing configuration
To load a configuration, select the “**Load Configuration...**” item from the main menu. As with the “Modify Host URL…”, this menu item is not available if there is a user currently logged into the MXSyncService. When enabled selecting this item opens a file selection window where the user can specify the location of the configuration file to load. Once loaded, the application will save this location into memory for access during application startup.
##### Create Configuration via LogChief
Administrators have the ability to create a new MXSyncUtility Configuration for a selected LogChief Configuration database. Refer to section ***How to Create MXSync Configuration*** for further details.
##### Changing the administrator password
By default, the administrator password is set to “***MXSyncAdmin***”. To change this password, open the main menu and select the “Change Admin Password…” menu item. A dialog window will open like that illustrated below. This option is not available if there is a user currently logged into the DataShedWebService. The minimum requirements for the new password include an 8-character minimum, a number and an uppercase letter.
Figure 6 - Change Password Dialog
##### Connecting to the MXSyncService
Selecting the “**Connect…**” menu item navigates the main window to the login page. Selecting ‘Remember Me’ from this page allows the application to remember the user login and password to enable auto login to the DataShedWebService on startup.
Figure 7 - Login Screen
### > Macro (anchor)
Quick Navigation
The quick navigation provides two screens that are immediately available to the user for monitoring the synchronization process. These can be accessed via the tabbed buttons located in the lower left of the application header (illustrated below).
Figure 8 - Quick Navigation Tabs
#### Monitor Page
Selecting the “Monitor” tab opens the Monitoring page on the main window panel. This page provides the user with session counts of successful and failed synchronizations as well as maximum and average execution times. Stats can be reset by clicking “Clear” for each section or by selecting “Clear All” to reset the entire page.
Figure 9 - Monitor Page
#### System Log
Selecting the “System Log” tab navigates to the system log page on the main window panel. This page provides a live logging console of events as they arise marked with a timestamp. The size of the container for holding the logged events is configurable through the “System Settings”. Once the console exceeds the maximum capacity, it will automatically begin to purge the oldest events in the log. The log can be cleared manually by clicking on the “Clear Console” located at the bottom of the logging console. A more detailed log is provided as a plain text file on disk.
Figure 10 - System Log Page
### > Macro (anchor)
Application Minimization and Window Extension Icons
#### Application Minimization
The application window may be minimized into the system tray by clicking on the icon located at the top right of the main window. It can then be restored by clicking on the Maxwell “Hammer” icon in the system tray. The icon itself will appear red when connected or grey with a cross when disconnected from the MXSyncService.
#### Windows Extended Configuration
The burger icon at the top right corner of the main window allows the user to toggle the extended configuration window open and closed.
### > Macro (anchor)
Status Panel
The status panel provides additional information regarding the current state of the utility. These are described in the following table.
Table 2 - Status Panel Symbols
| | | |
| --- | --- | --- |
| Status | Symbol | Description |
| Last Successful Sync | N/A | Displays the timestamp for the last successful synchronization. |
| Online |  | Connected to DataShedWebService |
| Offline |  | Disconnected from DataShedWebService |
| Automatic |  | Synchronization in Automatic and will synchronize based on the defined poll rate |
| Manual |  | Synchronization in Manual and will synchronize on demand when the synchronization button is clicked |
| Syncing |  | Synchronization in progress |
| Inactive |  | Synchronization is currently inactive |
If Auto Synchronization has been enabled for the configuration (refer to System Settings), then automatic and manual selection is activated through this interface by selecting the Automatic/Manual hyperlink.
Figure 12 - Automatic/Manual selection hyperlink
Once clicked, the application will ask for confirmation of the mode change before proceeding with the action. The text and icon representing the mode will update accordingly.
Figure 13 - Automatic/Manual confirmation dialog
## > Macro (anchor)
User Controls
The user controls panel located at the bottom of the utility provides controls for performing manual synchronization, synchronization wizard, and for accessing system and synchronization configurations. Manual synchronization is available only when in “Manual” mode and when connection is established with maxgeo’s MXSyncService.
Figure 14 - User Controls Panel
### > Macro (anchor)
Synchronize
The **Synchronize** button is mainly used when in Manual Mode. The MXSyncUtility will synchronize records that have been flagged (e.g. MXSynch_Ready = true) within the LogChief Configuration database grouped by hierarchy table mapping. This way, users control when records are synchronized to the Hosted Master MDS. It is very important when creating the MXSync Configuration json file that a field is chosen to use as a flag to identify records ready to be synchronized besides the LogChief_Record_Status.
### > Macro (anchor)
Synchronize Wizard
This is new functionality in MX Synch Utility from v1.3. The main objective of the “**Synchronize Wizard**” window is to easily identify all parent records to flag for synchronization instead of going through different LogChief profiles and groups. Based on the LogChief Configuration Mapping, the wizard shows the hierarchy of tables, with parent records and the number of associated children records that have not yet been synchronized for the selected parent record.
1. **Hierarchy Table Mappings – **A list of tables from the LogChief Configuration Mappings. Identifying the Parent Table based on the MDS Hierarchy Structure and dependent tables.
2. **Hierarchy Parent Table Records** – A list of records from the parent table selected from the “Hierarchy Table Mappings” menu tree. Parent records can be selected regardless of the synchronization flag (e.g. MXSynch_Ready) and data will be synchronized as shown in the table below:
| | | |
| --- | --- | --- |
| Parent LogChief_Record_Status | Parent Records | Children Records |
| 
 |  |  |
| 
 | |  |
3. **Hierarchy Children Tables** – A list of children tables associated to the hierarchy parent table. When a parent record is selected in the above table it identifies the related number of records within the children tables that are awaiting synchronization.
### > Macro (anchor)
System Settings
The system settings can only be configured whilst in manual mode. Any changes to these settings must be saved for the changes to take effect. Selecting “Cancel” will revert any changes made, provided that these changes have not been committed. To modify the system settings, click “Edit” at the bottom right of the window. Depending on access privileges the user may be prompted to enter an administrator password.
#### Administrator Access
To be able to modify the System Settings a user must have Administrative privileges to the software or provide an administrator password. The former works in conjunction with a DataShed5 user account whereby access is granted provided that the user is connected to the DataShedWebService and the DataShed5 user account is allocated a “RemoteAdmin” role. When disconnected, the user will be prompted to enter a password through the dialog window.
#### > Macro (anchor)
Host Settings
The “Host Settings” provide configuration for connecting to the hosted system and is dependent on the definition of the MXSyncService URL. On successful connection to the MXSyncService, the server details allocated to the logged in user can be queried by clicking the “Scan Databases” button. This populates the list of servers available and once a selection is made, populates the list of corresponding databases.
Poll rate (frequency of synchronization) and connection timeout can be configured for host communications. The connection timeout requires reconnection before changes take effect.
The “Enable Auto” setting determines whether users can use the Automatic polling; if not selected then only manual synchronization is allowed.
#### Client Settings
The “Client Settings” provides configuration for connection to the client databases. The local Server instance can be selected from the Server Name drop-down list. Authentication details should then be provided, either Windows or SQL Server Authentication (with username and password).
As with the “Host Settings”, click the “Scan Databases” button to retrieve a list of available databases. The LogChief System and Configuration databases should be selected.
The “Lock Synched Records” setting enables records to be marked as *synchronized* or *locked* in LogChief. *Synchronized* records can be changed and resynchronized, but locked records cannot be changed or re-synchronized. When a parent record is locked, additional child records can be added using LogChief, the parent record will be displayed in MXSync Utility and can be selected in order to synchronize the additional data.
#### Log File Settings
Log files can be specified by clicking “Select File…” and defining the location of the log file. The maximum size of the log file is defined in the “File Size” field in megabytes. Once this file size is reached, the utility begins purging old records to make room for new ones. Similarly, the “System Log Buffer Size” setting defines the maximum size for the system logging console.
### > Macro (anchor)
Configuration (Synchronization Settings)
For Contracts to be synchronized:
1. The MDS table tblContractProjectArea must be populated for each contract.
2. For each user logged into the DataShedWebService via the MXSyncUtility, they must be assigned access to Contracts via the User Access tab in DataShed5Admin
The configuration window provides a summary of the available contracts for use in applications such as maxgeo’s LogChief Application.
It is possible to have multiple contracts on the one system against multiple users in which case all contracts will be displayed in the “Available Contracts” table and the “User Access” column set based on user access.
### > Macro (anchor)
Application Management and Version Control
When working within a larger application framework, the MXSyncUtility can be co-ordinated to respond to the management of application versions from a hosted or cloud based DataShed5 system. Records pertaining to the required versions of the software and system configuration are synchronized down from the host and is checked to ensure compatibility with the current implementation.
Checks against versions are conducted at application start up, on configuration load and at the end of each synchronization sequence. If a version discrepancy is detected, a message is displayed on the ‘About’ screen, System Log console and ‘Monitor’ screen. Links on the ‘About’ and ‘Monitor’ screens provide a means for downloading the intended application service pack as specified by the hosted system.
To download the application service pack, click the Download hyperlink on the About or Monitor pages. Save the executable to disk and execute once download has completed. A dialog window will indicate the download completion.
The service pack is a self-contained file that contains the latest software update as well as the latest configuration. Depending on what needs to be updated, the service pack will determine whether to install the application and load the new configuration, or just load the configuration on its own. Once the install has completed, there should be no message displayed on the ‘About’ or ‘Monitor’ screens.
The new configuration file is saved in the following location:
C:\Users\Public\Documents\Maxwell GeoServices\MXSyncUtility\.json
## > Macro (anchor)
LogChief MXApp Plugin
The latest version of the MXSyncUtility can be launched through LogChief MXApp Plugin section of the main window. The main objective is for the plugin to send the LogChief Configuration connection string to MXSyncUtility and automatically populate the Client Settings in the System Settings. This will ensure the MXSyncUtility is connected to the correct LogChief System and Configuration database where the user is logging data.
This will be effective when users import the same LogChief Configuration multiple times with different database names. However, if the next selected LogChief Configuration has a different mapping a new configuration will need to be created or loaded.
Launching the MXSyncUtility through the LogChief MXApp Plugin will prevent the user from select the following LogChief Menu options:
## > Macro (anchor)
How to Create MXSync Configuration
### > Macro (anchor)
Overview
In order to synchronize and import data between the LogChief Configuration database and the remote MDS cloud database, the MXSyncUtility uses a JSON configuration file. This configuration file can be created for any selected local LogChief Configuration database.
In order to use MXSyncUtility to synchronize data from the LogChief Configuration database to the Host MDS database, the data needs to be flagged in LogChief as “ready to be synchronized”. This can be achieved by using a new checkbox column called “MXSynch_Ready” and adding this column to the parent record on the required profile.
The steps below detail how to create the MXSync configuration and synchronize data using the example Profile called *Drilling*.
### > Macro (anchor)
Steps to Create MXSync Configuration (json file)
#### Add MXSynch_Ready field in required Profile
1. Edit Profiles >> select Profile Name = Drilling. Click ‘Next’.
1. Select Collars Groups/Views >> Expand Collar – tblDHColl >> Select MXSynch_Ready column and add it to the View Fields on the right-hand side (as seen in image below).
1.
2. Click ‘Next’ all the way to the end and ‘Save’. The MXSynch_Ready field will be visible in the Logging Screen of the Collar. *For ease of use, you may wish to move the MXSynch_Ready column to the left of the grid.*
1. Enter Data into LogChief and select the records to be synchronized by ticking the MXSynch_Ready column.
## > Macro (anchor)
Launch MXSyncUtility
1. ***Modify Host URL***
1. ***Connect*** to MXSyncService.
1. ***Edit ***the System Settings. Enter the Host and Client Settings and Save the file. Client Settings will allow you to select local SQL Servers and Authentication Type for the LogChief Configuration Database.
1. Open Menu and select ***Create Configuration via LogChief***
1. Configuration Window appears with list of parent level tables in the Synchronize and Import tabs.
1. Select the required tables for Synchronizing and Importing.
*Note: When a table is selected for Synchronizing, all the associated library table data will be automatically imported where changes have been made in the host database since the last import.*
Apply Filters where necessary.
*B**y default, the column MXSynch_Ready is selected as a Filter if the table has this column.*
1. Click ***Create Configuration***. Once the Configuration is created it will create a pop-up window to save the configuration file. Select the file where you saved the system settings. Prompt for Replace >> OK.
1. Load Configuration Prompt window
1. Click **Yes, **will load the current configuration connected for syncing. And requires re-login to the DataShed Web Services.
1. You are now ready to synchronize data from your LogChief Configuration Database via either **Automatic** or **Manual Mode**. Through Manual Mode via **Synchronize** or **Synchronize Wizard**.
1. Data appears synchronized in LogChief.
# > Macro (anchor)
Planned Collar Workflow
The work flow diagrams below depict the processing required for Planned Collars moving from status of “Planned” to “In Progress”, logging data and amending the Max_Depth on a hole. The workflows shown are for the following:
- The **Administrator** to enable Planned Collars to be distributed to LogChief users by synchronising from the MDS to the LogChief Configuration database, and
- The **User** to log data, including the update of the Max Depth of a Collar record in LogChief, and synchronization of data with the MDS
The success of synchronising planned collars and creating collar records depends on the workflow being followed. With this process:
- the Planned Collar record is synchronised from the MDS to LogChief,
- this triggers the creation of the Collar record in LogChief
- the Collar record is then synchronised back to the MDS from LogChief, with any associated data.
Note, that the Collar record should NOT be manually created in the MDS. If the Collar record is manually created in the MDS, then any details will be overwritten with details from LogChief when synchronised with MX Sync Utility occurs.
**ADMINISTRATOR**
The following steps need to be performed by the Administrator for first-time use of the MX Sync Utility:
- As shown above, from DataShed5Admin, in order to use the MX Sync Utility users must be given access to WSServiceConsumer role.
**ADMINISTRATOR**
As shown above,
- Using MDS/DataShed4, the Administrator should identify all Planned Collars which need to be distributed to LogChief; Set **Distribute** flag to True
- Start LogChief, select configuration, and select MX Sync Utility
- From MX Sync Utility,
- Set the **URL** and **Host** **Database** **settings**; This provides settings required in order to gain access to your MDS database
- Create MX Sync JSon Config for LogChief: This uses your LogChief Config database to determine the tables which need to be synchronised between the LogChief Config database and the MDS
- Make **Upload** and **Download** selections and provide appropriate filters e.g.
tblDHCollarPlanned where Hole_Status = ‘PLANNED’ and Distribute = ‘True’
- Save and Re-Load the Json file
- You now have a JSon configuration file ready for use by the MX Sync Utility.
**USER**
As shown above,
- Planned Collars which have been flagged for Distribution will be synchronized to LogChief Config database from the MDS
- The Planned Collar will be updated to Hole_Status of ‘INPROGRESS’
- This will trigger the creation of the Collar record with a Hole_Status of ‘INPROGRESS’
- Data can be logged in LogChief for the relevant Holes
- The Max_Depth on the Collar record can also be updated past the Planned Depth and synchronised back to the MDS
- When ready, data can be synchronised between the LogChief Config database and the MDS
**Synchronise Process**
The diagram above depicts the MX Sync Utility processing workflow (shown in the Workflow User diagram at label MX) :
1. **Validation**: of the LogChief tables and Columns against the MDS tables and column
2. **Download**:
1. Download of all relevant Library data (to the LogChief Config database) which has been inserted or updated in the MDS since last synchronized to LogChief.
2. Download of any selected data for Importing; this data may be filtered e.g. Planned Collars
3. **Upload**: Upload of data from LogChief to the MDS, which has been selected for synchronising e.g. Collar data, Survey data etc.
# > Macro (anchor)
Best Practices, Common Issues and Support Assistance
1. **Timeout Error **occurs when downloading data.
If this issue is encountered, then:
1. Check the configuration, for the data you are trying to Import
1. Did you include an appropriate filter on the table, so that only the required records are downloaded? If required, include a filter, e.g. to only download ‘Planned’ collars or Active records etc. After modification, retry.
1. If the filter *is* appropriate, i.e. you are not trying to download all records from a large table then, you may need to modify the Connection Timeout property, Refer to [Host Settings](#_Host_Settings) section. Increase the Connection Timeout (ms) e.g. to 300000.
1. **Reporting an Issue**
If you need assistance with an issue, then the following should be provided:
1. Screen image of the System Log, showing any relevant details, or the Log File. The log file path is displayed on the Systems Settings page.
1. Screen image of the System Settings page, showing the Host and Client Settings
1. **SQL Server Consistent Naming to enable sharing of MX Sync Utility JSon configuration files**
In order for multiple users to share the same MX Sync Utility Json configuration file, it is recommended that all Users have
- the same version of SQL Server Express edition installed,
- with the same SQL Server instance name, and
- the same LogChief Configuration Database name.
By using a consistent naming standard, one MX Sync Utility JSon configuration can be created and shared between users which will reduce administration effort.