Technical documentation - Signifikant Simplified XML - SSX

Owned by Mattias Löfstrand
Last updated: 14 Aug 2020
11 min read



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/Hotspot

When 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

  1. Texts and translations

  2. Images and illustrations

  3. Parts

  4. Assemblies

  5. Catalogues

  6. 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