In this section you will learn more about Customs Forms.
Lab Info
Lesson: Product Discount Data Management (Standalone Custom Form)
Target Audience: Certified Configuration Engineer
Estimated Time to complete: TBD
Requirements & Solution Author: Petr Rys
Solution Developer & Lab Author: Marcin Łuczakuczak
User Story / Requirements
Create a standalone Custom Form to help pricing managers manage discounts per Product Groups and Families.
Product Group is part of Product Master, Product Family is assigned per Product Group.
Each Product group belongs to 1 Product Family as per table Product Family Mapping.
Based on cumulative yearly revenue on the whole Product Family the customer has assigned Discount Level in Discount Level Definition Table.
Based on Product Group and Discount Level achieved by the Customer the sales agent has a "recommended discount" and a "maximum allowed discount" (Target Discount % and Max Discount %)
Details
Product Discount Data Management Custom Form allows user to perform these tasks:
Change Data - Pick a table, Change values in the table, without adding any rows
Add new Product Group - Add a group, Assign it to the product family, Assign to it all the required discounts for all the required levels
Discount for each additional level has to be >= to the previous level, otherwise validation fails
Add a product family - Re assign product groups to reflect new Product Family,
Add new discount level to existing product family - Create new discount levels. Levels must be continuous.
Each level 1 has to start on 0 Min Revenue. Each additional level has to have Min Revenue >= to the previous one
Assign new discounts for new levels. Discount for each additional level has to be >= to the previous level, otherwise validation fails
Learning Outcomes
At the end of the Lab, you should be able to:
Create Standalone Custom Form, Custom Form Type
Utilize Input Matrix as Custom Form input
Understand Custom Forms Workflow
Provided resources
Logics:
sCFO_ProductDiscountLib
Company Parameters:
ProductFamilyMapping, DiscountLevelDefinition, Discount
Acceptance Criteria
User can access a standalone Custom Form within the Analytics section to complete tasks listed in the Details section.
...
User can select one of three options: Modify data, Create new Product Group, or Create new Product Family.
...
A separate form will be displayed for each option
Tables with calculation results are available in the Calculations section, located on the right panel.
...
It is recommended to highlight any changes made to tables for better visibility and clarity.
...
After the user submits the form, changes should be saved in the corresponding company parameter tables. If a workflow has been added to the form, the changes should be saved after approval.
Sample solution
...
Lab Info
Lesson: Product Discount Data Management (Standalone Custom Form)
Target Audience: Certified Configuration Engineer
Requirements & Solution Author: Petr Rys
Solution Developer & Lab Author: Marcin Łuczakuczak
User Story / Requirements
Create a standalone Custom Form to help pricing managers manage Discounts, Product Groups and Families from one place.
Product Group is part of Product Master, Product Family is assigned per Product Group.
Each Product group belongs to 1 Product Family. (Product Family Mapping table)
Based on cumulative yearly revenue on the whole Product Family the customer has assigned Discount Level in Discount Level Definition Table.
Based on Product Group and Discount Level achieved by the Customer the sales agent has a "recommended discount" and a "maximum allowed discount" (Target Discount % and Max Discount %)
Details
Product Discount Data Management Custom Form allows users to perform these tasks:
Change Data → select a table and change values within the table without adding new rows.
Add new Product Group → add a new group, assign it to a product family, and assign all the required discounts for different levels. It is important that the discount for each additional level is greater than or equal to the discount for the previous level; otherwise, the validation process will fail.
Add a product family → reassign product groups to reflect a new product family.
Add new discount level to existing product family → create new discount levels for an existing product family. The levels must be continuous, starting from level 1 at 0 Min Revenue. Each additional level must have a minimum revenue greater than or equal to the previous level. Users can assign new discounts for these new levels, ensuring that the discount for each additional level is greater than or equal to the discount for the previous level; otherwise, the validation will fail.
Learning Outcomes
At the end of the Lab, you should be able to:
Create Standalone Custom Form, Custom Form Type
Utilize Input Matrix as Custom Form input
Understand Custom Forms Workflow
Provided resources
Logics:
View file | ||
---|---|---|
|
Company Parameters:
View file | ||
---|---|---|
|
Acceptance Criteria
User can access a standalone Custom Form within the Analytics section to complete tasks listed in the Details section.
...
User can select one of three options: Modify data, Create new Product Group, or Create new Product Family.
...
A separate form will be displayed for each option
Tables with calculation results are available in the Calculations section, located on the right panel.
...
It is recommended to highlight any changes made to tables for better visibility and clarity.
...
After the user submits the form, changes should be saved in the corresponding company parameter tables. If a workflow has been added to the form, the changes should be saved after approval.
Sample solution
Expand | ||
---|---|---|
| ||
You will get a confirmation message in green that the form has been added successfully.
Note that you may have to check what values are assigned to each level. To avoid missing out any fields, the system displays warning icons which disappear once the field has been filled out. You can add as many discount levels as you need. Check out our documentation to learn more about discounts.
If you go to Company Parameters by clicking the third icon from the left in the top right corner, under Categories> Custom Form, you can check your newly created form. |
Step-by-step solution
Develop the logic and test in Studio
...
AbortOnInputGenerationExecution
Code Block | ||
---|---|---|
| ||
if (api.isInputGenerationExecution()) { api.abortCalculation() } |
BuildStep
Code Block | ||
---|---|---|
| ||
workflow.addWatcherStep("Sales Manager") .withUserWatchers("admin") .withReasons("Sales manager needs to approve this form") workflow.addApprovalStep("Sales Manager") .withPostStepLogic("customform_WorkflowPostStep") .withApprovers("admin") .withReasons("Sales manager needs to approve this form") |
...
UpdateData
Code Block | ||
---|---|---|
| ||
if (workflowHistory.steps.findAll { it.approvalStep }.every { it.approved } || workflowHistory.activeStep?.isEmpty()) { //TODO: The logic that will be performed after the user approved all the steps. } |
...
Proceed with deploying all logic created logics to your partition.
Access Administration → Custom Form Types from your partition. Create a new form type by clicking on the [+ New Form Type] button located at the top-right corner of the screen. Uncheck Embedded option and fill in the form:
If you miss [+ New Form Type] button, add Custom Forms rights to your user (admin) using User Admin.
...
Add the following code in the Configuration section.
...
In this configuration, the first tab is named "details" and uses the "dashboard" icon. It has a name that can be translated using the "Management options" key. The second tab is named "workflow" and uses the "process" icon. It has a name that can be translated using the "Workflow" key. The third tab is named "actions" and uses the "file-check-alt" icon. It has a name that can be translated using the "Todo list" key. The step label itself is also translatable using the "Product Discount Data Management" key.
Pricefx Studio - Create Custom Form Type
Using the Create Custom Form Type feature in Pricefx Studio simplifies the process of creating a Custom Form Type as compared to manual creation through the user interface. To create a custom form type in Pricefx, please follow these steps:
...
Navigate to the sCFO_ProductDiscountDataMgmn logic and open the Configurator.groovy file. Once you have accessed the file, add the following code snippet to it.
Code Block | ||
---|---|---|
| ||
if (customFormProcessor.isPrePhase()) { //1. Create two variables named 'configuratorName' and 'cfoFormIdKey'. Assign values to them from the Constconfig file. //String configuratorName = //String cfoFormIdKey = //2. Assign value to currentCfoForm. Use api.currentItem() //def currentCfoForm = //3. Get id from current Item. Remember that current item can be null. //Long cfoFormId = //4. Get inputs from currentCfoFrom. //5. Find input with a name that matches configuratorName //6. Take value //7. If the above operation returns null, return an empty map [:]. You can use elvis operator '?:' //If you want to prevent NullPointerException, it is recommended to use the safe navigation operator '?'. This will ensure that your code doesn't throw an exception if a null value is encountered. //Map configuratorValueBackup = //8. Add current form id to the configuratorValueBackup. Use cfoFormIdKey as a key and cfoFormId as value. //configuratorValueBackup.put() //9. update the input "ROOT" with a map that provides the name, label, url, type and value. customFormProcessor.addOrUpdateInput("ROOT", [name : configuratorName, label: configuratorName, url : configuratorName, type : InputType.INLINECONFIGURATOR, value: configuratorValueBackup] ) } |
Take a look at line 4 and the value of configuratorName, which will be created in the next step.
DEBUGINGDEBUGGING
Make sure to set the proper CustomForm for your logic in the Inputs tab. Run and test the logic afterwards.
...
In this step, we will create the configuratorEntry object and add a new hidden input with our custom form id to the configuratorEntry before returning it.
Code Block | ||
---|---|---|
| ||
import net.pricefx.server.dto.calculation.ConfiguratorEntry // Create a key for the CFO form ID from specified library //String cfoFormIdKey = // Create a new ConfiguratorEntry using the API //ConfiguratorEntry configuratorEntry = // Create a HiddenEntry InputBuilder with the CFO form ID key and build a context parameter for it //def param = // Add the newly created parameter to the ConfiguratorEntry. Use createParameter method. // Return the modified ConfiguratorEntry |
...
In this step, we will add a header and a drop-down list with options for selecting individual forms to the configurator.
Code Block | ||
---|---|---|
| ||
// Initialize a constant for main paragraph message //String PARAGRAPH_MESSAGE_MAIN = // Get value of the first input from the ConfiguratorEntry, only if it exists Long formId = // Get the product discount configurator utility script from the product discount library Script productDiscountConfigurator = // Instantiate the main entry of the product discount configurator. // Use getMainConfiguratorEntry method with formId as a parameter ConfiguratorEntry mainConfiguratorEntry = // Set the paragraph header for the main configurator entry. Use the constant initialized earlier // Return the main configurator entry |
...
In this step, we retrieve the option selected by the user and pass it as a parameter to the method that changes the form depending on the selected option.
Code Block | ||
---|---|---|
| ||
import net.pricefx.server.dto.calculation.ConfiguratorEntry // Get value of the first input from the OtionInput.groovy, only if it exists String selectedType = // Use configuratorSwitch method. Pass selectedType as a parameter. /** * This method is used to select and configure different types of ConfiguratorEntries. * It also loads the correct messages for each type. * * @param selectedType The type of ConfiguratorEntry to be used. This could be 'CHANGE_DATA', 'NEW_FAMILY', or 'NEW_GROUP'. * @return A ConfiguratorEntry instance configured based on the selectedType. * If the getterMethod or message for the selectedType do not exist, the method will return null. */ ConfiguratorEntry configuratorSwitch(String selectedType) { Script CONFIG_UTILS = libs.sCFO_ProductDiscountLib.CfoConfiguratorUtils Script CONST_CONFIG = libs.sCFO_ProductDiscountLib.ConstConfig def getterMap = [ (CONST_CONFIG.CHANGE_DATA) : CONFIG_UTILS.&getChangeDataConfiguratorEntry, (CONST_CONFIG.NEW_FAMILY) : CONFIG_UTILS.&getAddFamilyConfiguratorEntry, (CONST_CONFIG.NEW_GROUP) : CONFIG_UTILS.&getAddGroupConfiguratorEntry, ] def messageMap = [ (CONST_CONFIG.CHANGE_DATA) : CONST_CONFIG.CFO_CONFIGURATOR_CONFIG.PARAGRAPH_MESSAGE_CHANGE, (CONST_CONFIG.NEW_FAMILY) : CONST_CONFIG.CFO_CONFIGURATOR_CONFIG.PARAGRAPH_MESSAGE_ADD_FAMILY, (CONST_CONFIG.NEW_GROUP) : CONST_CONFIG.CFO_CONFIGURATOR_CONFIG.PARAGRAPH_MESSAGE_ADD_GROUP, ] def getterMethod = getterMap[selectedType] def message = messageMap[selectedType] if (getterMethod && message) { return configureEntries(getterMethod, message) } } /** * This method applies configuration to entries. * * @param getterMethod Method reference for getting configurator entry. * @param message The message to be set as paragraph header in configurator entry. * @return ConfiguratorEntry The modified configurator entry with new paragraph header. */ ConfiguratorEntry configureEntries(def getterMethod, String message) { ConfiguratorEntry configuratorEntry = getterMethod.call() configuratorEntry.setMessage(message) return configuratorEntry } |
...
Open logic.json in sCFO_ProductDiscountHeader_Configurator.
Open Studio Editor.
Click on the Inputs tab.
Set the Context to CONFIGURATOR.
Test LogicGenerate Inputs.
Click on the Results tab and check output.
Your output should resemble the example given below.
...
For Discount Level Definition option:
...
...
For Product Family Mapping option:
...
...
For Discount option:
...
...
All fields are required.
...
Add new Product Group option
...
“New Product Goup“ is an input type of String
“Assign Product Family” is a drop-down list with unique values of Product Familty colum in Discount Level Definition company parameter table.
The table for adding and deleting discount records should have identical columns as the Discount company parameters table, and provide a user-friendly way to add records.
“Product Group” column shoud have a drop-down list with newly added “New Product Group”. ColumnType: Option
“Discount Level” coulumn should have a drop-down list with list of numbers from 1 to 6. columnType: Option
“Traget Discount” and “Max Discount” are coulmns with columnType: Numeric
All fields are required.
...
...
Add new Product Family option
...
“New Product Family“ is an input type of String
“Assign new Product Family to an already existing Product Group.” is a checkbox. Default: unchecked.
“Assign to:” is a drop-down list. This is a list of unique values from “Product Family” column in Discount Level Definition company parameters table. This filed will be visible if the “Assign new Product Family to an already existing Product Group” value is set to true (with the checkbox checked).
The table for adding and deleting new discount levels records should have identical columns as the Discount Level Definition company parameters table, and provide a user-friendly way to add records.
“Product Family” column shoud have a drop-down list with newly added “New Product Family”. ColumnType: Option
“Discount Level” and “Min Revenue” are coulmns with columnType: Numeric
All fields are required.
...
Solution
Go to ChangeDataInputs.groovy and look at the configuratorSwitch method. Implement methods for each option chosen by the user to create one of three forms. Each method returns the ConfiguratorEntry object.
Code Block | ||
---|---|---|
| ||
/* Fragment of configuratorSwitch method */ def getterMap = [ (CONST_CONFIG.CHANGE_DATA) : CONFIG_UTILS.&getChangeDataConfiguratorEntry, (CONST_CONFIG.NEW_FAMILY) : CONFIG_UTILS.&getAddFamilyConfiguratorEntry, (CONST_CONFIG.NEW_GROUP) : CONFIG_UTILS.&getAddGroupConfiguratorEntry, ] |
getChangeDataConfiguratorEntry()
Code Block | ||
---|---|---|
| ||
ConfiguratorEntry getChangeDataConfiguratorEntry() { ConfiguratorEntry changeDataSection = api.createConfiguratorEntry() //TODO: create changeDataSection //1. Get config map from libraray (CFO_CONFIGURATOR_CONFIG) //2. Create option input - name: "ppTableInput", label: "Select table", required: true. // Get the value from CFO_CONFIGURATOR_CONFIG by OPTIONS.TABLE_OPTIONS key and // pass it as options parameter. //3. Get value from ppTableInput //4. Display a specific group of fields based on the option that is chosen. // Check required inputs in follow sections: // - For Discount Level Definition option // - For Product Family Mapping option // - For Discount option return changeDataSection } |
...
getAddFamilyConfiguratorEntry()
Code Block | ||
---|---|---|
| ||
ConfiguratorEntry getAddFamilyConfiguratorEntry() { ConfiguratorEntry productFamilySection = api.createConfiguratorEntry() //TODO: create productFamilySection //1. Create two inputs: // a) InputType.STRINGUSERENTRY, name: "productFamilyInput", label: "New Product Family", required: true // b) InputType.BOOLEAN, name: "assignToGroup", label: "Assign new Product Family to an already existing Product Group." //2. Get input value from "assignToGroup". If value is true: // a) Find unique family names from the ProductFamilyMapping company parameters table. // b) Create option input - name: "assignProductGroup", label: "Assign to", pass values from step a) //3. Create a table. Use result from step 1a as a option for product family option. return productFamilySection } |
...
Assign to: list of unique names from
ProductFamilyMapping
lookup tableNew Discount Levels: user can add and delete rows.
...
getAddGroupConfiguratorEntry()
Code Block | ||
---|---|---|
| ||
ConfiguratorEntry getAddGroupConfiguratorEntry() { ConfiguratorEntry productGroupSection = api.createConfiguratorEntry() //TODO: create productGroupSection //1. Find unique family names from the ProductFamilyMapping company parameters table. // You can use the API function "findLookupTableValues". //2. Create two inputs: // a) InputType.STRINGUSERENTRY, name: "productGroupInput", label: "New Product Group", required: true // b) InputType.Option, name: "Assign Product Family", label: "assignProductFamily", required: true // Pass the values from first step as a setValuesOptions() parameter //3. Get input value from productGroupInput //4. Create a table. Use result from step 3 as a option for product group option. return productGroupSection } |
...
Assign Product Family: list of unique values from
ProductFamilyMapping
lookup tableNew Discount: user can add and delete rows
...
Calculations
The results will be displayed as tables in the right panel. Only tables with changes will be shown as copies of parameter tables with updated values.
...
Open the Calculation.groovy file, which is located in the sCFO_ProductDiscountDataMgmt logic. Once it's open, please add the following code to the file.
Code Block | ||
---|---|---|
| ||
if (customFormProcessor.isPostPhase()) { // choosenOption is a value from managementOptionsInput if (chosenOption == "Add new Product Group") { //TODO: Part-1 } else if (chosenOption == "Add new Product Family") { //TODO: Part-2 } else if (chosenOption == "Change data") { //TODO: Part-3 if (ppTableInput == "Product Family Mapping") { //TODO: Part-4 if (chosenTable == "Product Family") { //TODO: Part-5 } else if (chosenTable == "Product Group") { //TODO: Part-6 } //TODO: Part-7 } else if (ppTableInput == "Discount Level Definition") { //TODO: Part-8 } else if (ppTableInput == "Discount") { //TODO: Part-9 } } } |
...
Task | Sample Code | |||||
---|---|---|---|---|---|---|
Create a table |
| |||||
Get data from company parameter table |
| |||||
How to edit cell style in table |
| |||||
How to add new table to the customFormProcessor. |
|
...
Saving changes to the tables
...
We need to ensure that changes in the target tables are displayed accurately. Once the user approves the changes, they should be saved. The customform_WorkflowPosStep logic is responsible for this process.
We need to revisit the logic that controls our Workflow. Our logic consists of two steps. Take a look at BuildStep.groovy
Code Block | ||
---|---|---|
| ||
workflow.addWatcherStep("Sales Manager") .withUserWatchers("admin") .withReasons("Sales manager needs to approve this form") workflow.addApprovalStep("Sales Manager") .withPostStepLogic("customform_WorkflowPostStep") .withApprovers("admin") .withReasons("Sales manager needs to approve this form") |
...
This task can be approached in various ways. You can either attempt to preserve the data or use the provided solution below.
Code Block | ||
---|---|---|
| ||
if (workflowHistory.steps.findAll { it.approvalStep }.every { it.approved } || workflowHistory.activeStep?.isEmpty()) { //part-1 if (optionInput == "Change data") { if (changeGroupOrFamily == "Product Group") { //part-2 } else if (changeGroupOrFamily == "Product Family") { //part-3 } else if (ppTableInput == "Discount") { //part-4 } else if (ppTableInput == "Discount Level Definition") { //part-5 } } else { //part-6 if (optionInput == "Add new Product Family") { //part-7 } else if (optionInput == "Add new Product Group") { //part-8 } } } |
...
Task | Code samples | |||||
---|---|---|---|---|---|---|
Get user inputs from current item assign it to |
| |||||
Get individual field values from user |
| |||||
Get |
| |||||
Create filters:
|
| |||||
Update |
| |||||
Use |
| |||||
Get |
| |||||
If output is null get an empty list |
| |||||
Filter the rows in their respective tables based on the values of Map. |
|
Resources for Further Learning
References
Custom Forms Configuration How-To(s)
...
Documentation
Groovy API
Other
...
Info |
---|
NOTE: If you have any inquiries regarding the content in this learning path, you can utilize the following online Pricefx forums: AskPricefxcommunity or Pricefx GenAI chatbot. |