DataSync Client User Manual

1. Setup Guide

Follow these steps to install and configure the DataSync Client on your computer. The entire setup process typically takes about 10-15 minutes.

1. Visit the DataSync landing page provided by your administrator
2. Click "Download Latest Version" to download the installer package
3. Save the file to your computer (e.g., Downloads folder)

Right-click the downloaded installer file and select "Run as administrator".

The Setup Wizard will guide you through the installation:

Click Next to proceed. You will be presented with the license agreement:

1. Read the license agreement carefully
2. Check "I accept the terms in the License Agreement"
3. Click Next to continue
4. Choose the installation location (default: C:\Program Files\DispatchScience\DataSyncClient)
5. Click Install to complete the installation

The installer will automatically:

• Install the DataSync Client Windows service
• Install the DataSync Configuration Tool
• Create Start Menu shortcuts

Once installation is complete, you'll see the completion screen:

Check "Launch DataSync Configuration Tool" and click Finish to open the configuration tool immediately.

After installation, open the DataSync Configuration Tool from the Start Menu.

Navigate to the Settings tab to configure your client:

Configure the following settings:

Setting	Description
Client ID	A unique identifier for this client, automatically generated from the computer's MAC address. This field is read-only and ensures the same machine always uses the same ID
Poll Interval	How often (in seconds) the client checks for new data. Default is 300 seconds (5 minutes). Minimum is 5 seconds
Server URL	The DataSync server URL (e.g., https://datasync-portal.dsapp.io/). This will be provided by your administrator

Navigate to the Database tab to configure your local SQL Server connection:

Enter your SQL Server connection string in the text box. Example connection strings:

Windows Authentication:

Server=localhost;Database=DataSyncLocal;Trusted_Connection=True;TrustServerCertificate=True

SQL Server Authentication:

Data Source=.;Database=DataSyncDb;Integrated Security=false;User ID=sa;Password=yourpassword;TrustServerCertificate=True;Encrypt=True;

Navigate to the Authentication tab and click "Sign In / Re-authorize".

1. A browser window will open to the Microsoft login page
2. Enter your Azure AD credentials (email and password)
3. Complete multi-factor authentication (MFA) if prompted
4. Grant consent for the DataSync application if requested
5. Return to the Configuration Tool - your authentication status will update

Click "Save Configuration" at the bottom of the window to save all your settings.

Navigate to the Service tab to start the Windows service:

1. Click Start to start the DataSync service
2. The Service Status will change to Running
3. The service will now automatically synchronize data in the background

---

2. Configuration Tool Reference

The DataSync Configuration Tool provides a graphical interface for managing all client settings. This section provides detailed information about each tab and its options.

Settings Tab

Essential connection and client settings:

Setting	Description
Client ID	A unique identifier automatically generated from this computer's MAC address. This field is read-only. Advanced users can override it in appsettings.json if needed
Poll Interval	How often (in seconds) the client checks for new data. Minimum: 5 seconds. Default: 300 seconds
Server URL	The base URL of the DataSync server (provided by your administrator)

Database Tab

Configure your local SQL Server database connection. The client will synchronize data to this database.

Element	Description
Connection String	Full SQL Server connection string for your local database
Test Connection	Validates the connection string by attempting to connect to the database

Authentication Tab

Manage your Azure AD authentication status:

Element	Description
Status	Shows current authentication state (Authenticated / Not authenticated)
Username	Your authenticated Azure AD account email
Token Expires	When your current authentication token expires
Sign In / Re-authorize	Opens browser for Azure AD sign-in
Clear Cached Tokens	Removes stored authentication tokens (useful for troubleshooting)

Service Tab

Monitor and control the DataSync Windows service:

Element	Description
Service Status	Current state: Running, Stopped, or Not Installed
Start	Start the service (requires administrator privileges)
Stop	Stop the service gracefully
Restart	Stop and restart the service
Refresh	Update the displayed service status
Open Event Viewer	Launch Windows Event Viewer to see service logs

Bottom Action Bar

Button	Description
Save Configuration	Saves all changes to the configuration file
Reload	Discards unsaved changes and reloads from disk
Validate	Checks for missing required fields without saving
Restart service after save	When checked, automatically restarts the service after saving

---

3. Authentication

The DataSync Client uses Azure Active Directory (Azure AD) for secure authentication. You must sign in before the service can connect to the server.

Re-Authorization (When Token Expires)

Authentication tokens expire periodically for security. When your token expires, you'll see these symptoms:

• Service logs show authentication errors
• Sync jobs fail with "401 Unauthorized" errors
• Configuration Tool shows "Not authenticated" status

To re-authorize:

1. Open the DataSync Configuration Tool
2. Go to the Authentication tab
3. Click "Sign In / Re-authorize"
4. Complete the sign-in process in the browser
5. Restart the service if it was running

Clearing Authentication

If you experience persistent authentication issues, try clearing the token cache:

1. Open the DataSync Configuration Tool
2. Go to the Authentication tab
3. Click "Clear Cached Tokens"
4. Click "Sign In / Re-authorize" to sign in fresh

---

4. Managing the Service

Using the Configuration Tool

The easiest way to manage the service is through the Configuration Tool's Service tab:

• Click Start to start the service
• Click Stop to stop the service
• Click Restart to restart the service
• Click Open Event Viewer to view logs

Using Windows Services

1. Press Win + R, type services.msc, press Enter
2. Find "DataSyncClient" in the list
3. Right-click and select Start, Stop, or Restart

Using Command Line

Run these commands as Administrator:

sc start DataSyncClient    (Start the service)
sc stop DataSyncClient     (Stop the service)
sc query DataSyncClient    (Check service status)

Viewing Service Logs

The DataSync Client logs detailed information to multiple locations:

Windows Event Log:

1. Open Event Viewer (eventvwr.msc)
2. Navigate to: Windows Logs > Application
3. Filter by Source: "DataSync"

Log File:

[Installation Directory]\log.txt

---

5. System Requirements

Minimum Requirements

Component	Requirement
Operating System	Windows 10/11 or Windows Server 2016+
.NET Runtime	.NET 10.0 or later (included in installer)
Database	SQL Server 2016 or later
Network	Internet access to DataSync server
Disk Space	100 MB for application, additional space for local database

Network Requirements

Ensure outbound HTTPS (port 443) access to:

• DataSync server URL (provided by your administrator)
• login.microsoftonline.com (Azure AD authentication)
• Azure Blob Storage endpoints

---

6. Troubleshooting

Service Won't Start

Check Authentication:

• Ensure you have signed in via the Configuration Tool
• Try clearing cached tokens and re-authorizing

Check Configuration:

• Verify all required fields in the Configuration Tool
• Test the database connection
• Ensure the Server URL is correct and accessible

Authentication Errors

Error	Cause	Solution
"401 Unauthorized"	Token expired	Re-authorize using Configuration Tool
"403 Forbidden"	No tenant permission	Contact administrator
Sign-in page errors	Network/browser issues	Check network, try different browser

Sync Not Working

Issue	Possible Cause	Solution
No jobs available	No new data on server	Check with administrator
Connection timeouts	Network issues	Verify server URL and firewall
Database errors	Connection string invalid	Test connection in Config Tool

---

7. Support

Getting Help

If you encounter issues not covered in this manual:

1. Check the Logs: Review the Event Viewer logs for detailed error messages
2. Verify Configuration: Ensure all settings match what your administrator provided
3. Contact Your Administrator: They can verify server-side configuration and tenant settings

Information to Provide When Requesting Support

• Client ID (auto-generated, shown in Configuration Tool Settings tab)
• Tenant ID
• Error messages from Event Viewer
• Steps to reproduce the issue
• Windows version and SQL Server version

---

Quick Reference

Item	Location
Configuration File	[Installation Directory]\appsettings.json
Log File	[Installation Directory]\log.txt
Token Cache	%PROGRAMDATA%\DispatchScience\DataSyncClient\msal_token_cache.bin
Service Name	DataSyncClient
Default Install Path	C:\Program Files\DispatchScience\DataSyncClient