Section Two: Understanding each component of the XML

This table provides a general understanding of the structure and general notes about each node.

XML Node

Description

<?xml version=”1.0″?>

Required for XML document

Initialization

</ImportData>

Initial Root Node that is required.

</Customer>

Required.

</Hierarchy>

Required – Contains all hierarchy key information as well the three main sections <Divisions>, <Models>, and <MasterPartsList>

</DivisionKeys>

For reference only – This will contain ONLY the Key fields needed to make your Division unique. Your fields will vary. Can be N number of fields. These need to be set up prior to XML import.

</ModelKeys>

For reference only – This will contain ONLY the fields needed to make your model unique. Your fields will vary. Can be N number of fields. <key>Year</key> is an example of how to make a model more unique. These need to be set up prior to XML import.

<Key>Composite Key</Key>

</IplKeys>

For reference only – This will contain ONLY the fields needed to make your IPL unique. Your fields will vary. Can be N number of fields. These need to be set up prior to XML import.

</ChapterKeys>

For reference only – This will contain ONLY the fields needed to make your Chapter unique. Your fields will vary. Can be N number of fields. These need to be set up prior to XML import.

<Key>Motor Label</Key>

</AttachmentKeys>

For reference only – This will contain ONLY the fields needed to make your Attachment unique. Your fields will vary. Can be

N number of fields.

</Divisions>

Required – Will contain child

<Division> nodes that will directly create your division hierarchy.

<Value>Model One</Value>

<Value>Model Two</Value>

<Value>Model Three</Value>

</Attribute>

<MultiValue>Model One</Value>

<MultiValue>Model Two</Value>

<MultiValue>Model Three</Value>

</Attribute>

</Attributes>

Attributes are listed under the <Attributes> node. Note there are two valid formats for listing the attribute value, one with the <Value> tag and one without. Note that if a translation is requested, the <Value> format is required. Multi-value attributes can also be added in this way, in which case the <Value> or <MultiValue> tag is also required. Each term added for the multi-value attribute needs to be contained in its own <Value> or <MultiValue> tag.

</Division>

The actual division you want created. Can have N number of child <Division> nodes for nested Divisions. Name will be the actual name displayed in DMRT. Key is what makes your division unique. If the key is the name, name is not required to be listed as an attribute but should also be the key value.

All fields that build the KEY value should be listed as an attribute, except for name. This applies to all hierarchy types (Divisions, Models, IPLs, Chapters, Attachments)

Visibility groups can be assigned to the Division on this node, but note that the Visibility Group must already exist; Division node will not create any Visibility Groups.

</Attributes>

</Model>

When listing models under any Division, only the name and key field attributes are required. Another section <Models> will allow for full

fulfilment of the model information.

Again, Model Code, Model year, and Model type are just the fields that make this particular Model unique. You may only need one field or more. If the field (attribute) is part of the key it CANNOT be blank and always requires a value.

</Models>

Where all the child <Model> nodes go and all model pertinent information.

<Model>

</Model>

This section displays an outline of possible child nodes for the Model. Attachments, Chapters, and IPLs can be listed within the Model tag. These are expounded upon below. The first section will show model attachments. The second section will show model Chapters, and the final section will show model IPLs.

</Attributes>

<Attribute Name=“Motor label”>Motors</Attribute>

</Attributes>

<Attribute Name=”Type”>AMotorA</Attribute>

</Attributes>

</ModelRef>

</Attachments>

</Model>

Model Attachments:

This is an example of a model as a

child node of the <Models> node that

has model attachments.

This particular example would yield the results:

Fridge Master – Model

Motors – Attachment Folder

Motor A – Model that is an Attachment

Do note that any models that are attachments <ModelRef> only need to list their attribute information.

This model attachment will also need to be listed as its own model under the <Models> section as a <Model>, but does not require a division reference in the <Divisions> section since it is already referenced as an attachment. Pay special attention that model attachments have the labeling <ModelRef> instead of <Model>. When listing the <ModelRef> as its own <Model> in the <Models> section, the key between the <ModelRef> and <Model> need to match exactly.

</Attributes>

<Attribute Name=“Chassis label”> Chassis</Attribute>

<IPLs>

</IPLs>

</Chapter>

</Model>

Model Chapters:

Chapters are set up like attachments; however, Chapters can have Models AND/OR IPLs. Unlike Attachments, that can only have Models as child nodes.

Do note the last Chapter attribute has a space. The attributes need to match the Key EXACTLY down to the sentence casing.

</Attributes>

<IPLs>

<Attribute Name=“Composite Key”>FMA2018A Door

</Attribute>

</Attributes>

<Description>Screw</Description>

<ContextNote>Metal</ContextNote>

</IplPart>

<Description>Handle</Description>

<ContextNote>Chrome</ContextNote>

</IplPart>

<Description>Cover</Description>

<ContextNote>Chrome</ContextNote>

</IplPart>

<ContextNote>Chrome</ContextNote>

</IplPart>

</IPLParts>

</IPL>

</IPLs>

</Model>

Model IPLs:

Note here that the IPL attributes follow a different structure. If you do not wish your field to be published as meta information in DMRT, then you can use “Composite Key” to store all the key information. Just make sure that your IPL Key is unique between models if you do not want it to have a shared Parts list. If you want it to share the same Parts list then you simply make the keys the exact same and the Parts list the exact same.

Description is not required but if omitted will default to “NEEDS DESCRIPTION” if creating a new Part that is not listed in MasterPartsList.

SortOrder is NOT currently respect in PartSmart Web but it is honored within DMRT.

Note: the IPL section is case-sensitive, so IPLParts and IplPart must be entered exactly as seen here.

</Hotspots>

</Image>

Images:

As of right now Models and IPLs are the only hierarchy items that support images via XML import.

If you desire to use images or literature, an additional ZIP file using windows compression (.zip) (Not winzip, 7zip, winrar, etc) will

need to accompany the XML. The zip file CAN have subfolders, which can be specified in the XML where you see “FilePath” to the left. Do note that FilePath should not have a leading slash, nor should it have the filename.

Supported image file types:

– Tif

– Jpg

– Png

– SVG[1]

<Translation IsoCode=”IT”>Da 31 settembre 2015</Translation>

<Translation IsoCode=”ES”>Desde 1 septiembre 2015</Translation>

</Translations>

The translations node can be used to translate Hierarchy Items (Models and Division Display Names), Part Names, Context Notes, and any attribute. As a pre-requisite, the IsoCode used in the XML must first be set up for the account. See Appendix A for a list of appropriate IsoCodes to use.

Custom attributes tagged with a <Translations> tag must already exist; the translations node will not create new attributes. These custom attributes must also be marked as Allow Translation = TRUE or the validation will fail and return an error.

</SerialVins>

Serial/VINs are listed under the <Model> tag within the <Models> Section. Each serial tag takes a type (case insensitive):

– Single

– Closed

– Open

The Prefix attribute is required, but the Start attribute is only required on Serial Type = Open or Closed, and the End attribute is only required when the Serial Type = Closed. The Serial/VIN list will then be processed and related to the appropriate Model under which it resides in the XML.

If the Serial setting Serial Prefix Character Count is set, the Prefix must abide by this rule. If the prefix character count doesn’t match the configured setting, an error will be returned when processing the Serial Vin from the XML.

<Value>* Override Chassis</Value>

</Attribute>

</RelationAttributes>

Relation attributes are listed under the IPL tag. The override name will use an attribute Name of “Name” and the <Value> tag will be used to capture the override name this IPL will use in relation to this model.

<Parts>

<Attribute Name=”Notes”>Notes</Attribute>

</Attributes>

</Part>

</Parts>

</MasterPartsList>

Once we fulfil all the models in the <Models> section, the final node is <MasterPartsList>. Description is required for a new part.

Note that If PartNumber is “blank”, you must generate an MD5Hash of the description and prepend the string “ARI” to the MD5Hash and finally set “IsInternal” on the part to be true.

An Example would be “ARI1A51489”

Do be careful including parts in the MasterPartsList section. This caution is provided because if the part already exists in the system and has several different descriptions, the masterpart description will now replace all the varying descriptions.

Included in the MasterPartsList are the following sections (under each individual <Part> node).

</RelatedParts>

RelatedParts is a section included under the Part tag. Options for relation type include:

· Included

· Cross-Sell or CrossSell

· Up-Sell or UpSell

These parts will be related to the part listed in the parent Part tag. The related part must already exist in the system before being added to the relation.

</Supersessions>

The Supersessions node lists each individual Supersession. The top list node includes a GroupType attribute. When the GroupType is AND, the part is replaced by ALL of the parts listed in the group. When the GroupType is OR, the part is replaced by ANY of the parts listed in the group.

An optional “Action” attribute can be provided, which will specify the action to take on the Supersession group. If omitted, default is PurgeAndReplace. On a PurgeAndReplace, all current Supersessions are deleted and replaced with the specified Supersessions from the XML. Other options include Upsert and Delete. Upsert will update only the Supersessions listed. Delete will remove all the supersessions from the parent PartNumber. Note: If Delete is specified, the <Supersession> nodes are ignored in favor of deleting all of the parent part’s supersessions.

Each Supersession node then contains a PartNumber, Uom, a Quantity, and IsMandatory attributes. Uom is expecting one of the following values:

– Each

– NotSpecified

The default if unmatched (or blank) is “NotSpecified”. Quantity should be a numeric, integer value. And IsMandatory is expecting one of the following values:

– True

– False

Note that the parts listed for Supersession must already exist in the system; the Supersession section will not create new parts. They need to be included in either the MasterPartsList or the IPLParts sections for creation. For more details on the Supersession node, please see Supersession Samples in Appendix A.

<Audience>Default</Audience>

</Pricing>

Pricing nodes are specified for each pricing entry to be added for the parent <Part>. Tags expected are Audience, MSRP, Cost, and AsOf.

– Audience: A text field to match the audience for which the pricing is being added. If there is only a single “Default” Audience specified for the OEM and this attribute is missing from the XML, it will add the pricing to the “Default” audience. Otherwise an error will occur. Note: the Audience specified must already exist in order to add pricing from the XML.

– MSRP & Cost: Numeric values. If a negative is represented in these fields, the absolute value is saved as the pricing value. In this example, a cost of -12 would be saved as 12. If both MSRP and Cost are 0 or blank, it will trigger a removal of the audience’s specified pricing.

– AsOf: This is a date field which corresponds to the As Of Date.

</Dimensions>

The Dimensions node will add measurement data for the Part. Only one Dimensions node is supported per Part. It takes four sub-elements:

– UOM: must match one of the following values exactly: in, ft, mm, cm, m

– Length, Width, Height: Non-negative numeric value greater than or equal to 0.01

All four elements are required to be present. If any one of the elements is missing, the Dimensions upload will fail (part should still be loaded unless a Part error occurs. If all of the elements are missing or 0, the current measurements will be removed from the Part specified.

</Deletes>

Finally, the <Deletes> node should specify all those items intended for delete. The Cascade flag can be used to propagate the delete to all its child items as well. The default is Cascade=”FALSE” so only the parent item will be deleted (potentially orphaning its children).

Valid child nodes within the <Deletes> section include the same format as the previous nodes in the XML document. That is:

– Divisions

– Models

– IPLs

– IplParts

– Images

– Literatures

– MasterPartsList

</Attributes>

</Division>

</Divisions>

Name and unique key identifier are required to identify the Division to delete. Custom attributes don’t need to be specified, just the attributes that make up the Unique Key for the Division.

Cascade attribute can be specified on each Division node, default is FALSE.

<Parents> node can optionally be used to specify only those relationships from which the Division should be deleted.

</Attribute>

</Attributes>

</Model>

</Attribute>

</Attributes>

</Model>

</Attribute>

</Attributes>

<!–will only delete from these parents –>

</Attribute>

</Attributes>

</Division>

</Parents>

</Model>

</Models>

Name and Unique Key identifier are required to identify the Model to delete. Custom attributes don’t need to be specified, just the attributes that make up the Unique Key for the Model.

Cascade attribute can be specified on each Model node, default is FALSE.

<Parents> node can optionally be used to specify only those relationships from which the Model should be deleted.

<Value>Chassis</Value>

</Attribute>

</Attributes>

</IPL>

</IPLs>

Name and unique key identifier are required to identify the IPL to delete. Custom attributes don’t need to be specified, just the attributes that ake up the Unique Key for the IPL.

Cascade attribute can be specified on each IPL node, default is FALSE.

<Parents> node can optionally be used to specify only those relationships from which the IPL should be deleted.

</Image>

</Images>

FilePath and FileName are required to identify the Image to delete.

<Parents> node can optionally be used to specify only those relationships from which the Image should be deleted.

Note: The Cascade attribute is not supported for Image nodes because there would be nothing to cascade to.

<Literature FilePath=”Literature” FileName=”LIT01.pdf”

VisibilityGroups=”US” Category=”Documents”>

</Literature>

</Literatures>

FilePath and FileName are required to identify the Literature.

Visibility Groups: Visibility groups can be assigned to the Literature on this node, but note that the Visibility Group must already exist; Literature node will not create any Visibility Groups. If any invalid visibility groups are listed, the literature will fail to import.

Category: If literature categories are set up (under Data Settings in DMRT), this field can be used to assign exactly one category to the literature. If the literature is repeated throughout the XML document, only the first Category will be assigned to the literature. If Categories are set up in the DMRT account, the default category will be assigned to newly imported literatures unless a Category is listed in the XML document.

Deletes:

<Parents> node can optionally be used to specify only those relationships from which the Literature should be deleted.

Note: The Cascade attribute is not supported for Literature delete nodes because there would be nothing to cascade to.

</IPLParts>

<Parts>

</Part>
</Parts>

</MasterPartsList>

Parts marked for delete can be listed in either the IPLParts section or the MasterPartsList à Parts section. PartNumber is required on both the IplPart node and the Part node in order to identify the Part to delete.

<Parents> node can optionally be used to specify only those relationships from which the Part should be deleted.

Note: The Cascade attribute is not supported for IplPart and Part nodes because there would be nothing to cascade to.

Part Status can be set by adding a child attribute node with the name of “Status” under the part’s attributes node. A value of 1 indicates an active part status and a value of 0 indicates an inactive part status.

If you have an existing dataset and are performing an update, the most important thing is to ensure that your Division, Model, IPL, Chapter, and Attachment keys (aka <Attributes>) match the existing DMRT keys.

If you have a new dataset and are performing a first load it is very important that you are able to reproduce the same keys the next time an update is needed so that duplicate models or divisions are not being created.

[1] SVG processing will convert the SVG file into a usable image, returning a bill of materials parts list and a list of hotspots. The SVG process will use SVG settings as defined in the SVG Settings section for BOM headers, default file type for conversion, etc. Hotspots & BOM list will give precedence to those returned from SVG processing. If none is returned from the SVG process, the XML Import will fall back on those listed in the XML:

If hotspots are listed in the XML for an SVG that returns hotspot info, the XML hotspots will be ignored.
If BOM parts list is included in the XML for an SVG that returns BOM parts list, the relation to the IPL will not be created, but the SVG data will be used instead. The XML parts will still be created.

Print this article

How can we help you today?

DataManager RT

Section Two: Understanding each component of the XML

How can we help you today?

DataManager RT

How can we help?