SyncTool is a standalone desktop application (Crs Sapera SyncTool) for transferring data between Sapera and the outside world. The program is built on the cross-platform technology Avalonia and is therefore made to run on multiple operating systems — unlike the previous version, which only worked on Windows. Typical uses are importing products, suppliers, customers, stock entries and finance journal entries from CSV, Excel or XML files as well as from a SQL database, but SyncTool can also export data and perform advanced actions such as FTP transfers, SQL runs and email sending.
SyncTool communicates with Sapera via the usual APIs, exactly as a user does via the browser. It requires a valid login and the right permissions — there is no direct shortcut around Sapera's access control.
SyncTool is installed and updated automatically via Velopack and can be started from the start menu or a shortcut icon. If you have not installed it yet, or your version is outdated, the program updates itself the next time it opens, provided the machine can reach the update server.
---
When SyncTool opens, a login form is shown with the following fields.
Environment specifies which Sapera instance to connect to, for example `production` or `staging`. The field corresponds to the platform name Sapera is set up with.
Tenant is the chain or store identifier, that is the domain name belonging to your organization in Sapera.
User is the username or email address of the account to log in with.
Password is the password for that account.
Org. unit (optional) can be filled in if your account has access to several organizational units and you want to connect to a specific one. If you leave the field blank, SyncTool automatically selects the unit that is the default for your user. If the account has access to exactly one unit, it is selected without asking. If you have access to several, SyncTool asks you to choose.
Press Log in or Enter to start the login attempt. A loading indicator is shown at the bottom of the form while SyncTool retrieves an access token and initializes the action list.
SyncTool saves a refresh token on the machine in the operating system's secure credential store (on Windows that is Windows Credential Manager) after a successful login. This means that on the next startup — or when you open a saved configuration file (.ssd) — you can be logged in automatically without entering the password again, as long as the refresh token is valid.
In the top right of the login screen you can switch the language between Danish and English. The choice is remembered per machine.
All users who can log in must have the permission Financial Import/Export Use granted in Sapera. Without it, login is rejected with an error message that you do not have access to SyncTool.
Certain actions require direct access to SQL Server and are reserved for users who are members of the Administrators group in Sapera. These actions are not shown at all in the action list for non-administrators. They typically involve internal operational tasks and are not relevant for normal import tasks.
---
Once login is complete, SyncTool switches to the main part of the program. At the top is a toolbar showing the active environment, tenant and any org. unit. Here you also find the buttons Load .ssd and Save .ssd for opening and saving configuration files, a Log out button, and a ? button that opens a short guide to the workflow itself.
Below the toolbar there are two primary tabs: 1. Setup and 2. Run. The idea is that you work from left to right — set up the action and data source, then run it.
At the bottom of the window is a status bar showing short informational messages, and below it is a log panel with three sub-tabs: Log, Warnings and Errors. The panel is collapsed to just the tab header, but click it, or press the arrow on the right, to expand it and see the details. The log panel is only shown when there is actually something to show.
---
A setup in SyncTool consists of one or more steps. Each step is one independent task with its own action, data source and field mapping. A configuration file (.ssd) can contain many steps that are run in sequence.
On the left of the setup tab is a list of the steps the setup contains. The buttons above the list let you add, remove, move up, move down and clear steps. Click a step in the list to edit it.
At the top right, when a step is selected, you first select Type and then Action.
Type filters the action list. Select Import for import actions (products, suppliers, customers, stock entries, etc.). Select Advanced for other actions such as SQL run, FTP upload, email and the like.
Action is the specific task the step is to perform, for example *Products*, *Suppliers*, *Finance journal entries* or *FTP upload*. Select the action in the dropdown list. Once an action is selected, the three sub-tabs below are enabled.
To the right of the action dropdown is a ? button that opens a detailed help dialog for that specific action. The dialog describes what the action does, which parameters it supports, and what each of the columns in the field mapping means. The individual actions are described in separate articles.
You can give the step an optional Step name that is shown in the list on the left and makes it easier to keep track of a setup with many steps.
The checkbox Show advanced hidden below the type/action row opens the two advanced parameter tabs and makes advanced column mapping fields visible in the mapping table. These are not necessary for normal use.
Here you tell SyncTool where data is to be retrieved from.
For file-based actions you press Load file... and select a CSV, Excel or XML file. Then details about the file are shown: file path, file type and, for CSV, settings for character set and separator. The checkbox First row is header indicates whether the first line in the file contains column names. The checkbox Built-in CSV/Excel reader switches to SyncTool's own file parser routines, which in many cases are faster and more robust than the OLE DB driver.
For SQL-based actions you press SQL connection... and specify a connection string. You can write a SQL query directly in the SQL query field or use Create query automatically to let SyncTool generate a default query based on the action's known columns.
The Preview count field limits how many rows are shown in the preview pane below. The import itself always processes all rows in the source, regardless of this number.
Once a source is selected, a preview of the data is shown directly in the tab. Use the button Show input data to refresh the preview manually.
Field mapping is where you link the source columns to the fields in Sapera that the action knows about.
The table has a Destination column (Sapera's field names) and a Source column (a dropdown with the columns from your data file or SQL query). Select the source that corresponds to each destination field. Rows without a mapping are shown in gray and skipped during the run.
In addition to the source/destination mapping, each field has further settings. The checkbox Update controls whether the field is updated when an entry already exists. Skip if empty leaves existing values in Sapera untouched if the source field is empty. RegEx lets you apply a regular expression to transform the source value, and Value if empty specifies a default value when the source is empty.
The basic parameters for the action (for example Allow creation and Allow update) are shown as checkboxes directly above the mapping table, so you do not need to switch tabs to adjust them.
Advanced columns such as Prefix, Postfix, Column expression and C# expression are visible when Show advanced is turned on.
These two tabs are only visible when Show advanced is active.
Step parameters shows the advanced parameters for the active step, including export settings such as FTP details, SharePoint URL or email recipient, depending on which action is selected.
Global parameters are parameters shared across all steps in the setup. These are typically connection strings, API keys and similar shared configuration values.
---
Parameter values such as passwords and connection strings are not saved in clear text in the configuration file. SyncTool supports two conventions for keeping secrets out of the file.
The § notation is used in connection strings. Write `Password=§MyKey;` in the connection string, and SyncTool looks up the password under the key `MyKey` in the operating system's secure credential store (on Windows: Windows Credential Manager) when that parameter is used.
The cred: notation is used when the entire parameter value is to be retrieved from Credential Manager. Specify `cred:MyKey` as the parameter value, and SyncTool automatically replaces the value with what is stored under `MyKey`.
If SyncTool loads an old configuration file with clear-text passwords in connection strings, the program migrates them automatically on first load: the password is moved to Credential Manager, and the file is updated with the § reference.
On a new machine — for example after a reinstallation — you must create the credentials manually in the operating system's credential store. On Windows this is done via Control Panel > Credential Manager > Windows Credentials > Add a generic credential. Use the key name `SyncTool_ParameterName` as the name and the password as the value.
---
The 2. Run tab is where you actually carry out the configured steps.
On the left of the tab is a list of steps with a checkbox next to each. Tick the steps that are to be included in the run. Click a step to see its details in the large window on the right.
Compare is a dry run that compares the source data with Sapera's current content without changing anything. The result is shown with colors in the result table: turquoise for new entries, light yellow for changed, gray for unchanged and red for failed. Always use Compare before you update, to check that the mapping is correct.
Update Sapera writes the found changes to Sapera. SyncTool asks for confirmation before this action is carried out.
Stop aborts an ongoing run in a controlled manner.
The two buttons also have a ... (selected) variant in the split menu, which runs all ticked steps in sequence rather than only the selected step.
Certain actions — for example pure SQL runs and exports — show different button labels such as Update DB and Export, but the principle is the same.
During the run, a progress bar is continuously updated with the percentage progress and statistics: total number of entries, new, changed, unchanged, skipped, warnings and errors, as well as the expected completion time.
The result table shows a preview of the processed rows with color marking. The button Changed/new only filters the table to show only entries that actually differ from Sapera's content. You can also open the comparison file in your default program or open the folder it is located in, via the corresponding buttons above the table.
---
A configuration — that is, the collection of steps, actions, source connections, field mappings and parameters — can be saved to an .ssd file (Sapera sync definition). Use Save .ssd in the toolbar and choose a location. SyncTool asks whether login details should also be saved in the file.
Use Load .ssd to open a saved setup. If the file has login details saved in it and a refresh token is available on the machine, SyncTool attempts a silent login so you land directly in the setup view without filling in the login form.
From the login screen there is a separate Load .ssd button in the top left that loads a file and copies its login details into the login form.
---
SyncTool can be started from the command line and run a .ssd file unattended as a scheduled task or as a background service. This makes it possible to automate daily or weekly data imports. On Windows it can for example be a task in Windows Task Scheduler or a Windows service that starts SyncTool with the relevant .ssd file as an argument at a fixed time.
In configuration files used for scheduled runs, it is recommended to save the login details in the file and ensure that passwords and connection strings use the § or cred: references, so that they are retrieved from Credential Manager and never saved in clear text.
The definition id field in the toolbar (visible to administrators) is a unique name for the setup and is used to identify scheduled jobs.
---
If you have questions, you are welcome to contact support.
Want to know more?
Read more in these related articles:
SyncTool - actions
Overview of the actions in SyncTool that are available without administrator permissions. Each action imports or processes data between an external source and Sapera.
Sync
This article explains the setup of webshop synchronization in Sapera
