Generic JSON Format

The Generic JSON format option significantly simplifies the work for STEP administrators and enterprise architects required to have STEP produce JSON (JavaScript Object Notation) messages.

Although the following alternatives provide a large degree of freedom in composing the JSON messages, they also require either programming skills and code management or custom development:

  • The OIEP Business Rules Based Message Processor option (here) can generate JSON messages constructed via business rules and the public Scripting API.

  • Extensions developed either via the Extension API or by Stibo Systems. Refer to the STEP API Documentation, available on the Start Page.

While the Generic JSON option is not as flexible as the others, it requires no programming skills and can be configured by users with basic knowledge of STEP and JSON. Refer to the Template, Mapping, and Output section and the Generic JSON Configuration Examples section below for illustrations.

Format Availability

Generic JSON is available for selection in:

  • Export Manager - refer to Creating a Data Export here

  • OIEP - refer to Creating an Outbound Integration Endpoint here

Mapping

This format requires creating a data map between STEP and the data being processed, and may also include data transformations. For details, refer to Data Mapping here.

Outbound Data

The same parameters are available in both Export Manager and OIEP:

  • Template - For a Generic JSON export, a template including instructions and placeholders determines how data should be handled, then STEP data is mapped into the JSON template. For details, refer to Outbound Map Data Options documentation here.

    Since no undo functionality is available in the Template field, it is good practice to use an external source-code editor for creating and editing a template. To test a template's validity for output, paste the code into STEP.

  • Format JSON Document - This option is disabled by default. This means that the data is output into a single line of comma-separated attribute / value pairs as shown below.

    Check the 'Format JSON Document' parameter to export the data in a formatted output for development and debugging purposes.

Export Manager

OIEP

Template, Mapping, and Output

Selecting the Generic JSON format option displays the default template which can be used to export basic property ID and Name together with attribute ID and value pairs for product objects.

The following instructions are the only ones available for the Generic JSON format option:

"__type": "__record"

This key value pair must be included in a template and indicates that the enclosing JSON object should be resolved / populated once for every object to be handled by the format option.

"__target <OPTIONAL IDENTIFIER>"

This instruction defines a mapping target and functions as a placeholder for a JSON string value (on the right side of the colon (:)). When provided, the optional identifier is shown in the Map Data screen.

Refer to the Generic JSON Configuration Examples section below for how the instructions work with mapping to produce messages that include data beyond basic properties and attribute values.

Considerations

  • You cannot map data as a Boolean or a number. Data output using the "__target <OPTIONAL IDENTIFIER>" instruction is either a string or null (when explicitly mapped but no data is available).

  • When data is mapped to an array, as in the 'values' example below, an empty array is output if no data is available (for example, if there were no values for the products).

  • As with the Excel or CSV format plugins, root objects for the export (i.e., the objects "__type": "__record" resolves against) must be of the same super type (products, classifications, assets, entities, etc.)

Using the default template, the Map Data step shows the mapping targets (right side) extracted from the template. The targets are mapped using the data sources (left side) and use standard mapping functionality, as defined in the Outbound Map Data - Mapping Targets topic here.

Before mapping, the Map Data steps is as shown below:

After mapping, the targets are supplied and transformed as required:

  • <ID> is mapped to the 'ID' target

  • <Name> is mapped to the 'Name' target

  • All Attributes is mapped to the 'values' section to recursively populate all attributes that have a value for the products to be exported.

    Expand the 'values' mapped section and click the transform button () to select which aspect of the mapping to use for the respective targets shown below:

    • For the 'attributeID' target, select the 'ID' aspect with default semicolon separator.

    • For the 'value' target, select the 'Value and unit' aspect with default semicolon separator.

Exporting with the 'Format JSON Document' option checked produces the following output:

Generic JSON Configuration Examples

Data can be exported using attributes or data path data sources, as illustrated in the examples below.

Mapping Attributes Example

This example shows how to use the 'Select Attribute' or 'All Attributes' sources to export the following data for each product using the Generic JSON format:

  • Product ID

  • Product Name

  • Product EAN (single valued attribute on product)

  • Product Target Market LOV value IDs as string array (multivalued LOV based attribute)

  • Product attribute values for specific attribute group with values output as string array to account for multivalued attributes

  • ID and EAN (attribute value) for Accessory objects (product objects referenced with a specific reference type)

  • IDs of Manuals (assets referenced using a specific reference type)

The template is:

Copy 
{
    "products": [
        {
            "__type": "__record",
            "id": "__target ID",
            "name": "__target Name",
            "ean": "__target EAN",
            "targetMarketIDs": [ "__target TargetMarketIDs" ],
            "specifications": [
                {
                    "attributeID": "__target SpecAttributeID",
                    "values": [ "__target SpecValues" ]
                }
            ],
            "accessoryReferences":[ 
                {
                    "targetId": "__target AccessoryID",
                    "targetEAN": "__target AccessoryEAN"
                }
            ],
            "pdfManuals": [ "__target ManualID" ]
        }
    ]
} 

The Map Data screen prior to mapping includes the following targets:

Mapping of ID and Name are supplied by the template. EAN is mapped via the Select Attribute data source.

For Target Market IDs, use the Select Attribute data source, and then select the 'LOV Value-ID' aspect to export the value IDs as shown below.

For the 'specifications' section, use All Attributes to map an attribute group (CategorySpecificAttributes) and then use the aspect parameter to output attribute IDs.

For the 'accessoryReferences' section, where both the target object ID and the EAN value from the target objects must be exported, use the 'Multi level References' option.

In this example, in the 'Multi level References' data source uses the 'Accessory' reference type and the 'Referenced node' source are selected to map the 'Accessory ID' target. The <Accessory> ID is initially mapped to both the AccessoryID and the AccessoryEAN targets. The mapping on the AccessoryEAN row is manually deleted. For the AccessoryEAN row, the 'Multi level References' data source uses the 'Accessory' reference type again, and the 'Referenced node attributes' source allows selection of the EAN attribute.

For the 'pdfManuals' string array to contain the IDs of assets referenced with a specific reference type, the type can be mapped directly from 'Asset References':

The image below show a sample of the exported message.

Mapping Data Path Example

This example shows how to use the 'Data Path' data source option to nest data for children objects inside the JSON structure for the parent.

Note: This mapping is used when only the parent level is selected on the Select Objects step for the Generic JSON format. The 'Only export selected objects' checkbox must be checked on the Select Objects step.

The template is:

Copy 
{
    "products": [
        {
            "__type": "__record",
            "id": "__target ID",
            "name": "__target Name",
            "children":[ 
                {
                    "id": "__target ChildID",
                    "ean": "__target ChildEAN"
                }
            ]
        }
    ]
} 

Mapping of ID and Name are supplied by the template.

For the 'children' section, use the 'Data Path' data source and add the 'Child' step.

Expand the 'children' section, map ID to the 'ChildID' placeholder, map the desired attribute to the 'ChildEAN' placeholder, and remove the extraneous Child/ mappings.

Note: The red text (Invalid mapped field) is displayed when the mapping can result in exporting child objects.

The image below shows the output message where 'I-SalesItemFamily-1311' is selected for export: