Technical documentation - Signifikant Simplified XML - SSX
- Mattias Löfstrand
- Ruud de Bruijckere
- Kenneth Jonsson
This document is intended for technical staff creating imports to Signifikant Platform and describes the Signifikant Simplified XML import format.
Data imports into Manager database
Overview
Signifikant Platform import process is a two-step process where Signifikant Simplified XML or any custom file formats are transformed into Signifikant XML import format and then imported. Signifikant Platform import function operates on Signifikant XML format (described separately), and has configuration functionality for applying a transformation from any custom xml format. This guide describes the Signifikant Simplified XML format.
Signifikant Platform import function has the following built in transformations:
Signifikant Simplified XML to Signifikant XML
Windchill xml (requires configuration of Windchill) to Signifikant XML - in this case Signifikant Simplified XML is used as well
Creo Illustrate xml to Signifikant XML
IsoDraw xml (companion files) to Signifikant XML
Arbortext and Simonsoft CMS to Signifikant XML
Configuration
Signifikant Platform’s standard function is controlled by import.config, which lists the directories to use and the transforms to apply. Each information type will need to reside in their own directory. E.g. an external application exports parts and pdf-documents. The config file will specify where these exports shall be placed and how Signifikant Platform should recognize these exports. The config file will also specify where the Signifikant XML files shall be placed and where transforms are to be found. E.g.
D:/Export/Illustrations
D:/Export/Parts
D:/Export/Assemblies
D:/Export/Catalogues
D:/Import/Illustrations
D:/Import/Parts
D:/Import/Assemblies
D:/Import/Catalogues
D:/Import/HotspotWhen the first step of the import is started, Signifikant Platform will look in the export directory specified in the config file and match the folders found according to the regex in the config file. The information found will be transformed and placed in the import directory along with a .lis file specifying the content.
Naming convension for folders
A good practice is to use a naming convention for import folders based on <source>_<year>-<month>-<day>_<time>.
E.g. “ERP_2020-02-01_103121”.
Note the date format with year-month-day. This helps sorting the folders in windows explorer making it easy to find the latest export.
Task scheduler will import folders in one task based on alphabetical sorting, so ensure to use a convesion that works with this sorting
The second step, the actual import, will look in the import directory and match he folders with the regex in the config file and the actual files listed in the .lis file to determine what to import. When the second step of the import is completed, Signifikant Platform will place a status.xml file in the import directory.
Batch size will split import file in parts to ensure no xml file gets too big. A reasonable size is to set BatchSizeMB to 20.
Import.config
The import.config is automatically generated when Manager is started the first time. The location is C:\ProgramData\Signifikant\Assert\
Transformation
Transformation configuration is holding list of transformation styles which may transform files from one format to an other format.
Transformation configurations
<TransformationConfigs>
<TransformationConfig src="C:\ProgramData\Signifikant\Assert\htmlDocumentStyle.xsl" name="htmlDocumentStyle" transformTo=".html" />
</TransformationConfigs>In TransformationConfigs section we can specify multiple transformation styles sheets which may transform document from one type to an other. For example, from xml format to html format.
The src attribute represents the path where the transformation style sheet is located. We can assign identification name to style sheet by giving a name in name attribute. The transformTo attribute represents to which format this transformation will transform.
Sources in version 4.x
Transformation and import files are loaded from locations specified by tags in XmlConfig
<XmlConfig>
<ExportBasePath>D:\Assert\Export</ExportBasePath>
<ImportBasePath>D:\Assert\Import</ImportBasePath>
</XmlConfig>Sources in version 5.0
In version 5.x it is possible to define sources. A source is a concept of a source system, regardless of which transforms are used and where the files are stored. A source may be defined by its location or its folder name. Each source will appear as a column in import storage and as an option in task manager in the Manager application.
Defining sources using location.
Defining sources using folder name. In this case each transform will get its own configuration.
Languages in version 4.x and 5.0
Valid languages are defined in ImportSettings
Languages in version 5.1 and later
In version 5.1 and later it is possible to map language codes and all language settings are collected within LanguageSettings tag inside ImportSettings.
Note that language codes cannot be longer than 8 digits.
Sample import.config
APIs
See Technical documentation - XML import format for APIs to initiate import.
XML files
The following information may be imported into Signifikant Platform:
Texts and translations
Images and illustrations using illustrations.xml format and possibly also hotspots.xml.
Parts using part.xml format.
Assemblies using assemblies.xml format
Documents using documents.xml format
Catalogues using catalogue.xml format
Serial numbers using serialnumber.xml format
Hotspots using hotspot.xml format
There are dependencies between the different information types and information will have to be imported based on these dependencies.
Parts may refer to images if parts have images.
Assemblies refer to illustrations (images with hotspots) and parts
Catalogues refer to the contents of the catalogues, which may be parts, assemblies, documents or other catalogues.
Preferred import order is
Texts and translations
Images and illustrations
Parts
Assemblies
Catalogues
Serial numbers
Sample xml for texts (signifikant and xliff format)
Sample xml for content
General components of most xml import files
Metadata
The Metadata element includes information from the export process. At the moment, it includes export-type and export-time, but this information can easily be extended if the need exists.
Common element attributes
Most data types (parts, assemblies, catalogues, etc.) in the Signifikant information model share a number of common attributes:
identity An identifier for the element
persistent-identity* An identity that is reused over recurring imports
number A number for the element, e.g. part number
name A name for the element, e.g. part description
* The persistent-identity is the only attribute that is required in the import file. Often the identity, persistent-identity and number are the same, but there are use cases where these have different values.
Specifications
You can add an arbitrary number of additional attributes to most data types in the Signifikant information model. During import, you provide their values by using the Specifications tag which takes key/value pairs (called type and value).
Permissions
On most data types in the Signifikant information model you can set permissions which determine who has access to the information. During import, you provide the permissions by using the Permissions tag, which takes one or multiple permission levels.
CataloguesUsing
For each data type element in the import file, you can specify in which place and in which catalogue(s) the element is used. This way of linking data type elements to catalogue nodes makes the import and synchronization process very efficient.
Images
Most data types in the Signifikant information model can be linked to an image. The image is identified by its file name in the image directory. Images are imported into the Signifikant Manager from a directory or zip-file.
Removing presentations
All presentations can be removed at import by usign a remove command in the xml.
Remove command
Updating or overwriting presentations
Basic function in import is that import will overwrite only the values in the xml file. That is if name, identity and persistent identity exist on a presentation and xml only contains persistent identity and description, the presentation will have a name, identity, description and persistent identity afther the import. Fields may, though, contain empty string. In this case the value of that field will be replaced by an empty string.
But presentations may also be overwritten. In this case the presentation is removed and then reimported according to the xml. This is achieved by an overwrite command according to below.
Overwrite command
Specific components per data type of the xml import files
Texts
Each text may be defined by a persistent id which can be referred from all other exports. Each text contains all translations for that text with language defined using ISO 639-1 alternatively ISO 639-1 and ISO 3166.
A text with language "" is considered being invariant, the same for all languages.
Parts
On top of the common information, the parts file allows you to add a supplier-part-number and a classification for the part. Classification is one way to distinguish various types of parts; another way is to use one or more custom specifications.
Illustrations
An illustration consists of one or more images and one or more hotspots. The image is defined by its filename. For each hotspot, the location and identity is provided. The identity can later be used to link a hotspot to a part-row in an assembly.
This is one way of importing hotspots to the Signifikant Manager. Alternative ways are
Embedding the hotspots in the image files
Using Optical Character Recognition (OCR)
Illustrations may contain hotspots as xml. This xml may be embedded into the illustration.xml file or imported as a separate file referred from the illustrations.xml file. The hotspots are defined by position (x,y) and size (with, height). Both position and size are normalized values (0-1) and origo is top left corner of the illustration.
SVG files may also have hotspots built into them. If both hotspots as xml and hotspots in SVG are provided, the hotspot information in the xml will be discarded.
Assemblies
An assembly consists of one or more illustrations and one or more part-rows. Illustrations are identified by their persistent-identity. Assemblies can be kits, which is marked in the import file with the kit tag. For each part-row the following information can be provided:
Position (is matched with the hotspots)
Quantity
Sellable item
Hidden part number
Remark
Included-in-kits
Type
Documents
For each document you can provide a title. If you work in a multilingual environment, you can provide a title for each language. You can also provide a list of languages for which the document is valid.
Catalogues
The catalogue import file describes the structure for each catalogue (nodes with images) and it also describes how each node is linked to other data type elements in the Signifikant information model. A node can be linked to:
Parts
Images
Illustrations
Assemblies
Documents
Other catalogues
Web Viewer imports
Overview
It is possible to make imports into the WebViewer. Currently imports of the below information is possible:
organisations
Imports can be started manually by uploading files in the web viewer or by a service monitoring a hot folder.
Sample xml
