Package net.pricefx.server.dto.calculation

Class ConfiguratorEntry

Object
AbstractPortletDto
ConfiguratorEntry
All Implemented Interfaces:
Serializable, Portlet, ComplexCalculationResult
public class ConfiguratorEntry extends AbstractPortletDto implements ComplexCalculationResult
Holds a section of a Configurator form: a set of inputs that share a purpose, and an optional message shown above them.

Create an instance with api.createConfiguratorEntry(), add inputs built with api.inputBuilderFactory(), and return it from a logic element. To return several sections from one element, wrap them in a ConfiguratorEntryArray.

Configurators are a legacy input mechanism. Since version 17.0, use Forms 2.0 for new implementations instead.

Example: 


 def entry = api.createConfiguratorEntry()

 api.inputBuilderFactory()
         .createOptionEntry("Meat")
         .setOptions(["Beef", "Lamb", "Pork"])
         .addToConfiguratorEntry(entry, { "Beef" })

 return entry
See Also:

  • Constructor Details

    • ConfiguratorEntry

      public ConfiguratorEntry()
      Not intended for public use. This constructor does not set the logic context, so the inputs added with createParameter() do not get their values from the previous round trip. Use api.createConfiguratorEntry() instead.
      See Also:

  • Method Details

    • getInputs

      public List<ContextParameter> getInputs()
      Gets the list of context parameters.

      NOTE:

      All available inputs are returned, also hidden internal inputs which are generated during the default, first-run, previous or value-changed-by-logic value tracking
      Returns:
      the list of context parameters, or null if no context parameters were previously added
      See Also:

    • getFirstInput

      public ContextParameter getFirstInput()
      Gets the first context parameter. Example: 
      
 api.logInfo("first input value",configuratorEntry.getFirstInput().getValue())
      Returns:
      the first context parameter, or null if no context parameter was previously added

    • setInputs

      public void setInputs(List<ContextParameter> inputs)
      Sets the list of context parameters.
      Parameters:
      inputs - a list of context parameters. Can be null.
      See Also:

    • getMessage

      public String getMessage()
      Gets the message.
      Returns:
      the message, or null if it was not set

    • setMessage

      public void setMessage(String message)
      Sets a message that will appear on top of the configuration entry. You may use HTML markup. Example: 
      
 entry.setMessage("<BR /><Center><B><Font Size='3'>Competitor Price Information</Font></B></Center></BR/ >")

      HTML sanitization (since 17.0): the message is sanitized before it is rendered, so only a restricted subset of HTML is displayed and anything else is sanitized. In particular, raw <a> hyperlinks pointing to external URLs are displayed as HTML code (shown verbatim as text) instead of clickable links unless the URL targets pricefx.com/pricefx.eu or starts with # (a context link). Enabling the disableHtmlInjection feature flag strips all HTML tags. See the Allowed HTML Tags and Attributes page in the Pricefx Knowledge Base for the full list of supported tags, attributes and URL schemes.

      Parameters:
      message - the text to display as message
      See Also:

    • setHiddenActions

      public void setHiddenActions(InputButtonAction... hiddenActions)
      Hides all or specified buttons from the pop-up Configurator.

      Example – hides all buttons: 

      
 import net.pricefx.common.api.InputButtonAction

 def ce = api.createConfiguratorEntry()
 ce.setHiddenActions(InputButtonAction.ALL)
 return ce
      Parameters:
      hiddenActions - Specify the button you want to hide. See InputButtonAction for possible values.
      Since:
      6.1.0 - Vesper
      See Also:

    • getHiddenActions

      public List<InputButtonAction> getHiddenActions()
      Retrieves a list of hidden pop-up Configurator buttons.
      Returns:
      the list of hidden InputButtonAction
      Since:
      6.1.0 - Vesper
      See Also:

    • createParameter

      public ContextParameter createParameter(InputType type, String name)
      Creates a parameter and adds it to the list of inputs. The parameter will be created without target date. If the FormulaEngineContext is set and contains the parameter with the name, it will be used to set the value of the context parameter by retrieving a parameter from the context with the specified name.

      The Input Builder approach is recommended instead: build the input with api.inputBuilderFactory() and add it with createParameter(ContextParameter). Example: 

      
 def ce = api.createConfiguratorEntry()
 ContextParameter param = ce.createParameter(InputType.OPTION, "Customer_inline_01")
      Parameters:
      type - Input type of the parameter.
      name - Name of the parameter.
      Returns:
      the context parameter

    • createParameter

      public ContextParameter createParameter(InputType type, String name, Date targetDate)
      Creates a parameter and adds it to the list of inputs. If the FormulaEngineContext is set and contains the parameter with the name, it will be used to set the value of the context parameter by retrieving a parameter from the context with the specified name.

      The Input Builder approach is recommended instead: build the input with api.inputBuilderFactory() and add it with createParameter(ContextParameter). Example: 

      
 def ce = api.createConfiguratorEntry()
 ContextParameter param = ce.createParameter(InputType.OPTION, "Customer_inline_01", api.targetDate())
      Parameters:
      type - Input type of the parameter.
      name - Name of the parameter.
      targetDate - the target date of the parameter. Only LOOKUP parameters use it.
      Returns:
      the context parameter
      See Also:

    • createParameter

      public ConfiguratorEntry createParameter(@NotNull ContextParameter input, Closure<?> defaultValue)
      Creates a parameter and adds it to the list of inputs. If the FormulaEngineContext is set and contains the parameter with the name, it will be used to set the value of the context parameter by retrieving a parameter from the context with the specified name. If the FormulaEngineContext is not set, or no parameter that matches the name of the input is found in the context, then defaultValue from the closure will be used. Example: 
      
 ContextParameter contextParameter = api.inputBuilderFactory()
                                        ... (other methods from the builder)
                                       .buildContextParameter()
 ConfiguratorEntry configuratorEntry = api.createConfiguratorEntry().createParameter(contextParameter, { "hop" })
      Parameters:
      input - the input element to add
      defaultValue - the value to be used if nothing is selected in the input
      Returns:
      this ConfiguratorEntry object instance

    • removeInputWithTrackedContent

      public ConfiguratorEntry removeInputWithTrackedContent(String name)
      Removes an input from this configurator entry, together with the hidden inputs that track its values. The input must exist and have value tracking turned on.

      When you remove a tracked input from the inputs list directly, its hidden tracking inputs stay in the entry. Use this method to remove them as well.

      Example: 

      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setDefaultValueTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry
 // another element removing input 'test'
 def configurator = out.First

 configurator.removeInputWithTrackedContent('test')
      Parameters:
      name - name of the input
      Returns:
      this ConfiguratorEntry object instance without the removed input
      Since:
      14.0 - Caribou Lou

    • isDefaultValueTracked

      public boolean isDefaultValueTracked(String name)
      Checks if the default value tracking for the specified ContextParameter is enabled. Example: 
      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setDefaultValueTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // another element - returns the default value of 'test' ContextParameter (if available), otherwise returns "not supported"
 return out.First.isDefaultValueTracked('test')
          ? out.First.getDefaultValue('test')
          : 'not supported'
      Parameters:
      name - ContextParameter's name available around the current ConfiguratorEntry
      Returns:
      true if the default value of the specified ContextParameter is tracked, otherwise false
      Since:
      14.0 - Caribou Lou
      See Also:

    • getDefaultValue

      public Object getDefaultValue(String name)
      Retrieves the default value of a specific tracked input (i.e., created using the InputBuilderFactory and tracked for default value with AbstractInputBuilder.setDefaultValueTracking(boolean) enabled.

      Note: Attempting to retrieve the default value of an input that is not being tracked will result in a DefaultValueNotTrackedException. To avoid this exception, verify the tracking status of the input by calling isDefaultValueTracked(String) before invoking this method.

      Example: 

      
  // First element (creates a tracked "test" input in configurator entry with value set to 'Actual' in the input generation mode)
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setOptions(['Forecast', 'Actual'])
          .setValue('Actual')
          .setDefaultValueTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // Second element (abort calculation if in input generation mode)
 if (api.isInputGenerationExecution()) api.abortCalculation()

 // Third element (retrieve and use the default value of 'test' input in another configurator as TextUserEntry)
 def configurator = out.First
 def firstDefault = configurator.isDefaultValueTracked('test')
                          ? configurator.getDefaultValue('test')
                          : 'not supported'

 def configuratorEntry = api.createConfiguratorEntry()
 configuratorEntry.inputs = [
     api.inputBuilderFactory()
         .createTextUserEntry('Test input default value')
         .setValue(firstDefault)
         .buildContextParameter()]

 return configuratorEntry
      Parameters:
      name - the name of the tracked input you want to retrieve the default value for
      Returns:
      default value of the tracked input
      Throws:
      ConfiguratorEntryException.DefaultValueNotTrackedException - if the specified Context Parameter's default value is not tracked.
      Since:
      14.0 - Caribou Lou
      See Also:

    • isPreviousValueTracked

      public boolean isPreviousValueTracked(String name)
      Checks if the previous value of a specified ContextParameter is being tracked.

      Example: 

      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setPreviousValueTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // another element - returns the previous value of 'test' ContextParameter (if available), otherwise returns "not supported"
 return out.First.isPreviousValueTracked('test')
          ? out.First.getPreviousValue('test')
          : 'not supported'
      Parameters:
      name - The name of the ContextParameter within the ConfiguratorEntry you want check for previous value tracking.
      Returns:
      true if the previous value of the specified ContextParameter is being tracked, otherwise false.
      Since:
      14.0 - Caribou Lou
      See Also:

    • getPreviousValue

      public Object getPreviousValue(String name)
      Retrieves the previous value of a specific tracked input (i.e., created using the InputBuilderFactory and tracked for previous value with AbstractInputBuilder.setPreviousValueTracking(boolean) enabled.

      Note: Attempting to retrieve the previous value of an input that is not being tracked will result in a PreviousValueNotTrackedException. To avoid this exception, verify the tracking status of the input by calling isPreviousValueTracked(String) before invoking this method.

      Example: 

      
  // First element (creates test input in configurator entry with value set to 'Actual' in the inputs generation mode)
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setOptions(['Forecast', 'Actual'])
          .setValue('Actual')
          .setPreviousValueTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // Second element (abort in the input generation mode)
 if (api.isInputGenerationExecution()) api.abortCalculation()

 // Third element (get previous value of the test-input and return it in the text-user-entry)
 def firstPrevious = out.First.getPreviousValue('test')

 def configuratorEntry = api.createConfiguratorEntry()
 configuratorEntry.inputs = [
     api.inputBuilderFactory()
         .createTextUserEntry('Test input previous value')
         .setValue(firstPrevious)
         .buildContextParameter()]

 return configuratorEntry
      Parameters:
      name - the name of the tracked input you want to retrieve the previous value for
      Returns:
      previous value of the tracked input
      Throws:
      ConfiguratorEntryException.PreviousValueNotTrackedException - If the specified Context Parameter's previous value is not being tracked.
      Since:
      14.0 - Caribou Lou
      See Also:

    • isValueChangeByLogicTracked

      public boolean isValueChangeByLogicTracked(String name)
      Checks if a specified ContextParameter is tracked for the value change by the Groovy logic

      Example: 

      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setValueChangeTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // another element - returns the  value of 'test' ContextParameter (if available) changed by the logic, otherwise returns "not supported"
 return out.First.isValueChangeByLogicTracked('test')
          ? out.First.getLastValueChangedByLogic('test')
          : 'not supported'
      Parameters:
      name - ContextParameter's name available around the current ConfiguratorEntry
      Returns:
      true if the value changes by the logic of the specified ContextParameter are being tracked, otherwise false.
      Since:
      14.0 - Caribou Lou
      See Also:

    • isFirstRunTracked

      public boolean isFirstRunTracked(String name)
      Checks if the first run value tracking for the specified ContextParameter is enabled. Example: 
      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setFirstRunTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // another element - returns true if the run is first, false if not, otherwise returns 'not supported'
 return out.First.isFirstRunTracked('test')
          ? out.First.isFirstRun('test')
          : 'not supported'
      Parameters:
      name - ContextParameter's name available around the current ConfiguratorEntry
      Returns:
      true if the first run of the specified ContextParameter is tracked, otherwise false
      Since:
      14.0 - Caribou Lou
      See Also:

    • isFirstRun

      public boolean isFirstRun(String name)
      Retrieves the first run flag for a specific tracked input (i.e., created using the InputBuilderFactory and tracked for first run with AbstractInputBuilder.setFirstRunTracking(boolean) enabled.

      Note: Attempting to retrieve the first run flag value of an input that is not being tracked will result in a FirstRunNotTrackedException. To avoid this exception, verify the tracking status of the input by calling isFirstRunTracked(String) before invoking this method.

      Example: 

      
  // First element (creates test input in configurator entry with value set to 'Actual' in the inputs generation mode)
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .setOptions(['Forecast', 'Actual'])
          .setValue('Actual')
          .setFirstRunTracking(true)
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // Second element (abort in the input generation mode)
 if (api.isInputGenerationExecution()) api.abortCalculation()

 // Third element (get first run flag value of the test-input and return it in the text-user-entry)
 def isFirstRun = out.First.isFirstRun('test')

 def configuratorEntry = api.createConfiguratorEntry()
 configuratorEntry.inputs = [
     api.inputBuilderFactory()
         .createTextUserEntry('Test input first run flag')
         .setValue(isFirstRun)
         .buildContextParameter()]

 return configuratorEntry
      Parameters:
      name - the name of the tracked input you want to retrieve the first run information
      Returns:
      true if the input was initiated (run first time), false if it has run more than once
      Throws:
      ConfiguratorEntryException.FirstRunNotTrackedException - If the specified Context Parameter's first run is not being tracked.
      Since:
      14.0 - Caribou Lou
      See Also:

    • setTrackedValue

      public ContextParameter setTrackedValue(String name, Object value)
      Sets the ContextParameter value, enriched by the groovy logic value tracking feature.

      Value changed by this method will be stored in ContextParameter.getParameterConfig() together with timestamp (only last value change is tracked and will be kept).

      The change is stored as a Map with LocalDateTime as a key. Read it with getLastValueChangedByLogic(String).

      Example: 

      
 // "SomeType" element in Groovy logic
 def configuratorEntry = api.createConfiguratorEntry()
 api.inputBuilderFactory()
          .createOptionEntry('FirstOrSecond')
          .setOptions(['First', 'Second'])
          .setValueChangeTracking(true)
          .addToConfiguratorEntry(configuratorEntry)
 return configuratorEntry

 // "OtherElement" in Groovy logic
 def configuratorEntry = out.SomeType
 if (conditionIsMet) {
      configuratorEntry.setTrackedValue('FirstOrSecond', 'valueChangedByTheLogic')
 }
      Parameters:
      name - The name of the ContextParameter to update within the ConfiguratorEntry.
      value - The updated value of the ContextParameter, reflecting changes made via Groovy logic.
      Returns:
      The updated ContextParameter with its value changed and tracked.
      Throws:
      ConfiguratorEntryException.ChangeByLogicNotTrackedException - If the specified input does not exist within the ConfiguratorEntry or if value change tracking is not enabled.
      Since:
      14.0 - Caribou Lou
      See Also:

    • getLastValueChangedByLogic

      public Object getLastValueChangedByLogic(String name)
      Retrieves the last value of a specified ContextParameter that was changed by Groovy logic, together with the timestamp of when the change occurred.
      If tracking is not enabled or the specified input does not exist within the given ConfiguratorEntry, a ChangeByLogicNotTrackedException will be thrown.

      Example: 

      
 // SomeType element in Groovy logic
 def configuratorEntry = api.createConfiguratorEntry()
 api.inputBuilderFactory()
          .createOptionEntry('FirstOrSecond')
          .setOptions(['First', 'Second'])
          .setValueChangeTracking(true)
          .addToConfiguratorEntry(configuratorEntry)
 return configuratorEntry

 // OtherElement in Groovy logic
 def configuratorEntry = out.SomeType
 if (conditionIsMet) {
      configuratorEntry.setTrackedValue('FirstOrSecond', 'valueChangedByTheLogic')
 }

 // OtherElement in Groovy logic returning timestamp and value changed by the groovy logic
 def configuratorEntry = out.SomeType
 return configuratorEntry.getLastValueChangedByLogic('FirstOrSecond')
      Parameters:
      name - The name of the ContextParameter within the ConfiguratorEntry you want to retrieve the last changed value and timestamp for.
      Returns:
      The value of the ContextParameter which was changed by the logic (with timestamp).
      Throws:
      ConfiguratorEntryException.ChangeByLogicNotTrackedException - if input was not found for particular ConfiguratorEntry or value tracking is not turned on.
      Since:
      14.0 - Caribou Lou
      See Also:

    • createParameter

      public ConfiguratorEntry createParameter(ContextParameter input)
      Creates a parameter and adds it to the list of inputs. If the FormulaEngineContext is set and contains the parameter with the name, it will be used to set the value of the context parameter by retrieving a parameter from the context with the specified name. Example: 
      
 ContextParameter contextParameter = api.inputBuilderFactory()
                                        ... (other methods from the builder)
                                       .buildContextParameter()
 ConfiguratorEntry configuratorEntry = api.createConfiguratorEntry().createParameter(contextParameter)
      Parameters:
      input - the input element to add
      Returns:
      this ConfiguratorEntry object instance

    • addParameter

      @Deprecated public ConfiguratorEntry addParameter(ContextParameter input)
      Deprecated.
      Use createParameter(ContextParameter) instead.
      Adds a parameter to the list of parameters of this object without setting its value from the formula context. Example: 
      
 ContextParameter contextParameter = api.inputBuilderFactory()
                                        ... (other methods from the builder)
                                       .buildContextParameter()
 ConfiguratorEntry configuratorEntry = api.createConfiguratorEntry().addParameter(contextParameter)
      Parameters:
      input - The ContextParameter to add (f.e an input)
      Returns:
      this ConfiguratorEntry object instance

    • getAdditionalConfig

      public Map<String,String> getAdditionalConfig()
      Gets the Map of additional configurations
      Returns:
      the additional config, or null, if nothing was set
      Since:
      5.0 - Collins

    • setAdditionalConfig

      public void setAdditionalConfig(Map<String,String> additionalConfig)
      Sets all the additional configurations at once
      Parameters:
      additionalConfig - the additional configuration, as pairs of key and value. For the keys, see addAdditionalConfigValue(String, String).
      Since:
      5.0 - Collins
      See Also:

    • addAdditionalConfigValue

      public void addAdditionalConfigValue(String name, String value)
      Sets an additional configuration pair.

      Example: 

      
 def invoicePriceBoundaries = api.createConfiguratorEntry()
 invoicePriceBoundaries.addAdditionalConfigValue("sectionLabel", "Business Rules")
 invoicePriceBoundaries.addAdditionalConfigValue("recalculateParentEntityOnConfirm", "true")
      Parameters:
      name - the name of the configuration key. Possible key names:
      • sectionLabel (String): a heading shown above the message and the inputs of this entry
      • recalculateParentEntityOnConfirm (Boolean): "true" recalculates the document, such as a Quote, an Agreement/Promotion or a Rebate Agreement, when the user confirms the changes in the Configurator. Default: false
      value - the value of the configuration key
      Since:
      5.0 - Collins

    • getResultType

      public String getResultType()
      Returns the result type of the configurator entry.
      Specified by:
      getResultType in interface ComplexCalculationResult
      Returns:
      Always "CONFIGURATORENTRY".

    • setContext

      public void setContext(FormulaEngineContext ctx)
      Not intended for public use. api.createConfiguratorEntry() sets the logic context, which the createParameter() methods use to read the values of the inputs.

    • getInputByName

      public ContextParameter getInputByName(String name)
      Get ContextParameter by provided name

      Example: 

      
 // Element 'First' with logic
  def configuratorEntry = api.createConfiguratorEntry()

  api.inputBuilderFactory()
          .createOptionEntry('test')
          .addToConfiguratorEntry(configuratorEntry)

  return configuratorEntry

 // another element - returns the test input
 return out.First.getInputByName('test')
      Parameters:
      name - ContextParameter's name available around the current ConfiguratorEntry
      Returns:
      ContextParameter if found or null if not.
      Since:
      14.0 - Caribou Lou
      See Also: