---
title: "Define a related product group"
slug: "define-a-related-product-group"
updated: 2024-11-26T10:03:32Z
published: 2024-11-26T10:03:32Z
canonical: "docs.zilliant.com/define-a-related-product-group"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zilliant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Define a related product group

Related product groups allow users to combine a main product with its related products. This feature uses a [lookup table](/v1/docs/lookup-tables) to manage the group information and its corresponding products.

To create a related product group, follow these steps:

1. [Create a lookup table.](/v1/docs/define-a-related-product-group#create-a-lookup-table)
2. [Upload the group data into the lookup table.](/v1/docs/define-a-related-product-group#upload-the-group-data-into-the-lookup-table)
3. [Implement a Groovy script.](/v1/docs/define-a-related-product-group#implement-a-groovy-script)
4. [Upload the Groovy script into Zilliant CPQ.](/v1/docs/define-a-related-product-group#upload-the-groovy-script)

## Create a lookup table

### Before you begin

You need a lookup table to maintain the following data:

- Main and related product data
- (Optional.) Group hierarchical data

#### Main and related product data

Your lookup table must include at least two lookup columns to map the main product and the related product using the **onType** and **onAttribute** properties.

In the lookup table, you must set the **onType** property to the product and the **onAttribute** property to one of the following objects, depending on system requirements:

- objectName
- objectExternalId
- objectERPId

#### Group hierarchical data

Define group hierarchical data in the lookup table if your system doesn't have the navigation concept to reach related products through a group.

The group code and group description columns are optional, and there is no restriction on the number of levels if a group hierarchy concept is applied.

If the system uses a group hierarchy concept, you must define a naming convention for the group code and a delimiter to extract level information from the group code. For example, a recommended naming convention is **001, 001-001**, where `-` is the delimiter to indicate the group level. This group level indicator will be used in the default implementation to determine which group code and name to return to the UI.

### Procedure

1. [Create a lookup table](/v1/docs/lookup-tables#create-a-lookup-table).
2. [Add](/v1/docs/lookup-tables#add-a-lookup-table-column) and [configure](/v1/docs/lookup-tables#configure-a-lookup-table-column) lookup table columns for:
  - Main product
  - Related products
  - Simple group code
  - Group name

## Upload the group data into the lookup table

There are two methods to prepare data for main and related products:

- Define the ERP ID Add the ERP ID to the lookup table and lookup column, then synchronize the system with the ERP to obtain the needed data structure.
- Use the Excel download and upload feature Prepare the data in Excel, then upload it to the system.

The following image displays the data usage with a Groovy script:

![Related product mapping_groovy](https://cdn.document360.io/24f960e8-3c1c-4c18-a2c6-83b6ae4aab84/Images/Documentation/Related%20product%20mapping_groovy.png?sv=2026-02-06&spr=https&st=2026-11-02T14%3A49%3A15Z&se=2026-11-02T15%3A49%3A15Z&sr=c&sp=r&sig=jHbTyeqZtkfDOrMcejHbcEfHCFHK4YgiryItQdaMQ7k%3D)

## Implement a Groovy script

Use Groovy to obtain the groups and their related products based on the table showed on the image in the [previous section](/v1/docs/define-a-related-product-group#upload-the-group-data-into-the-lookup-table). In the Groovy script:

1. [Import classes](/v1/docs/define-a-related-product-group#import-classes).
2. [Configure the lookup table usage](/v1/docs/define-a-related-product-group#configure-the-lookup-table-usage).
3. [Execute the engine and return results](/v1/docs/define-a-related-product-group#execute-the-engine-and-return-results).

### Import classes

Import the following classes through a Groovy script:

- com.imc.model.Product
- com.imc.model.RelatedProductGroup
- com.imc.iss.groovy.GroovyLogger
- com.imc.iss.groovy.lookupTable.GroovyLookupTable
- com.imc.iss.configuration.services.RelatedProductHierarchyEngine

A Groovy script can use the [engine] variable, for example RelatedProductHierarchyEngine, that provides the following methods:

| Method | Purpose |
| --- | --- |
| void init(String tableName,String mainProductFieldName,String relatedProductFieldName) | Initialize the engine with the table name, main product column, and related product column. |
| void addGroupCodeField(String groupCodeFieldName,int levelIndicator) | Inform the engine about groupCodeFieldName and its level. |
| void addGroupNameField(String groupCodeFieldName, String groupNameFieldName) | Map the group code column and its corresponding group name column. |
| void setGroupCodeDelimiter(String groupCodeDelimiter) | Inform the engine about the naming convention of the group code. |
| RelatedProductGroup run() | Execute the default Java implementation based on the current sales item’s product. |
| addResult(RelatedProductGroup relatedProductGroup) | Add executed results to the engine. |
| List `<RelatedProductGroup>` getResults() | Return the added executed results to the user interface. |

### Configure the lookup table usage

1. Initialize the related product hierarchy engine with the table name, main product column name, and related product column name.
2. Specify the group code column and its corresponding level using the following method: `addGroupCodeField ([FieldName],[level indicator])`
3. Define the mapping between the group code column and the group description column using the following method: `addGroupNameField ([Group Code Field Name],[ Group Name Field Name]`

          Note

          

You must call `addGroupNameField` after `addGroupCodeField`.
4. Specify the delimiter for the group code column using the following method: `setGroupCodeDelimiter ("-")`

### Execute the engine and return results

After setting up the lookup table usage:

1. Use the `run()` method to activate the engine to retrieve the data. This method returns the RelatedProductGroup object.
2. Use the `addResult([RelatedProductGroup])` method to add the returned result to the result list.
3. Use the `getResults()` method to return the results to the system.

The following sample Groovy script uses the standard default implementation with a single table.

```
engine.init("RPH_TABLE1", "MAIN_PRODUCT ", "RELATED_PRODUCT ")
// Define the Group Code Field and Group Code Description
engine.addGroupCodeField("RPG1", 1);
engine.addGroupNameField("RPG1","RPG1_NAME ");
engine.addGroupCodeField("RPG2", 2);
engine.addGroupNameField("RPG2","RPG2_NAME");
// Set the delimiter usage in Group Code Value
engine.setGroupCodeDelimiter("-");
// Default Engine
def relatedProductGroup1 = engine.run();
engine.addResult(relatedProductGroup1);
// Return the result to Digital Sales Platform
return engine.getResults();
```

## Upload the Groovy script

Upload your Groovy script to Zilliant CPQ.

For details about uploading and configuring Groovy scripts, read [Upload a Groovy script](/v1/docs/upload-a-groovy-script). At Step 5, select **Related Product Hierarchy - custom script to return the related product hierarchy**.