Why would I use manual sync?
Please read the data sync orientation article before you begin, since it provides important background information, including the motivation for using manual sync.
Two types of users - which type of sync user am I?
Importing data to Matics requires first preparing all the client's exported data to match the Matics data structures by:
Mapping the fields used in the client's ERP/MRP system to the corresponding fields in the Matics system.
Checking that the imported data include all the required fields.
The user who will perform manual sync must be authorized to map table columns. This is the first type of user.
After fields are mapped, any user can import data files, as long as their user's group access permissions includes Data Sync -- this is the second type of user.
For more information see Users Data Sync Permissions Settings.
Data preparation
Guidelines
Export the data from your ERP/MRP system to flat files. Supported file formats are comma delimited files (.csv) and text files (.txt).
TIP: If your dataset contains accented characters or non-English alphabet characters, save as CSV UTF-8 or Unicode Text when available.When preparing flat files, you can set any character to be the value separator. Notwithstanding, the character should not be a character that could be potentially included in your data as this will generate errors.
If no custom delimiter is set, the system uses the tab character for .txt files and a comma for .csv files.Remove extra lines.
Do not insert special characters such as the '+' symbol in the flat file name. Underscores and hyphens are supported.
Imported data must match the Matics database table structure: which means you must include all the Matics required fields related to the data you want to import. Please refer to the Table Dependencies section in the data sync orientation article, which lists at the end the required fields in each table.
If your ERP system does not group machines by machine type, you will need to retrieve the machine types used in Matics for your site since this is a key field.
The following fields are part of the system infrastructure, so depending on the data you intend to import, make sure you have their correct system identifiers:
Recipe production parameters' names and material related properties for channels 1 to 100 (the machine type's set properties are required for filling in correctly the values in FK_PropertyName). You may find this list of default machine type properties useful. Specific idiosyncrasies are specified in the data sync orientation article, here.
Material groups set for your site (FK_MaterialGroup)
User groups
TIP
Table dependencies determine in what order data are to be imported. When importing multiple table data files, number these files per their import order. The import order is specified here.
Sample files
In the learning process it's helpful having an example for hands-on experimentation. Download the sample data files attached to this article. You'll find them at the very end.
The files are:
1_Products.csv
2_Mold.csv
3_Users.csv
TIP
Compare these files to the output of your ERP/MRP system to get an idea of how your data will need to be organized.
These sample files are numbered per the correct import sequence and will be used to demonstrate manual data import. To keep them simple, they include only data for required fields -- with the exception of the Users table that includes also an optional field.
Importing the sample files
The following walkthrough demonstrates the import of these files.
Step-by-step procedures for data mapping and uploading files is provided in the following sections.
Interface orientation
Starting point
Go to Data Sync > Manual Sync:
The page is called File Manager since it provides the option of mapping and uploading data files. The File Manager table lists a synopsis of the sync action and results for each uploaded data file.
Click to set the values separator in use in your data.
Click to map your data fields to Matics fields.
NOTE: This step is applicable only to users authorized to map data.Quick upload of data files to Matics is the only upload option available for users without data-mapping permissions.
If the sync failed, click Failed to view the sync errors.
We will go over these five interfaces in the following sections.
Define files separator dialog
Manual data sync supports two file types: .csv and .txt.
For each file type there's a default value separator character. For .csv files it's a comma and for .txt files it's a tab. You can set any character to be the value separator. The character must not be a character that could be potentially included in your data.
If you change the delimiter character, to apply this change click Save changes.
To revert back to the defaults, click Cancel.
NOTE
For .csv files the first line will be used as column headers.
For .txt files use the system-defined separator between values. The first line will be used as column headers.
The Value separator table is a standard system table, and as such it includes all the built-in various table options, such as pin column (3). Ignore these options since it doesn't make sense to use them here.
Data Mapping dialog
This dialog is available only to users with mapping authorization.
Go to Data Sync > Manual Sync and click Data Mapping:
Start by selecting the table you're mapping. In the above example the Products table was chosen. This will populate the dialog with the Matics table's fields (columns), in the Products columns list.
Hover over the information icon to display context-sensitive tooltips, for example the column description.
Sort the columns list.
Default order sorts the table's fields per table structure in the Matics database.
Alphabetically sorts the table's fields in descending, alphabetical order.
Required presents required fields at the top of the list.
To quickly locate a specific table field, use the Search option.
The scroller is for scrolling through the columns list.
Click Upload File.
IMPORTANT: Make sure you upload files in the correct order as specified here.
See the respective workflow below for the next steps you'll be doing.
Upload File dialog
Go to Data Sync > Manual Sync and click Upload File:
The Upload File control is available to all users. For those with mapping permissions, you would use this option in subsequent data syncing after mapping the table(s) columns.
Start by selecting the table you are about to upload.
IMPORTANT: Make sure you upload files in the correct order as specified here.Click View mapping to verify that the mapping in your data file matches the existing mapping for that table.
If the mapping is incorrect and you have mapping permissions, use the Data Mapping dialog to fix the mapping. If you don't have mapping permissions, escalate to whoever has.
When the mapping is correct, click Okay and continue.
Upload the target flat file.
Click Sync. See the upload file workflow in action below.
Click the refresh control to view the most current sync status.
File Manager & sync errors
Go to Data Sync > Manual Sync. This is the landing page which also serves as the where you track file synchronization activity.
You can manually reload the page to view the most current file sync statuses.
Scope the period for which you want to view the files that were synced manually.
Files that include failures in their data synchronization will be indicated with a Failed status (the other two statuses are Syncing... and Synced).
Click the reddish Failed status indicator to view that file's Sync errors log.
To save the log, click Download file in the bottom-left corner of the Sync errors window.
Main workflows
Using the Data Mapping dialog for manual data sync
Go to Data Sync > Manual Sync.
Click Data Mapping.
In the Table name list select the relevant table.
On the left you'll be shown all the columns this table includes, with a tooltip description of what this table field is for and beneath the column name/table field the type of data (text, number, etc.) and the constraints for that data value.
You can use this information to create your data fileAssuming you've already prepared it, click Upload File.
IMPORTANT: Make sure you upload files in the correct order as specified here.Click Map File.
NOTE: If you've already uploaded a file in the past for that table you'll be prompted to confirm that you want to remap the columns, which will overwrite any previous mapping done for this table.On the right you will see the mirror of the Matics columns. A warning icon indicates those columns in your data file for which the system did not detect a corresponding column for the table in your uploaded data file.
Click See first to present at the top of the list all the columns for which there are mapping errors.Fix these mapping errors by selecting the column in your file that matches the Matics column name.
NOTE: Only unmapped fields in your data file will be offered in the drop-down list, so if the correct field has been erroneously mapped to another field you will need first to fix that mapping to release that field.Click Sync.
Using the Upload File dialog for manual data sync
Go to Data Sync > Manual Sync.
Click Upload File.
IMPORTANT: Make sure you upload files in the correct order as specified here.In the Table name list select the relevant table.
Click View mapping.
Verify that your file's columns match the columns of the Matics table.
Click Okay to close the Mapping confirmation window.
Drag & drop or browse to upload the flat file you are now syncing.
Click Sync.
Syncing product recipe data
When importing product recipe data, we’re expected to provide for each production parameter, which will populate the FK_PropertyName column, its standard --the F value. The FK_PropertyName field’s values can be any of the production parameters configured for the machine type when setting up the system.
In the file preparation guidelines, we mentioned an Excel file that lists each machine type’s default properties. You may find it useful opening this Excel to see what the property name is called and how it’s spelled. For example, CycleTime. Keep in mind though that it’s not an exhaustive list since your site may have additional custom properties that are in use.
Through which tables you import the product’s recipe data depends on whether you want to specify the variances in these production standards per different machines, or not.
If not, you’ll use the Product Recipe table.
When importing product recipe data through the Product Recipe table, making adjustments to these values per machine can be done later on at the job level either by syncing data through the Product Recipe Job table, or manually through the Matics system.
TIP
If you want to use manual sync to set in advance the recipe’s production standards per each machine, use the Product Recipe Standard table. Users will then have these machine-specific standards available in jobs as Alternative Recipes.
In the following walkthrough example we used this ProductRecipe sample file to import product recipe data.
EXTRA INFO
The recipe's production parameter (FK_PropertyName) dedicated to hyperlinks is a machine-type level property called 'file'*. The value for this property needs to be an absolute URL, for example: https://kb.matics.live/
*This property's display name is as was configured, for example the display name could be 'Instructions'.
Syncing stop event groups and event reasons data
Importing stop event groups and event reasons through Manual Sync is an efficient way to import and update your site's stop event groups and reasons.
Sequence
Import files that correspond to the following tables in this order:
EventGroups: a table that establishes the stop event groups.
EventDescription: a table that establishes the stop event reasons for these groups.
EventDictionary: a table that establishes the translations for either the stop event group names or stop event reason names.
EventMachineDefinition: a table that establishes to which department OR machine type OR machine a stop event group OR a stop event reason will be available for.
Description of each table's fields
EventGroups
Import the basic definitions for stop event groups at your site.
For example:
Field Name | Required? | Description | Supported values |
Ename | Y | Group name in English | Text string |
ERPID_ScheduleDefinition | Y | Group's scheduling classification |
|
ErpId | Y | The key for the record of the event group | Text string |
AllMachines | Y | How the event group is tied to machines: If TRUE the event group is assigned to all the site(s) machines. If FALSE, this group will be assigned to machines per the EventMachineDefinition table's definitions. TIP: you can use complementary logic by first using TRUE for all machines, and then fine-tune in the EventMachineDefinition table's definitions specific instances. For example, if the stop event group will be available to 99% of the machines in your site, you can start by setting TRUE here and afterwards in the machine definition table specify machines for which this stop event group doesn't apply. |
|
DisplayInOpApp | Y | Whether this stop event group will be visible in the tablet application. |
|
LName | N | Event group name in local language | Text string |
IsActive | N | Whether this stop event group is available for use or not. |
|
Color | N | The color code value used for the group | HEX value |
OpAppDisplayOrder | N | The position of this stop event group in the groups shown on the tablet app. | Number |
Corporate | N | Inherit colors set at the multisite level to all the organization's sites. (Not yet in use) |
|
ERPCategoryId | N | Not in use |
|
Icon | N | An icon that signposts the event group with a meaningful visual cue. | The value for the icon as listed below |
EventDescription
Import the basic definitions for stop events at your site.
For example:
Field Name | Required? | Description | Values |
AllMachines | Y | How the event is tied to machines: If TRUE the event is assigned to all the site(s) machines. If FALSE, this event will be assigned to machines per the EventMachineDefinition table's definitions. TIP: you can use complementary logic by first using TRUE for all machines, and then fine-tune in the EventMachineDefinition table's definitions specific instances. For example, if the stop event will be available to 99% of the machines in your site, you can start by setting TRUE here and afterwards in the machine definition table specify machines for which this stop event doesn't apply. |
|
Ename | Y | Stop event name in English | Text string |
ERPID_EventGroup | Y | The ERP ID of the event group this event is a member of | Text string |
ErpId | Y | ERP ID of this stop event reason | Text string |
LName | N | Stop event reason name in local language | Text string |
ERPID_EventDefinition | N | Refers to the event's work type, a legacy typecasting. There are three options that need to be matched correctly to the industry-standard time management model implemented in Matics: If the group's classification is Unscheduled, choose Idle Time. Downtime can apply to stop event groups classified as Planned downtime and Unplanned downtime. Manual Work is intended for the special case of certain CNC machines in which there's a phase in production that the machine itself isn't working while its operator is performing manual work, and it would be incorrect to record this time as downtime. |
|
Color | N | The color code value used for this stop event reason | HEX value |
Icon | N | An icon that signposts the stop event reason with a meaningful visual cue. | See supported values below |
IsActive | N | Whether this stop event reason is available for use or not. |
|
ERPID_ScheduleDefinition | N | The group's scheduling definition that applies to this stop event reason |
|
DisplayInOpApp | N | Whether this stop event reason will be visible in the tablet application. |
|
OpAppDisplayOrder | N | The position of this stop event reason within its group shown on the tablet app. | Number |
TargetPC | N | Target percentage | Number |
EventDictionary
This table supports the translation of either the name of a stop event group or the name of a stop event reason.
For example, you can see in the first row the translation of an event reason and in the second row the translation an event group:
Field Name | Required? | Description | Values |
ERPID_EventGroup | N | ERP ID of the stop event group that you are translating. | Text string |
ERPID_Event | N | ERP ID of the stop event reason that you are translating | Text string |
Amh | N | Name of stop event reason in Amharic | Text string |
Cze | N | Name of stop event reason in Czech | Text string |
Eng | N | Name of stop event reason in English | Text string |
Heb | N | Name of stop event reason in Hebrew | Text string |
Rus | N | Name of stop event reason in Russian | Text string |
Spn | N | Name of stop event reason in Spanish | Text string |
Arb | N | Name of stop event reason in Arabic | Text string |
Chn | N | Name of stop event reason in Chinese | Text string |
Ned | N | Name of stop event reason in Dutch | Text string |
Ger | N | Name of stop event reason in German | Text string |
Ukr | N | Name of stop event reason in Ukraine | Text string |
Ita | N | Name of stop event reason in Italian | Text string |
Hun | N | Name of stop event reason in Hungarian | Text string |
Prt | N | Name of stop event reason in Portuguese | Text string |
Pol | N | Name of stop event reason in Polish | Text string |
Gre | N | Name of stop event reason in Greek | Text string |
Rum | N | Name of stop event reason in Romanian | Text string |
EventMachineDefinition
Fine-tune to which machines the stop event groups and/or reasons apply to.
Each record will be for either a stop event group or stop event reason.
And this object will be mapped to either a department, a machine type or a machine.
For example, here you see that machine M-4 is unassigned from a group:
Field Name | Required? | Description | Values |
ERPID_EventGroup | N | ERP ID of the stop event group | Text string |
ERPID_Event | N | ERP ID of the stop event reason | Text string |
ERPID_Department | N | ERP ID of the department | Text string |
ERPID_MachineType | N | ERP ID of the machine type | Text string |
ERPID_MachineId | N | ERP ID of the machine | Text string |
Action | N | Determine what action is applied to the stop event group | stop event reason: is it assigned to a department | machine type | machine? ( |
|
Verifying successful sync
Even though getting a Synced status confirms that the data import succeeded, it's always a good idea to spot-check a few items in the system.
For example, if you've imported new products, you can go to Production > Products and sort the Products table by Index numbers. The largest index number is the newest item added. Click the index to open that product's record and examine it.
Subscribing to sync logs
There's also an option of subscribing to sync logs that will be delivered to your mailbox:
Go to Setup > Site Configuration > Step 7 - Define System Variables > More Settings.
In the Definition column search for
SyncLogFileEmailRecipient.In the Value cell for
SyncLogFileEmailRecipiententer the email addresses of those that are interested in subscribing to sync logs, separating between email addresses with a semi colon;.Click Save changes.
Troubleshooting
Line #(n) : Missing mandatory fields,record #(n)
If the line number (n) is the last line in your file, this error may indicate that your data file includes an empty row. Open the data file with a text editor, such as Notepad++ and show symbols. Check if there's an extra line break (CR|LF) in that file and remove it. In this example there was an extra CR|LF that had to be removed:
Appendix: Icon library values
If using icons to signpost the stop event reason in the EventDescription table with a meaningful visual cue, here are the values you can use:
Icon | Value to use |
 | back.svg |
 | break-copy-3.svg |
 | drag-handle.svg |
 | electricity-copy-3.svg |
 | general-copy-4.svg |
 | lunch-copy-2.svg |
 | maintenence-copy-9.svg |
 | maintenence-copy-10.svg |
 | malfunction-copy-3.svg |
 | materal-copy-2.svg |
 | no-group-icon.svg |
 | operator-copy-5.svg |
 | planning-copy-5.svg |
 | qa-copy-4.svg |
 | rejects-copy-5.svg |
 | setup-copy-5.svg |
 | smoke-copy-2.svg |
 | stop-copy-5.svg |
 | temp-copy-5.svg |
 | tools-copy-3.svg |
 | water-copy-5.svg |
 | workers-copy-5.svg |
Related articles