FX Item Picker Setup

Prerequisites

Basics

FX Item Picker enables FieldFX Back Office users to find and select items from one sObject and add them to another sObject.

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.

Considerations

  • The FX Item Picker depends on the related object’s Search layout.

  • Items cannot be added to the associated item grid if the record is in a read-only Workflow Status.

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

Setting Up FX Item Picker

The Item Picker does not 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.

    The only required entry is Picker Object.

    1. Compact: Select to use smaller grid rows and columns.

    2. Picker Object: 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.

    3. Picker Lookup Field: The field on the object you want use to filter items in the resulting grid

    4. 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

    5. Picker Filter: A SOQL statement to control valid entries

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

    6. Action Button Label: Text to display on a button a user can click to take action on selected items

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

    7. Target Object: The sObject where the entries should be added

    8. 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.

    9. Target Object Item Field: The field on the target object to create the records in

    10. UID of Item Cart (optional): UID of the FXL Item Cart to update with selections from this FX Item Picker

    11. 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:

      • The group of items can be collapsed to show only the parent item.

      • Child items cannot be selected.

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

    12. Expand Children by Default (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

    13. 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.

  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.

Customizing the Sequence of Selected Items

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

  • The FX Item Picker supports allowing a user to define the sequence number used when adding the selected items to the FXL Data Grid.

    • When 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.

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

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

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.

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 a Ticket, Select Items to Add from a Quote

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

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