An Altium NEXUS Server installation includes a CSV Component database importer tool that can be used to bring component data into the NEXUS Server from a file exported from an enterprise system, such as a company ERP or PLM system. Implemented as a configurable batch (*.bat) file, the desktop tool imports component data from a target spreadsheet file (*.csv) into the server as determined by existing server templates or a dedicated configuration file.
► See PLM Integration for more information on working between the NEXUS Server and PLM systems.
The command line tool can be found in the \Program Files (x86)\Altium\Altium NEXUS Server\Tools\CSVImport folder of the NEXUS Server installation. See the csv-import.bat for information on the command line syntax used with the tool, or simply execute the batch file without attributes for more detailed information.
Notes:
- The tool and its supporting Java runtime folder (
JRE8) may be copied to and run in any location, including on a different networked machine to the NEXUS Server host machine.
- The tool may need to be run with elevated (Administrator) privileges, depending on where it is located.
- The tool syntax is case sensitive, as are references in Server Templates and any configuration files used.
Source file format:
The CSV data importer tool requires the source comma-delimited CSV file to use UTF-8 character encoding. If the file uses other encoding formats such as ANSI or UTF-8-BOM, the importer will not parse extended characters (such as µ) correctly, or may not accept the *.csv source file.
If creating a basic CSV file for testing purposes, note that some versions of Windows' Notepad do not save in a compatible UTF-8 format. If in doubt, an alternative text editor such as Notepad++ can be used to create and save UTF-8 encoded files, and is also useful for checking the encoding format of *.csv files exported from a source enterprise system.
Auto mode
When used without applying a configuration file (option –c) the CSVImport tool process will attempt to match the target CSV filename (say, Resistor.csv) with a server Component Template that supports that Component Type (Resistor). The found Template will determine the Revision, Lifecycle and Default Folder (server target) for the imported data. Note that the minimum data requirement for the source CSV file is the PART_NUMBER parameter column and its matching Values.
The csv-import utility tool provides general progress information in the console window as it runs, and can also produce a log file as specified by the command syntax (-l). If component manufacturer part parameters are present in the CSV file (by default; MFR_PART_NUMBER and MFR_NAME), matching Part Choice entries are created in the server.
The optional log file provides details of a successful import process – if the process fails, a log file is not generated.
Configured mode
The tool’s more advanced mode uses an XML configuration file to specify file-to-server parameter mapping for the import process. For the example shown here this might be say, mapping the source Value parameter to Resistance in the server, and the Format parameter to Package.
To obtain a base configuration file that can be modified to suit, run the tool with the generate configuration file setting (-g). This will create the specified XML file with parameter key/value pairs extracted from the source CSV file, and the Revision, Lifecycle and target folder setting from the matched Template. For example:
csv-import.bat -s http://HPZ600:9780 -u admin -p admin -g MyConfig.xml -i C:\Users\Public\Documents\CSV_Files\Resistor.csv
Edit the Attribute Values in the ToAltium section of the MyConfig.xml configuration file (for the Resistor PLM class) to map as required.
Mapping edits for this example
For the example shown here, the related Attributes would be changed from:
<ns2:Attribute attributeType="revision">
<ns2:Key>Format</ns2:Key>
<ns2:Value>${attribute.Format}</ns2:Value>
</ns2:Attribute>
<ns2:Attribute attributeType="revision">
<ns2:Key>Value</ns2:Key>
<ns2:Value>${attribute.Value}</ns2:Value>
</ns2:Attribute>
...to:
<ns2:Attribute attributeType="revision">
<ns2:Key>Package</ns2:Key>
<ns2:Value>${attribute.Format}</ns2:Value>
</ns2:Attribute>
<ns2:Attribute attributeType="revision">
<ns2:Key>Resistance</ns2:Key>
<ns2:Value>${attribute.Value}</ns2:Value>
</ns2:Attribute>
The configuration file is then used with the tool (option –c) to perform the required mapping:
csv-import.bat -s http://HPZ600:9780 -u admin -p admin -c MyConfig.xml -i C:\Users\Public\Documents\CSV_Files\Resistor.csv
If the component entries already exist in the Server (as imported in the above
Auto mode example process), new Revisions will be created and the remapped parameters added to the existing data – existing parameters are not removed.
Additional features:
- An applied configuration file determines all settings for the import process, including parameter mappings, independently of related server Templates.
- All parameters may be mapped to accommodate the input CSV file parameters, including what name is used in the file for PLM Number and the part manufacturer data.
- Multiple Entity definitions, including their constituent parameter Attributes, can be included in a configuration file. Copy an existing Entity group entry, say for
Resistor, and then paste/edit this to create another for Capacitor.
- When a source path is specified without a CSV file, the tool will search the source folder for CSV filenames that match Entity definitions in the configuration file. So if configuration Entity references exist for
Capacitor and Resistor and matching CSV files are found, the data for those components will be imported into the server. This is effectively the tool's batch operation mode.
- If the source CSV file uses a particular filename structure that does not match the standard server Component Types (
Resistor, Capacitor, etc), this can be allowed for by mapping the PLM class in the configuration file. For example if the source file is PLM-Export_Resistors.csv, the PLM class entry plmType=”Resistor” can be changed to plmType=”PLM-Export_Resistors”.
