FXL Item Picker Setup

Introduction

FX Item Picker enables FieldFX Back Office users to find and select items from one sObject and add them to another sObject. You can also use the FX Item Picker in the Lightning version.

Example 1. When you might use the FX Item Picker

  • Add items to a ticket while looking at the quote, filtered by the correct price book.

  • Add items to a ticket from a list of items included on the quote.

  • Add items to a price book from a selection of catalog items.

The FX Item Picker is generic and intended to be highly customizable.

Optionally, you can configure custom labels for the FX Item Picker Lightning Component.

To use the FieldFX Lightning package starting with version 1.225, you must use the FieldFX Managed Package version 1.529 or higher.

To find the version numbers you have installed, see Check Version Number for FieldFX Managed Package and FieldFX Lightning Managed Package.

Prerequisites

Complete the Salesforce Lightning AppBuilder training before setting up and configuring the FX Item Picker for the first time.

To set up the FX Item Picker, you need:

Needed Permissions Needed Licenses Complete These Tasks
Prior to First Time Setup

  • System Administrator permissions

Back to Top

Considerations

The FX Item Picker depends on the related object’s Search layout. if the record is in a read-only Workflow Status, Items can’t be added to the associated item grid.

Do not add the FX Item Picker inside of an Accordion Lightning Component. Doing so leads to undesirable results and slow performance.

Adding a Field to an Existing FX Item Picker

If an Admin adds an additional field to the search layout used by an existing FX Item Picker, users must manually activate that field in the FX Item Picker before it displays for the user.

  1. Access the affected FX Item Picker.

  2. Select the gear icon to the right of the FX Item Picker’s Search field.

  3. Click to select the new field’s blank checkbox.

    The field displays in the FX Item Picker.

    GIF showing clicking on the FX Item Picker’s Gear Icon and selecting an additional field to show

Step-by-Step Guides

In setting up the FX Item Picker you can use custom code snippets for APEX and JavaScript to capture and publish a lightning event. There are also steps on the advanced usage for the filter settings.

The Item Picker doesn’t work for Text Area, Text Area (Long), or Text Area (Rich Text) field types. These are automatically filtered out by the picker. The Picker Object specified must have a Search Layout defined that includes fields of other types available for the FX Item Picker to work.

  1. Access FieldFX Back Office.

  2. Switch to the Lightning Experience.

  3. Access the page that you want to use the FX Item Picker.

  4. Select the gear icon, then click Edit Page.

  5. Type FX Item Picker in the Search components.. box.

    Features FX Item Picker Component Selection

  6. Drag the FX Item Picker from the Custom - Managed list to the place on the page where you want the picker to appear.

  7. Make sure the Item Picker is the selected component on the page.

  8. Define the settings for the component using the options on the right side of the screen.

    Table 1. Item Picker Configuration Options
    Settings Description

    Picker Heading

    Enter the heading of the picker. See Customize the Picker Heading and Title section.

    Picker Title

    Enter the title for the picker. See Customize the Picker Heading and Title section.

    Compact checkbox

    Select to use smaller grid rows and columns.

    Picker Object
    (Required)

    The sObject from which you need to select items.

    If the object is a price book in a price book hierarchy with extended pricing enabled for the job, the results grid displays additional results from parent price book(s) in the hierarchy.

    The Enable_Extended_Price__c field must exist on the Job and Quote objects and must be set to true for the specific Job or Quote for this feature.

    See the price book hierarchy setup instructions for details.

    The specified Object must have a Search Layout that includes fields other than Text Area, Text Area (Long), or Text Area (Rich) type fields.

    Those fields can be present on the search layout as well, but there must be other types of data on the search layout for the object for the FX Item Picker to function.

    Picker Lookup Field

    The field on the object you want use to filter items in the resulting grid.

    Picker Lookup Value

    The path to the field on the current page you want to use as the value for the Picker Lookup Field used for the filter.

    Picker Filter

    A SOQL statement to control valid entries.

    For example, a SOQL statement to filter out archived items.

    Action Button Label

    Text to display on a button a user can click to act on selected items.

    For example, Create Ticket Items as the button text to add selected items to a ticket.

    Target Object

    The sObject where the entries should be added.

    Target Object Parent Lookup Field

    The field on the current page that names the parent object for the selected items being created.

    For example, for the Target Object FX5__Ticket_Item__c, FX5__Ticket__c is the parent field, because every ticket item must be on a ticket.

    Target Object Item Field

    The field on the target object to create the records in.

    Show the '# of Items Columns' Column
    checkbox

    Select this checkbox to show a new column of the number of items.

    Field For '# of Items' Column

    Enter the text for the column title. You can use an expression to define its custom label. The correct format is $Label.customLabelName.

    Always fire lightning event

    Use this to automatically kick off a lightning event.

    If it’s unchecked and after an item is added, the FX Item Picker sends a refresh event that other Lightning components can listen out for, then refresh if they need to.

    If it’s checked, other FieldFX components can be designed to listen for the event and then process the event as they are designed for.

    UID of Item Cart
    (optional)

    UID of the FXL Item Cart to update with selections from this FX Item Picker.

    Parent Field (For Bundles)
    (optional)

    field on the sObject that items are bundled by.

    For example, for Price Book Items, the field is the Parent_Price_Book_Item__c field.

    When parent and child items exist in the picker:

    • You can collapse the group of items to show only the parent item.

    • Child items cannot be selected.

    • The parent and all children are selected together from the picker and added to the Target Object.

    Expand Children by Default checkbox
    (optional)

    Select to display parent and child items when the FXL Item Cart loads; otherwise, only parent items display and users must expand the parent item(s) to see child items

    Users retain the ability to expand or collapse the child items with either option .. Max number of items that can be inserted at once: number of items users can select to add to the FXL Data Grid at the same time.
    The default value when blank is 6. The maximum number that can be selected at once is 100.

    If users select more items than the allowed value, they are not able to add the items to the FXL Data Grid. The button is grayed out.

    When the user hovers over the button, a message displays informing the user of the maximum number of selected items.

    Example of the message that displays showing the maximum number of items when hovering over the i icon.
    This option does not apply if the selected items go to an FX Item Cart.

    Max Number of items that can be inserted at once

    Enter the maximum number of items that are shown in the grid at one time.

    Even though setting a maximum number to 500, a high number like that can impact performance and cause a degradation in grid display. Start with 100 at first. If there is a degradation, have your admin lower the number.

    Column for setting insert sequence order (leave blank to deactivate)

    This column sets the insert sequence order. If you set this field, it will increment on the target object by one per insert. You can use an expression to define its custom label. The correct format is (!$Label.customLabelName).

    See Customize Selected Items Sequence for more information.

    Target’s Parent Field
    (For bundles, when setting sequence)

    This field is used to bundle child items on the target object. You can use and expression to define a custom label. The correct format is (!$Label.customLabelName).

    Set Component Visibility > Filters

    Click to add a filter.

    See Advanced Filter Settings Use for more information.

  9. Click Save.

    See specific setup examples below the image.
    Screenshot of the FX Item Picker options with completed entries
    Figure 1. Default FX Item Picker settings for selecting Quote Items to add to a Ticket.

Lightning Event Code Snippets

If you want to capture and publish a lightning event, use the following code snippets.

APEX Code Snippet (Capturing a Lightning Event)

The below example highlights an apex class that contains a function called forward. The function accepts a JSON string object, deserializes it, and returns the object. In the return portion of the code, you can replace the snippet of code with whatever you need to do with the event, including forwarding it to another API, etc.

APEX Code Snippet
public with sharing class fxlwc_controller_event {

    @AuraEnabled
    public static String forward(String event){
        try {
            Object eventData = JSON.deserializeUntyped(event);
            return event;
        } catch (Exception e) {
            throw new AuraHandledException(e.getMessage());
        }
    }
}

For more information, see Salesforce Developer Documentation: Communicate with Events.

JavaScript Code Snippet (Publishing a Lightning Event)

The below snippet of code is the JavaScript side of this lightning web component. The messageService, FXL_MESSAGE, and the invokeForwardEvent function are imported.

The LWC subscribes to the message lightning events channel using the subscribeMC() function. This function simply runs a subscribe method and passes in a brand-new message context, a channel to listen to FXL_MESSAGE, a handler, and an object scope. Whenever this component receives an event, it will convert the JSON string to an the event, and fire it to the apex function forward by using the invokeForwardEvent function that was imported. In doing so, the apex code, shown above, will capture the event, deserialize it, and the implementor is free to do what they will with the event.

JavaScript Code Snippet
import { LightningElement, track } from "lwc";
import {
  subscribe,
  APPLICATION_SCOPE,
  createMessageContext,
} from "lightning/messageService";
import FXL_MESSAGE from "@salesforce/messageChannel/FXL_MESSAGE__c";

import invokeForwardEvent from "@salesforce/apex/fxlwc_controller_event.forward";

export default class Fxlwc_event_viewer extends LightningElement {
  @track subscription = null;
  @track receivedMessage = "";

  constructor() {
    super();
    this.subscribeMC();
  }

  subscribeMC() {
    if (this.subscription) {
      return;
    }
    this.subscription = subscribe(
      createMessageContext(),
      FXL_MESSAGE,
      (message) => {
        this.handleReceivedMessage(message);
      },
      { scope: APPLICATION_SCOPE }
    );
  }

  handleReceivedMessage(message) {
    this.receivedMessage = message
      ? JSON.stringify(message, null, "\t")
      : "no message payload";


    invokeForwardEvent({event: JSON.stringify(message)}).catch(err => {
      console.error(err);
    });

  }

  get subscribeStatus() {
    return this.subscription != null ? "True" : "False";
  }
}

To publish events in lightning web components, execute this.dispatchEvent(new CustomEvent('previous')); if the JavaScript class extends the LightningComponent class. See Salesforce Developer Documentation: Create and Dispatch Events for more information regarding dispatching lightning events.

In the example code above, the event captured was fired by an older EventService that was written, however, it works the same way.

Back to Top

Customize the Picker Heading and Title

You can customize the Picker Heading and Picker Title fields for the FX Item Picker on any records page where it’s being used.

If you leave these fields blank,

  • The Picker Heading defaults to FXL Data Grid

  • The Picker Title defaults to the item’s object label.

These properties also support using an expression to define its custom label. The correct format is (!$Label.customLabelName).

Advanced Filter Settings Use

You can use these two settings to take advantage of advanced filter settings.

Setting Example Description

$source

 
Target__Segment__c = '$source.Segment__c'

Allows the user to incorporate into filters the record detail (if applicable) and its specific fields.

For example, Picker results are filtered to Segment__c on the source record.

$user

 
CreatedBy.User.Id = '$user.id'

Allows incorporation into filters the logged in User and its specific fields.

For example. Picker results are filtered to only those items created by the logged in User.
There is no autocompletion for the properties of the objects. You should follow SOQL rules for the where clause.

Back to Top

Customize Selected Items Sequence

This functionality is intended specifically to address a scenario where the FX Item Picker is used to add Ticket Items to an Invoice.

With the FX Item Picker a user can define the sequence number used when adding the selected items to the FXL Data Grid. After set up, the user can define the order in which selected items should be added to the FXL Data Grid.

Items are added to the Selected Items tab of the FX Item Picker in the order in which the user selects them. The user can use the arrows in the Order column of the Selected Items tab to reorder the selected items before adding them to the FXL Data Grid.

LMP141 FX Item Picker Order Sequence

Child items are added immediately after their parent item, but can be reordered within the limits of the parent item’s sequence.

Sequence numbers are controlled by two fields in the FX Item Picker component’s settings:

Column for setting insert sequence order

A number field on the target object to use for sequencing items

Leaving this field blank disables the sequence numbering by selection order.

This can be the Sequence Number field. However, if so, the price book’s FX5__AddTktItemsByPBSeqNum__c field must be set to False.

Target’s Parent Field
(For bundles, when setting sequence)

Field on the target object that defines the parent for child items

For example, for the FX Item Picker used to add Invoice Items, FX5__Parent_Invoice_Item__c.

The parent field on the source object must also be defined in the FX Item Picker’s Parent Field (For Bundles) setting.

Sequence Number Considerations

The assignment of sequence numbers by selection order applies only to FieldFX Back Office. Sequence number assignments from items added in FieldFX Mobile continue to behave as they always have.

If the organization also has FX CPQ and utilizes the Rule Engine, the sequence numbers for items added by the Rule Engine are determined by the Rule Engine and do not follow the settings from the FX Item Picker.

Examples

These examples show the values to use when selecting items from tickets, quotes, price books, invoices, and FX EAM Purchase Orders.

For each example, add the FX Item Picker component to the page for the object you are working with.
Object Type Example

Ticket

Add from a price book
Add from a quote

Quote

Add from a price book

Price Book

Add from catalog items

Invoice

Add from ticket items

EAM Purchase Order

Add stock items from a warehouse

For a Ticket

Select Items To Add from a Price Book

Component Option Value

Picker Object

FX5__Price_Book_Item__c

Picker Lookup Field

FX5__Price_Book__c

Picker Lookup Value

FX5__Job__r.FX5__Price_Book__c

Picker Filter

FX5__IsArchived__c = False AND FX5__Parent_Price_Book_Item__c = null
(FX5__Catalog_Item_Code__c Like 'Crew - Planning%' OR FX5__Catalog_Item_Code__c = 'Invoice Comments')

Action Button Label

Add Ticket Items

Target Object

FX5__Ticket_Item__c

Target Object Parent Lookup Field

FX5__Ticket__c

Target Object Item Field

FX5__Price_Book_Item__c
If Price Book Hierarchy is enabled, items from parent price books also display.

Select Items to Add from a Quote

This particular scenario requires additional triggers and is not currently supported.

For a Quote, Select Items to Add from a Price Book

Component Option Value

Picker Object

FX5__Price_Book_Item__c

Picker Lookup Field

FX5__Price_Book__c

Picker Lookup Value

FX5__Price_Book__c

Picker Filter

FX5__IsArchived__c = False AND FX5__Parent_Price_Book_Item__c = null

Action Button Label

Add Quote Items

Target Object

FX5__Quote_Item__c

Target Object Parent Lookup Field

FX5__Quote__c

Target Object Item Field

FX5__Price_Book_Item__c

For a Price Book, Select Items to Add from Catalog Items

Component Option Value

Picker Object

FX5__Catalog_Item__c

Picker Lookup Field

Picker Lookup Value

Picker Filter

FX5__IsArchived__c = False AND FX5__Parent_Price_Book_Item__c = null

Action Button Label

Add Price Book Items

Target Object

FX5__Price_Book_Item__c

Target Object Parent Lookup Field

FX5__Price_Book__c

Target Object Item Field

FX5__Catalog_Item__c

For an Invoice, Select Items to Add from Ticket Items

Caution: The generic FX Item Picker controls will likely not produce desired results for invoicing without additional configurations.
Component Option Value

Picker Object

FX5__Ticket_Item__c

Picker Lookup Field

FX5__Job__r.FX5__CustomerAccount__c

Picker Lookup Value

FX5__CustomerAccount__c

Picker Filter

FX5__Invoice_Item__c = NULL AND ticket_status__c = 'Ready for Invoicing'

Action Button Label

Create Invoice Items

Target Object

FX5__Invoice_Item__c

Target Object Parent Lookup Field

FX5__Invoice__c

Target Object Item Field

FX5__Ticket_Item__c

For an FX EAM Purchase Order, Select Stock Items to Add from a Warehouse

Component Option Value

Picker Object

FX5__StockItem__c

Picker Lookup Field

FX5__Warehouse__c

Picker Lookup Value

FX5__Warehouse_ID__c

Action Button Label

Create PO Stock Items

Target Object

FX5__POStockItem__c

Target Object Parent Lookup Field

FX5__Purchase_Order__c

Target Object Item Field

FX5__Stock_Item__c

Back to Top