The multi-level references data source option allows you to map data from referenced or ancestor objects. You can also map so that one or more additional rows are generated for referenced objects. This option is available and mapped the same for product, classification, asset, and entity objects.
Note: The multi level references data source is available for most formats that require mapping. This option is not supported for the Excel Smartsheet format. This option is also not supported in the STEPXML format since mapping is not available.
For example, a customer hierarchy is created in STEP using entity nodes. Each customer has a reference of the type Region to a Location. Each Location has a reference of type Address to specific addresses. When the customer hierarchy is exported, it is possible to follow the references and export data from the address objects.
Using the Multi Level References option allows the following information from the object to be exported:
- Names of referenced objects.
- Attribute values on referenced objects.
- Meta data attributes on references with values.
The output of the 'Insert References' data source (defined in the Insert References - Data Source Outbound topic here) gives access to the same data as the Multi Level Reference data source, but 'Insert References' writes each object on an individual row to produce a simplistic layout with clear relationships between the objects.
The user interface for the mapping step of the Export Manager tool and the outbound integration endpoint tool are not exactly the same. For Export Manager, mapping is described in the Export Manager - Map Data topic here. For OIEPs, mapping is handled in the Output Templates section under the Format parameter as described in the OIEP - Event-Based - Output Templates Section topic (here) or the OIEP - Select Objects - Output Templates Section topic (here).
For more information about the additional wizard steps, refer to the Creating a Data Export topic (here) or the Creating an Outbound Integration Endpoint topic (here).
After mapping, most output options can be altered using transformations. For more information, refer to the Outbound Map Data - Transform topic here.
When multiple references exist, the options for the output are:
- All references in a single field, separated - This is the default setting for the 'Multi Valued' option.
- One reference per field - Use the 'Item [ ]' option as a separate mapping to output each reference in an individual field.
Examples
The following topics include examples using this data source option with:
- Single value reference types (here)
- Multi-value reference types (here)
- Entities (here)
- Products (here)
Mapping Multi Level References
- Select the data to be exported for the outbound tool. For more information, refer to the Data Exchange topic here.
Note: Export Manager includes the ability to restrict the output based on several options regardless of mapping. For more information, refer to the Export Manager - Select Objects topic here.
- On the Map Data step, in the left panel, select Multi level References data source.
- In the right panel, click the right arrow icon to display the Multi Level data source wizard.
- In Select reference, highlight the relevant source reference type and click Next.
- In Select path, the legal reference types available are displayed in the dropdown. Select the required reference type.
To add an additional reference type, click the 'plus down arrow' button, 
.
- Select the necessary reference levels and click Next.
Based on selected reference, the following options may be available:
- Single valued - exports data from the referenced object of the selected type where only one is allowed.
- Multivalued - exports data from all referenced objects of the selected type where multiple references are allowed. All reference values are output in a single field, with a separator character.
- Item [ ] - exports data from only a single referenced object, determined by the selected Item number. For example, Item [1] only exports data from the first referenced object.
- Item [ ] with multiple references - use the previous 'Item [ ]' option to create a separate mapping for each of the available references. Each mapping will show a unique number within the brackets, for example: Item [1], Item [2], Item [3] will produce information for three references, each in a column. For details, refer to the Multiple Reference Metadata in Separate Fields section of the Multi Level References - Examples with Multi-Value Reference Types topic here.
- X - Click the delete button to remove any unnecessary levels.
- In Select Source, choose the type of data to be exported:
- Referenced node exports the names of the objects. The Select Attribute screen is disabled.
- Referenced node attributes exports attribute values on the referenced objects for the selected attribute. Click Next to display the Select Attribute screen.
- Reference meta-data attributes exports attribute values applied to the reference. Click Finish.
- If needed, in Select Attribute, use Browse or Search to locate the attribute that holds the values to be exported and click Finish.
The multi-level reference mapping is complete and displayed on the Map Data dialog.
- Complete any additional mappings and initiate the export.
The single object output includes the values for both of the Accessory Optional references. Although this example used the Excel format, any other format would produce the same output. In the following image, '.|Node|.' is the referenced product of the exported product. This is included since on the Select source step, 'Referenced node attributes' was selected and then for the Select attribute step, 'Country of Origin' was selected.
