Document number	Revision
DOCU12222	3

Reference Import (Setup and Configuration)

Reference Import (Setup and Configuration)BackgroundSetupAdd Reference Import to basetypesAdd Reference Import to subtypesConfigurationBasic schema configurationExternal file configurationFiletype and FilenameFile content structure<import-ref> elementSamplesImporting part references from a .xlsx documentImport using aggregateFrequently Asked QuestionsWhy does clear-on-import not remove all references?

Background

Reference Import is bundled with Highstage and is available as a possible customization to Actions, Parts, Documents and Devices. Reference Import enables the possibility to add references In bulk to items, from external files associated with an item.

Setup

You can include Reference Import to be available on all items of a specific basetype, or on items of specific Subtypes.

Add Reference Import to basetypes

To include Reference Import to basetypes in your Highstage installation, add the following lines in the custom.schema.xml:

Added Reference Import to Part basetype items:


<type name="part">
    <import-ref name="default"
                title="Reference Import"
                pattern="#item#qty,pos"
                basetype="part"
                clear-on-import="1"
                subtypes="*"
                file-pattern="*.xlsx"
                ignore-headers="0"
                create="1"
                aggregate="0"/>
</type>

Notice that the above examples includes a number of predefined attributes of the <import-ref> element such as aggregate , pattern and file-pattern. These attributes can be customized in a number of ways. Visit <import-ref> element for information about the available attributes.

Reference Import can also be added to other basetypes such as Documents, Actions or Devices by changing the <type name="BASETYPE" attribute to reflect the appropriate basetype.

The following sample illustrates the different basetypes where Reference Import can be added:


xxxxxxxxxx
<type name="part"></type> <!--PART BASETYPE-->
<type name="action"></type> <!--ACTION BASETYPE-->
<type name="doc"></type> <!--DOCUMENT BASETYPE-->
<type name="device"></type> <!--DEVICE BASETYPE-->

Remember to Reset Highstage for the changes in custom.schema.xml to take effect.

The Reference Import feature is now accessible from the appropriate item view in Highstage under the reference section in the default form.

item2

Add Reference Import to subtypes

To include Reference Import to subtypes in your Highstage installation, add the following lines to the appropriate subtype schema:


xxxxxxxxxx
<schema schemasyntaxversion="0.8">
    <type name="SUBTYPE">
        <import-ref
                    name="import-ref-subtype"
                    title="Reference Import"
                    pattern="#name#pos"
                    basetype="part"
                    subtypes="*"
                    file-pattern="references.csv"
                    create="1"
                    aggregate="0"/>
    </type>
</schema>

Notice that the above examples includes a number of predefined attributes of the <import-ref> element such as aggregate , pattern and file-pattern. These attributes can be customized in a number of ways. Visit <import-ref> element for information about the available attributes.

Here you can modify the <type name="SUBTYPE" to specify which subtype you want the Reference Import feature to be added to. For instance, the following snippet will make Reference Import available on all items with the MCAD subtype.


xxxxxxxxxx
<type name="MCAD"></type>

Remember to Reset Highstage for the changes in the subtype schema to take effect.

Note! This can be done both from the specific subtype schema or as an addition to the custom.schema.xml in the tweak folder

Configuration

Reference Import can be configured in a number of ways to facilitate the import of larger quantities of references to specific items. Similarly, you might also benefit from adding more variations of Reference Import buttons to support more specific or different import capabilities in Highstage.

Reference Import supports the following capabilities:

Import references to the current item from new or existing items in Highstage.
Import references with attributes that are created and associated with the reference.
Import a subset of references by defining base- and/or subtype(s) of the references that should be imported.
Import references from any of the supported file-formats (XLSX, CSV and plain-text file formats).
Ignore any number of rows in your reference file to account for headers.
Import from aggregated files by enabling aggregate to import any number of references to the same item.

Basic schema configuration

The following snippet can be used as a standard configuration of Reference Import:


xxxxxxxxxx
    <type name="BASETYPE">
        <import-ref name="ref_imp_sample"
                    title="Import References"
                    basetype="BASETYPE"
                    pattern="#item"
                    file-pattern="references.xlsx"
         />
    </type>

This snippet includes the mandatory attributes name, title, basetype, pattern and file-pattern for Reference Import to function. The above snippet makes use of example values for these properties.

Notice!
Remember to replace the BASETYPE text with an appropriate basetype such as part, doc, device or action. For instance, by declaring : <type name="part" and basetype="part" - this will ensure that the Reference Import is available from all part items and that only references from other parts will be imported.

A number of additional attributes can be added to further customize the Reference Import. Visit <import-ref> element to read more about the available attributes and their use.

External file configuration

Filetype and Filename

The external file that is used for Reference Import must be placed in the folder of the item.

item2-doc

The file-type of the file located in the item folder must be the same file-type as specified in the file-pattern attribute in the \<import-ref> element.

The Import-ref feature support input in the following formats: .xlsx, .csv and .txt.

You can traverse a specific file located in the item folder for references by defining the filename in the file-pattern attribute.


xxxxxxxxxx
<import-ref file-pattern="filename.csv" />

You might also specify file formats to traverse the first occurring file with a specific format in the folder by only specifying file format rather than a specific file.

For instance, the following file-pattern attribute specifies that the first occurring Microsoft Excel format document (.xlsx) in the item folder must be traversed for references to be imported to the item:


xxxxxxxxxx
<import-ref file-pattern="*.xlsx" />

The following snippet illustrates that the first occurring .txt document from the item folder must be traversed for references.


xxxxxxxxxx
<import-ref file-pattern="*.txt" />

File content structure

To import references, the document that is placed in the appropriate item folder must adhere to a specific structure, for the references to be imported.

The following table includes file-samples of how the files should be structured for common file types.

Filetype	Sample document structure for reference import
`.xlsx`	.xlsx sample document
`.txt`	.txt sample document
`.csv`	.csv sample document

Notice that the sample documents uses qty and pos as added columns to the pattern attribute. These attributes are optional and can be supplemented by other attributes from the ts_ref basetype or omitted.
To do this, you must add or remove the columns in the appropriate document whilst also adding and/or removing the attributes from the pattern attribute in the XML schema.

<import-ref> element

Attributes

Name	Description	Values and examples	Required
`name`	Name of element. Name attribute must be defined.	`name="default"`	✔️
`title`	Title defines the appearing text on the button.	`title="Reference Import"`	✔️
`pattern`	defines which attribute(s) that is used from the specific basetype column to filter for items. The `pattern` attribute allows for the possibility to add values to associated reference attributes.	`pattern="#filter#attribute"` Any number of basetype columns can be used as filtering (`#filter`) for identifying existing items in Highstage. Attributes used as filters must consist of attributes from the specified basetype columns. Similarly, `#attribute` can be used to assign associated values to elements on the reference such as quantity (qty) or position (pos). Any number of attributes can be added. Associated attributed to the reference must consist of existing attributes on the basetype ts_ref	✔️
`file-pattern`	Defines a specific file or first occurring file in the folder with a specific file-type that should be accessed for importing references. Specific file: `file-pattern="filename.csv"` First file in folder of specific file type: `file-pattern="*.csv"`	Accepted file formats includes plain text and comma separated value formats. Ex. `.xls` `.xlsx` `.csv` `.txt`	✔️
`basetype`	Defines which references to be imported depending on the basetype of the referenced item.	*`basetype="part"`	✔️
`create`	Adds or remove the `Create` button for references not found. Enables or disables the possibility to create items for references that are not found	Enable (Default): `create="1"` Disable: `create="0"`	❌
`subtypes`	Defines which references to be imported based on subtype(s). One or more subtypes can be added, separated by `,`. Items with other subtypes will be listed as `items not found` and will be omitted from the reference import.	All subtypes (Default): `subtypes="*"` Specific subtype: `subtypes="DOCU"` More subtypes: `subtypes="DOCU,PART"`	❌
`clear-on-import`	Enabling `clear-on-import` will delete existing references on the item and update with references and attributes from the associated reference import file. disabled `clear-on-import` will retain existing references and reference attribute values and only add new occurring references from the associated reference import file.	Enabled: `clear-on-import="1"` Disabled : `clear-on-import="0"`	❌
`ignore-headers`	Defines the number of top rows to be ignored when importing references from a file. Can be set to any positive value.	`ignore-headers="1"` will omit the first line in the file.	❌
`aggregate`	Enables the possibility of importing multiple references to the same item. The `pattern` attribute must only have one associated element attribute for aggregate to function. An example is provided below.	Disabled (Default): `aggregate="0"` Enabled: `aggregate="1"`	❌

Samples

The following samples provides you with a number of different implementations of Reference Import.

Importing part references from a .xlsx document

This sample imports references from a .xlsx file located in the Item folder. This import will reference items with the part basetype and all subtypes. Through the pattern attribute, the items are identified using the #item (Item ID). In addition, #qty,pos adds these column values to the added references.


xxxxxxxxxx
<type name="part">
    <import-ref name="default"
    title="Import"
    pattern="#item#qty,pos"
    basetype="part"
    clear-on-import="1"
    subtypes="*"
    file-pattern="*.xlsx"
    ignore-headers="0"
    create="1"
    aggregate="0"/>
</type>

Note!
The pattern attribute can use any column holding either a primary and secondary keys as an identifier for the item references. This could, for instance, be an item column or a SKU (Stock Keeping Unit).
Similarly qty and pos is used as an example for added reference attributes. Any column from the ts_ref basetype can be added to the pattern attribute as added reference attributes.

The .xlsx file content must follow the following structure:

example-snippet

Clicking on the the Reference Import button with this current sample setup will now prompt the following pop-up:

excel-snippet-export-clicked

Clicking Import references will attach all the listed references:

excel-snippet-export-resolved

Import using aggregate

The aggregate attribute supports the possibility of adding any number of references to the same item.

This sample will create three separate references to the ECAD11253-1A. Each with a unique POS attribute associated with the reference (1A, 2B, 3C).

The .xlsx file follows the following structure:

aggregate-file-snippet

The following snippet is added to the custom.schema.xml:


xxxxxxxxxx
<type name="part">
    <import-ref name="default"
                title="Import references"
                pattern="#item#pos"
                basetype="part"
                clear-on-import="1"
                subtypes="ECAD,MCAD"
                file-pattern="aggregate-references.xlsx"
                ignore-headers="1"
                create="1"
                aggregate="1"/>
  </type>

Notice that the header row with ITEM and POS is omitted from being read as a reference by specifying ignore-headers="1".

Clicking Import references will prompt the following pop-up:

item2-aggregate-clicked

Clicking Import references will attach the listed references:

item2-aggregate-execute

Frequently Asked Questions

Why does `clear-on-import` not remove all references?

For creating new Reference Import profiles - you must declare a basetype (Action, Part, Document, Device, Action). For that profile, only items of that basetype will be imported. Similarly, if the clear-on-import is enabled, only references to items of that basetype will be removed prior to the import of new references.

For instance, if your Reference Import profile has specified Part as it's basetype, existing references to items of type doc (Documents) will not be automatically removed prior to import of new part references.

highstage_footer