Package net.pricefx.common.apibuilder.clicoll

Class CalculableLineItemCollectionBuilder<T extends CalculableLineItemCollectionBuilder>

Object
ObjectIdentity
AbstractBuilder
CalculableLineItemCollectionBuilder<T>
Direct Known Subclasses:
BasicCompensationBuilder, BasicRebateAgreementBuilder, ContractBuilder, CustomFormCollectionBuilder, QuoteBuilder
public abstract class CalculableLineItemCollectionBuilder<T extends CalculableLineItemCollectionBuilder> extends AbstractBuilder
This is the shared builder class for Quotes, RebateAgreements and Contracts.
Some important notes on the sequence in which changes to the document structure are processed:

Any modifying action (adding lines, inputs etc. or a structure object etc.) IS NOT executed as per sequence of the Groovy logic! The Groovy logic is more like a routine to collect all necessary changes. These changes are not executed immediately. They are collected (per execution phase) and then executed in this order:
  • Add line items
  • Delete line items (PRE phase only!)
  • Move line items (PRE phase only!)
  • Rename folders
  • Add inputs (to: lines, header/a ROOT folder, and folders)
  • Add outputs (to: lines, header/a ROOT folder, and folders)
  • Update header fields
  • Process Render Info

  • Field Details

  • Constructor Details

    • CalculableLineItemCollectionBuilder

      public CalculableLineItemCollectionBuilder(String instanceId, String classId, IdGenerator idGenerator, Invocations<MethodInvocation> invocations, HeaderPhase phase)

  • Method Details

    • isPrePhase

      public boolean isPrePhase()
      Determines the current calculation phase of the header logic execution.
      Returns:
      true if the current context is "pre"/before line items calculation

    • isPostPhase

      public boolean isPostPhase()
      Determines the current calculation phase of the header logic execution.
      Returns:
      true if the current context is "post"/after line items calculation

    • addOrUpdateOutput

      public T addOrUpdateOutput(Map<String,Object> calculationResult)
      Adds or updates a result value (an output value) on the ROOT level.

      For map example/details, see addOrUpdateOutput(String, Map)

      Parameters:
      calculationResult - A map describing a calculation result
      Returns:
      itself (for flow pattern)

    • addOrUpdateOutput

      public T addOrUpdateOutput(String lineId, Map<String,Object> calculationResult)
      Adds or updates a result value (an output value) on a folder (or line item) with given lineId.

      Example 1 – Setting a background color for the header output results: 

      
 quoteProcessor.addOrUpdateOutput(folderId,
         [
                 "resultName"   : "RedMinimumMargin",
                 "resultLabel"  : "Red (Minimum) Margin",
                 "result"       : totalMinimumRed,
                 "formatType"   : FieldFormatType.MONEY_EUR,
                 "resultType"   : CalculationResultType.SIMPLE,
                 "cssProperties": "background-color: red;",
                 // "suffix": "",
                 // "warnings" : []
         ]
 )
      Example 2 – Setting an overridable header output (using overrideValueOptions and isOverridable parameters): 
      
 quoteProcessor.addOrUpdateOutput("ROOT",
         [
                 resultName          : "ExportControlMessage",
                 resultLabel         : "Export Control Message",
                 resulType           : "TEXT",
                 result              : "Long",
                 overrideValueOptions: ["Long", "Short"],
                 isOverridable       : true
         ]
 )
      See also the overrideValueOptions setting for line items: AttributedResult.withManualOverrideValueOptions(List)

      Special resulName values – Specify one of the special resultName value (__UI_DetailPageHeader, __UI_HeaderDisplaySettings, or __UI_ItemsDisplaySettings) to:

      • Build a custom header using "resultName": "__UI_DetailPageHeader":
        For more details refer to the Configure a Custom Quote Header Knowledge Base article.
      • Render input fields side by side:
        Example: 
        
 if (quoteProcessor.isPostPhase()) {

     def displaySettings = [numberOfFieldsPerLine: 3]
     quoteProcessor.addOrUpdateOutput(
             [
                     "resultName": "__UI_HeaderDisplaySettings",
                     "resultType": "OBJECT",
                     "result"    : displaySettings
             ]
     )

 }

 if (quoteProcessor.isPrePhase()) {

     //create dummy sample input fields
     for (int i = 1; i <= 10; i++) {
         def inputField = api.inputBuilderFactory()
                 .createUserEntry("UserEntry$i".toString())
                 .buildMap()
         quoteProcessor.addOrUpdateInput(inputField)
     }

 }
        For more details refer to the Layout and Formatting of Input Fields (Reference).
      • Render line item sections: 
        
 quoteProcessor.addOrUpdateOutput([

         "resultName" : "__UI_ItemsDisplaySettings",
         "resultLabel": "__UI_ItemsDisplaySettings",
         "resultType" : "OBJECT",
         "result"     : ["viewType": "TABLE_VIEW"]    // possible values: TREE_VIEW, TABLE_VIEW, TABLE_VIEW_2

 ])
      Parameters:
      lineId - The id of the folder/line
      calculationResult - A map describing a calculation result
      Returns:
      itself (for flow pattern)
      See Also:

    • addOrUpdateInput

      public T addOrUpdateInput(Map<String,Object> contextParameter)
      Adds or updates an input parameter on the ROOT level.

      Example: 

      
 if (quoteProcessor.isPrePhase()) {

  def productInputMap = api.inputBuilderFactory()
                                 .createUserEntry("Discount")
                                 .setRequired(true)
                                 .buildMap()

  quoteProcessor.addOrUpdateInput("ROOT", productInputMap)

  }

      For more details see addOrUpdateInput(String, Map)

      Parameters:
      contextParameter - A map describing the context parameter (user input).
      Returns:
      itself (for flow pattern)
      See Also:

    • addOrUpdateInput

      public T addOrUpdateInput(String lineId, Map<String,Object> contextParameter)
      Adds or updates an input parameter on a folder (or line) with given lineId. Use the InputBuilder methods to define properties of the input.

      Example: 

      
 if (quoteProcessor.isPrePhase()) {

   def lineId = quoteProcessor.ROOT_LINE_ID // optional example: def lineId = quoteProcessor.quoteView.lineItems.getAt(0)?.lineId
   def userInputMap = api.inputBuilderFactory()
             .createUserEntry("Discount")
             .buildMap()

 quoteProcessor.addOrUpdateInput(lineId, userInputMap)

 }
      Parameters:
      lineId - The id of the line. Can be used on ROOT, Folders, and Items
      contextParameter - A map describing the context parameter (user input).
      Returns:
      itself (for flow pattern)
      See Also:

    • updateField

      public T updateField(String lineId, String fieldName, Object value)
      Updates a field on the line.
      Note: Not supported for all objects, e.g. quotes.
      Parameters:
      lineId - The id of the line
      fieldName - The field name
      value - The new value
      Returns:
      itself (for flow pattern)

    • updateField

      public T updateField(String fieldName, Object value)
      Updates a header field value.

      For quotes the supported fields are: additionalInfo1, additionalInfo2, additionalInfo3, additionalInfo4, externalRef, expiryDate, editabilityStatus, targetDate, label, userGroupEdit, userGroupViewDetails, attributeExtension.

      Example: 

      
 quoteProcessor.updateField("attributeExtension___Description", description)
      Parameters:
      fieldName - The field name
      value - The new value
      Returns:
      itself (for flow pattern)
      See Also:

    • setRenderInfo

      public T setRenderInfo(String fieldName, String key, Object value)
      Sets (adds or updates) rendering information for particular header fields and buttons. The available key/value pairs depend on a particular field. If a key is used that is unknown to the client, it will be ignored.

      The following fields and keys are supported (field names correspond to names in the JSON data structure):

      Document Type Supported Field Names Supported Keys (boolean type) Example
      Common for Quotes, Agreements & Promotions (Contracts), Rebate Agreements, Sales Compensation attachments, creationWorkflowLabel, creationWorkflowStatus, customHeader, directLink, endDate, externalRef, headerText (hides the "Description" field in a document detail page), label, prevRev, signatureStatus, startDate, supersededBy, targetDate, uniqueName, userGroupEdit, userGroupViewDetails, workflowStatus hide, required, disabled, collapsed (for customHeader only) 
      coProcessor.setRenderInfo("externalRef", "required", true) // sets the "External Reference" field required
      Additionally only for Quotes expiryDate, markAsLost, quoteStatus hide, required, disabled 
      quoteProcessor.setRenderInfo("expiryDate", "disabled", true)
      Additionally only for Agreements & Promotions (Contracts) contractExternalRef, contractStatus hide, required, disabled 
      cProcessor.setRenderInfo("contractExternalRef", "hide", true)
      Additionally only for Rebate Agreements payoutDate, rebateAgreementStatus hide, required, disabled 
      raProcessor.setRenderInfo("payoutDate", "hide", true)
      Additionally only for Sales Compensation payoutDate, compensationStatus hide, required, disabled 
      coProcessor.setRenderInfo("payoutDate", "hide", true)

      Note: targetDate and expiryDate cannot be set as non-mandatory for Quotes – e.g., quoteProcessor.setRenderInfo("targetDate", "required", false) will not set the field as not required in the Quote user interface.
      Note: customHeader supports only the collapsed key. For example, quoteProcessor.setRenderInfo("customHeader", "collapsed", true) will display the custom header collapsed (available for CLIC modules).

      The following buttons and keys are supported:

      Supported Button Names Supported Keys (boolean type) Example
      addFolder
      addItems
      attachmentsButton
      browseItems
      browseRecommendedItems
      convertToDeal
      copyToClipboard (REACT only)
      creationWorkflowBack
      creationWorkflowSubmitAndNext
      deleteButton
      duplicateButton
      editButton
      editLabelButton (allows to hide the pencil icon next to the label)
      emailCalculableButton
      exportDOCXButton
      exportPDFButton
      exportXLSXButton
      importExportButton
      importFromClipboard (REACT only)
      markAsLost
      massEditButton (hides the "Mass Edit" button in the Items tab)
      recalculateButton
      recalculateChangesItemsButton (default=true)
      recalculateChangesOutputsButton (default=true)
      reconvertToDealButton
      revisionButton
      revokeButton
      saveButton
      submitButton
      withdrawButton
      		 hide 
      
  quoteProcessor.setRenderInfo("recalculateChangesOutputsButton","hide", false) // displays the "Recalculate Changes" button within the Calculations sider on the Header and Items tab
      Note: Once you hide a button, you have to explicitly set hide to false or use clearRenderInfo(String) in order to let the button re-appear.

      For Custom Forms, the following buttons are supported:

      Supported Button Names Supported Keys (boolean type) Example
      submitButton
      recalculateButton
      withdrawButton
      revokeButton
      editButton
      duplicateButton
      deleteButton
      revisionButton      		 hide 
      
  customFormProcessor.setRenderInfo("revisionButton","hide",false) // displays the "Create New Revision" button on the Custom Form
      Parameters:
      fieldName - The name of the field or button this setting should be applied on.
      key - The setting name. Possible values are hide, required (not available for buttons), disabled (not available for buttons).
      value - Value An attribute of boolean type.
      Returns:
      itself (for flow pattern)
      See Also:

    • clearRenderInfo

      public T clearRenderInfo(String fieldName)
      Clears the existing render info for a field or for all fields.

      Example: 

      quoteProcessor.clearRenderInfo("submitButton")
      Parameters:
      fieldName - The field name to clear all info for, or null for all info for all fields
      Returns:
      itself

    • addLineItem

      public T addLineItem(String key)
      Adds a new line item in the root folder.
      Parameters:
      key - The key (usually the sku)
      Returns:
      itself (for flow pattern)

    • addLineItem

      public T addLineItem(String parentLineId, String key)
      Adds a new line item in the specified parent (folder ID).
      Parameters:
      parentLineId - id of parent item
      key - The key (usually the sku)
      Returns:
      itself (for flow pattern)

    • addLineItem

      public T addLineItem(String parentLineId, String key, List<Map<String,Object>> contextParameter)
      Adds a new line item in the specified parent (folder ID) and sets some context parameters.

      Sometimes it is required to pass values from a header logic to line items that this logic creates. You can use the HIDDEN input type and reference it in the calculation logic. The following code sample creates a new quote line with parameters fetched from the header logic: 

      
 def params = [[name:"MyHiddenParam", type: InputType.HIDDEN, value:"ABC"]]
 quoteProcessor.addLineItem("ROOT","MB-0003",params)
      In the line calculation logic, this value then can be retrieved by: 
      
 def val = input.MyHiddenParam
      Notes:
      • This way you can also set default values of "real" input parameters as determined by the line calculation logic. Set the value in the header logic and make sure that the names of the parameter match in both logics.
      • If you use this method only to transport values between the header and line, set the parameter type to HIDDEN. The value can also be a map to transport more structured data.
      • Any parameter that is non-HIDDEN and not determined by the line item logic will be removed.
      • Be aware that this hidden data is also exposed to the user (it is part of the quote response). It is not visible in the UI, but that does not make it a secure storage! Also, try to keep the data volume reasonably low.
      You can also set default values for items created using the quoteStructure class: 
      
 def params = [[name:"MyHiddenParam", type: InputType.HIDDEN, value:"ABC"]]
 def qs = new QuoteStructure()
 qs.addPart("MySKU",params) //use add.Folder for a folder
      Parameters:
      parentLineId - id of parent item
      key - The key (usually the sku)
      contextParameter - A list of maps describing the context parameters
      Returns:
      itself (for flow pattern)

    • moveItem

      public T moveItem(String lineId, String newParentId)
      Moves an item or folder under a new parent. Only works in the PRE phase.
      Parameters:
      lineId - The line ID of the item to move
      newParentId - The line ID of the target folder. null if you want to move it to root folder
      Returns:
      itself (for flow pattern)

    • renameFolder

      public T renameFolder(String lineId, String newFolderLabel)
      Renames a folder (not items).
      Parameters:
      lineId - The line ID of the folder to rename
      newFolderLabel - New label
      Returns:
      itself (for flow pattern)

    • deleteItem

      public T deleteItem(String lineId)
      Deletes an item or folder. Only works in the PRE phase.
      Parameters:
      lineId - The line ID of the item to remove
      Returns:
      itself (for flow pattern)