Line Items Creation Configurer Class

This Apex hook can alter new lines that are being created, remove new lines, and create new lines based on products that the user selects.

This hook occurs after the user selects the Add Lines button on the Add Lines component, and before the IQA call for any of the new lines being added.

Apex hook class

• It must implement one of the following interfaces:
  • zpl.LineItemsCreationConfigurer2
  • zpl.ScopedLineItemsCreationConfigurer
• It must have a global access modifier.
• You must specify the Apex hook class name in the Line Items Creation Configurer Class field of the Product Selector Configuration.

Definition for the zpl.ScopedLineItemsCreationConfigurer​ interface

/**
 * Interface for a hook class that determines which line item records will be created.
 * The getLineItemsForCreation() will get in its parameter all the line items that were selected by the user and
 * should have been created.
 * The lines in the list can be updated or removed. Moreover, other lines can be added to the list. The method will return
 * the LineItemsCreationData object containing line items that should be created and optional message that will be shown to user.
 * It is allowed to persist lines directly in the hook class if needed. Those lines what were persisted in the hook won't be
 * persisted once again by the product code.
 * @param lineItems the list of line item records which the user has selected to Add
 * @param preEntryFields list of the Pre-entry Fields defined on the UI
 * @param preEntryFieldsValues map of the user-entered values for the each Pre-entry Field defined
 *      KEY: API name of the pre-entry field (SalesforceField__c), VALUE: user-entered field value
 * Note: if pre-entry field allows multi select then VALUE will hold List<Object>, otherwise - single Object
 * @return LineItemsCreationData, containing the list of actual line items to create and optional custom message to show to user
 */
global interface LineItemsCreationConfigurer2
{
    LineItemsCreationData getLineItemsForCreation(SObject[] lineItems, List<PreEntryField__c> preEntryFields,
            Map<String, Object> preEntryFieldsValues);
}
/**
 * Interface for a hook class that determines which line item records will be created. This version of the interface extends
 * LineItemsCreationConfigurer2 to add the option to include scoping restrictions. To ignore scope, use LineItemsCreationConfigurer2 directly.
 * The getLineItemsForCreation() will get in its parameter all the line items that were selected by the user and should have been created.
 * The lines in the list can be updated or removed. Moreover, other lines can be added to the list. The method will return
 * the LineItemsCreationData object containing line items that should be created and optional message that will be shown to user.
 * It is allowed to persist lines directly in the hook class if needed. Those lines what were persisted in the hook won't be
 * persisted once again by the product code.
 */
global interface ScopedLineItemsCreationConfigurer extends LineItemsCreationConfigurer2
{
    /**
    * @param lineItems the list of line item records which the user has selected to Add
    * @param preEntryFields list of the Pre-entry Fields defined on the UI
    * @param preEntryFieldsValues map of the user-entered values for the each Pre-entry Field defined
    *      KEY: API name of the pre-entry field (SalesforceField__c), VALUE: user-entered field value
    * Note: if pre-entry field allows multi select then VALUE will hold List<Object>, otherwise - single Object
    * @param scope map of system-defined values by which to constrain the available records
    *       KEY: name of the scoping element, VALUE: value of the scoping element
    * @return LineItemsCreationData, containing the list of actual line items to create and
    *      optional custom message to show to user
    */
    LineItemsCreationData getLineItemsForCreation(SObject[] lineItems, List<PreEntryField__c> preEntryFields,
            Map<String, Object> preEntryFieldsValues, Map<String, Object> scope);
}

Where the LineItemsCreationData is the class used to return lines and the optional custom message.

Definition for the zpl.LineItemsCreationData

global class LineItemsCreationData
{
    @AuraEnabled global SObject[] lineItems { get; private set; }
    @AuraEnabled global String message { get; private set; }
    global LineItemsCreationData(SObject[] lineItems)
    {
        this.lineItems = lineItems;
    }
    global LineItemsCreationData(SObject[] lineItems, String message)
    {
        this.lineItems = lineItems;
        this.message = message;
    }
}

Definition for the zpl.LineItemsCreationConfigurer2 interface

/**
 * Interface for a hook class that determines which line item records will be created.
 *
 * The getLineItemsForCreation() will get in its parameter all the line items that were selected by the user and
 * should have been created.
 * The lines in the list can be updated or removed. Moreover, other lines can be added to the list. The method will return
 * the LineItemsCreationData object containing line items that should be created and optional message that will be shown to user.
 *
 * @param lineItems the list of line item records which the user has selected to Add
 * @param preEntryFields list of the Pre-entry Fields defined on the UI
 * @param preEntryFieldsValues map of the user-entered values for the each Pre-entry Field defined
 *      KEY: API name of the pre-entry field (SalesforceField__c), VALUE: user-entered field value
 * Note: if pre-entry field allows multi select then VALUE will hold List<Object>, otherwise - single Object
 *
 * @return LineItemsCreationData, containing the list of actual line items to create and
 *      optional custom message to show to user
 */
global interface LineItemsCreationConfigurer2
{
    LineItemsCreationData getLineItemsForCreation(SObject[] lineItems, List<PreEntryField__c> preEntryFields,
            Map<String, Object> preEntryFieldsValues);
}

Difference between zpl.LineItemsCreationConfigurer2 and zpl.ScopedLineItemsCreationConfigurer interfaces

zpl.ScopedLineItemsCreationConfigurer is an enhanced version of the configurer interface. It has one additional parameter—scope that can be passed inside the hook from the Line Items component.
You can define the scope in the App Builder Scope (JSON) property of the Line Items component. Once you have defined it, and used the scoped version of interface, the scope will be passed inside the Apex hook as a parsed JSON in the Map<String, Object> form.

Example of the class implementation

global class SampleLineItemsCreationConfigurer2 implements zpl.LineItemsCreationConfigurer2, zpl.ScopedLineItemsCreationConfigurer
    {
        global zpl.LineItemsCreationData getLineItemsForCreation(SObject[] lineItems, List<zpl__PreEntryField__c> preEntryFields,
                Map<String, Object> preEntryFieldsValues)
        {
            List<SObject> updatedLineItems = new List<SObject>(lineItems);
            for (SObject lineItem : lineItems)
            {
                for (Integer i = 0; i < 3; i++)
                {
                    SObject clone = lineItem.clone();
                    updatedLineItems.add(clone);
                }
            }
            return new zpl.LineItemsCreationData(updatedLineItems, 'customMessage');
        }
        global zpl.LineItemsCreationData getLineItemsForCreation(SObject[] lineItems, List<zpl__PreEntryField__c> preEntryFields,
                Map<String, Object> preEntryFieldsValues, Map<String, Object> scope)
        {
            List<SObject> updatedLineItems = new List<SObject>(lineItems);
            for (SObject lineItem : lineItems)
            {
                for (Integer i = 0; i < 2; i++)
                {
                    SObject clone = lineItem.clone();
                    updatedLineItems.add(clone);
                }
            }
            return new zpl.LineItemsCreationData(updatedLineItems, 'customScopedMessage');
        }
    }