Important: With the 2023.3 release, the JSON outbound integration that uses the 'Product Data Exchange' delivery method will no longer be supported. It is advised that the individual who maintains PDX integration configurations set up the new STEPXML outbound integration that uses the 'Product Data Exchange 2' delivery method and disable the old JSON outbound integration before the 2023.3 release.
Using specific tags within Advanced STEPXML as defined on the PDX Outbound Integration Endpoint (OIEP), users can export metadata on product, image and document, and entity reference types from STEP to PDX. Once exported, reference metadata values will display as part of a composite attribute in PDX. With this additional information, users within PDX are able to access and utilize more detailed information regarding references of products exported to PDX.
Note: Although a product reference type is used in the example below, the setup in workbench will be the same regardless of whether the user is exporting product, image and document, and/or entity reference types metadata to PDX. However, the STEPXML tags will differ, depending on the reference type. For more information regarding tags in STEPXML, refer to the STEPXML Tags and Examples topic in the Data Exchange documentation here.
Prerequisites
While this topic will provide an overview of the steps /configurations required to export metadata on various references types, it is expected that anyone exporting metadata from references to PDX have an overall understanding of the following topics:
Exporting Metadata on Reference Types
Users can export metadata from reference types to PDX as part of a composite attribute by including specific STEPXML tags within the Advanced STEPXML format. Before exporting metadata on a reference type to PDX, a reference type (in this example, a product reference type) must first be configured.
- Create a product reference type. In this example, the user has created a product reference type with the ID and Name 'Product to Product Case.' Note the highlighted valid attribute 'CaseSupplier.' The 'CaseSupplier' attribute will contain the metadata on the product reference type.
- Make the newly created product reference type 'Product to Product Case' valid on the product you would like to export to PDX. In the example below, the user has made the 'Product to Product Case' reference type, with a target of 'Hard Case for Bose SoundLink Micro Bluetooth Speaker,' valid for the product 'Bose Soundlink Micro (Black).' The attribute 'Case Supplier' has four metadata values (Aenllosi, SKB, Gator, Penguin) for this reference. The goal is to make these metadata values part of a composite attribute within PDX once the 'Bose Soundlink Micro (Black)' is exported to PDX.
- In the Advanced STEPXML format template, include the following tags, as shown in the example below.
<ProductCrossReference Type="Product to Product Case"> <MetaData AttributeID="CaseSupplier"/> <Product Referenced="true" Embedded="true"> <Name/> <Values/> </ProductCrossReference>
Note: The example presented in Step three is only a portion of the Advanced STEPXML template, and not the entire template.
- Using the PDX OIEP, export the selected product to PDX.
The product 'Bose Soundlink Micro (Black),' along with the metadata on the 'Product to Product Case' reference type, has been exported to PDX.
The image directly below shows how the composite attribute would be presented in PDX. Note that the title of the composite attribute is titled 'Product to Product Case,' based on the ID of the product reference type.
For more information on the PDX Outbound Integration Endpoint, refer to the PDX Outbound Integration Endpoint Configuration topic here.
Assigning an Alternative Title for Reference Types within PDX
By default, composite attributes made up of reference type metadata are titled based on the ID of the reference type that contains the metadata. For example, if the title of a composite attribute in PDX is 'Product to Product Case,' then this would also be the ID of the reference type, 'Product to Product Case.' However, users may want the composite attribute that contains the reference type metadata to have a different title. This can be achieved by assigning the 'PDX Composite Attribute' attribute to the reference type.
The following configuration steps must be performed to set up and use the 'PDX Composite Attribute ID' attribute:
- First, a description attribute must be created. The ID of this attribute must be added to the PDSDelivery.CompositeAttributeID=[attribute_id] property in the sharedconfig.properties file on your STEP application server. For example:
PDSDelivery.CompositeAttributeID=PDXCompositeAttributeID
The 'PDX Composite Attribute' attribute can be given any ID or name and can be created anywhere in your system. In this example, the name of the attribute is 'PDX Composite Attribute' and the ID of the attribute is 'PDXCompositeAttributeID' and has been created within an attribute group named 'PDXReferenceAttributes.'
- The attribute must be made valid on the Reference-Type (Reference-Type user-type root) object type, which is located in System Setup under Object Types & Structures > Basic Object Types.
Note: The 'PDX composite attribute ID' attribute is made valid on the reference type object, not on the reference type link between the source and target product.
Once the bulleted items listed above are implemented, create a value for the 'PDX Composite Attribute' attribute, which will now be included as a description attribute within the 'Product to Product Case' reference type. In the example below, the user has assigned the value 'ProductCase' to the 'PDX Composite Attribute.'
With the 'PDX Composite Attribute' now assigned a value, when the 'Bose Soundlink Micro' (Black) product is exported to PDX, the composite attribute on the 'Product to Product Case' reference will be titled 'ProductCase,' based on the value of the 'PDX Composite Attribute' attribute.
For more information on the PDX Status Attribute Group attributes, refer to the PDX Channel Status Monitoring section of this documentation here. For more information on creating attributes, refer to the Creating Attributes topic in the System Setup documentation here.
Handling Nested Data Structures
Nested data structures are sometimes required to capture pieces of product information. A good example is nutritional information describing the contents of a product at various scales. Consider the GDSN modeling of this data:
Nutritional Information: group{
Preparation State: lov,
Daily Value Intake Reference: string+,
Nutrient Basis Quantity Type Code: lov,
Nutrient Basis Quantity: decimal,
Serving Size: decimal[],
Serving Size Description: string+,
Nutrient Detail: group{
Nutrient Type Code*: string,
Percentage of Daily Value Intake: decimal,
Measurement Precision: lov,
Nutrient Quantity Contained: decimal[],
Daily Value Intake Percent Measurement Precision Code: lov,
Nutrient Value Derivation Code: lov,
Description On Nutrient Qualifier: string[],
Nutrient Source: string+
}[],
Nutrient Basis Quantity Description: string+,
Servings Per Package Description: string+
}[]
To model this data as accurately as possible, the STEP data model is required to have a referential nature (i.e. using references to other objects) as illustrated below:
The referential structure needs to be included in the Advanced STEPXML Template of the PDX OIEP, by embedding the referenced data. Consider the example below:
<STEP-ProductInformation ResolveInlineRefs="true" FollowOverrideSubProducts="true">
<ContextList ExportSize="Minimum"/>
<CrossReferenceTypes ExportSize="Minimum"/>
<UnitList ExportSize="Minimum"/>
<AttributeList ExportSize="Minimum"/>
<Products ExportSize="Minimum" FlattenHierarchy="false">
<Product>
<Name/>
<Values/>
<ProductCrossReference Type="Product_NI" ExportSize="Minimum">
<MetaData/>
<Product Referenced="True" Embedded="True">
<Values/>
<ProductCrossReference Type="NI_ND" ExportSize="Minimum">
<MetaData/>
<Product Referenced="True" Embedded="True">
<Values/>
</Product>
</ProductCrossReference>
</Product>
</ProductCrossReference>
</Product>
</Products>
<Assets ExportSize="Referenced"/>
</STEP-ProductInformation>Important: In the example used above, the referential structure is modeled using STEP Objects of the Product type tied together by Product cross-references, but Entity-based structures would be equally valid for transferring a nested data structure to PDX.
On the PDX side, the attribute values of each reference and its target object are consolidated to form a row of values in a Composite Attribute. PDX Composite attributes closely resembles multi-valued Data Containers in STEP, but they are able to contain other Composite Attributes, thus forming a 'tree' of data.
By default, composite attributes are titled according to the name of the given STEP reference type, or the ID of the reference type if no name is available. However, the recommendation is to create a meta data attribute for the reference types tying together the nested data structures that explicitly sets the ID of the Composite Attribute in PDX.
Specifically, a description attribute must be created, made valid for the reference types of interest, and the ID of this attribute must be added to the PDSDelivery.CompositeAttributeID=[attribute_id] property in the sharedconfig.properties file on your STEP application server. For example:
PDSDelivery.CompositeAttributeID=PDXCompositeAttribute
The ‘PDX Composite Attribute' attribute can be given any ID or name and can be created anywhere on your system. In this example, the name of the attribute is 'PDX Composite Attribute' and the ID of the attribute is 'PDXCompositeAttribute,' and has been created within an attribute group named 'PDX Reference Attributes.’
Now a value can be set for the created meta data attribute, allowing us to change the composite attribute ID in PDX. In this example, we’ll set a value for the ‘PDX Composite Attribute' attribute, which will now be included as a description attribute within the ‘Product_NI' and 'Product_ND’ reference types, changing the IDs of the two composite attributes in PDX to 'Nutritional Information' and 'Nutrient Details’ respectively.
Assigning an Alternative Title for an Attribute that is Part of a PDX Composite Attribute
Important: This is for the JSON integration only.
Just as the 'PDX Composite Attribute' attribute can be used to create an alternate title for a reference type that is exported to PDX, it can also be used to create an alternative ID for an attribute that is part of a composite attribute.
Note: To assign an alternative title for an attribute that is part of a PDX Composite Attribute, the attribute must be made valid on the Attribute (stibo.normalattribute) object type.
As an example, the image below shows the product 'Bose BTS Hard Case' with 'ProductDimensions' as one of its attributes:
Because the 'Bose BTS Hard Case' product is referenced by the 'Bose Soundlink Micro (Black)' product using the 'Product to Product Case' reference type (as detailed earlier in this topic), when the Bose Soundlink Micro (Black) is exported to PDX, the 'ProductDimensions' attribute will be displayed as such:
However, if the user needed the title of the attribute to be something different than the ID of the attribute itself, a value could be assigned to the 'PDX Composite Attribute' attribute, as shown in the example below:
With the ' PDX Composite Attribute' attribute assigned a value (in this case, 'ProductSize'), the attribute, once exported along with the product, would instead be displayed as shown in the image below:
The 'ProductDimensions' attribute is now identified within PDX by the value assigned to the 'PDX Composite Attribute' attribute, 'ProductSize.'
For information on how to make an attribute valid on the Attribute object type and the Reference object type, refer to the Attribute Metadata on Attributes topic in the Attributes section of the System Setup documentation here. The steps for making an attribute valid on the Reference object type are the same as those used for making an attribute valid on the Attribute object type.
For information regarding Reference and Link Types, refer to the Reference and Link Types topic in the System Setup documentation here.
For more information regarding Advanced STEPXML, refer to the Advanced STEPXML Format topic in the Data Exchange documentation here.