How-to: Create custom Lookup Function

Description

Adding a new custom Lookup function with one "Header field" to show simple lookup response.

This example will result in a lookup function accessible by a Action.

The lookup will return information from the BC standard field "Work Description" in the Sales Order header.

Other uses

• This example can display any information from Business Central, like Comments, notes or instructions

Prerequisites

Please read Lookup Functions to ensure this flow suits your requirement.

Step 1: Defining a new page for the custom Lookup function 

This part requires you to edit the Mobile Configuration Files

Add this section in the <pages> tag.

We use two special properties in the <header> element to achieve the desired behavior on the device. 

• automaticAcceptOnOpen = Defines if the values in the header should be automatically accepted. Formerly known as updateOnActivate.
• hideAfterAccept = If true, hide (collapse) the header when "Accept"-button is pressed at Mobile Device

More details: Lookup Mobile Configuration

<!-- Custom -->
<page id="WorkDescription" type="Lookup" icon="stopwatch">
  <title defaultValue="Work Description"/>
  <lookupConfiguration type="WorkDescription" useRegistrationCollector="false">
    <header configurationKey="WorkDescriptionHeader" automaticAcceptOnOpen="true" hideAfterAccept="true"/>        
    <list listId="Lookup"/>       
  </lookupConfiguration>      
</page>
<!-- Custom -->

Add this section to the <actions> tag in the Pick page.

<!-- Custom -->
<open id="WorkDescription" icon="stopwatch" title="Work Description"/>
<!-- Custom -->

Step 2: Define Header and header fields

For this example we only add one field containing the BackendID.

(When using same fieldname as in the page that is linked from, it will get automatically populated on the device)

Subscribe to this event

OnGetReferenceData_OnAddHeaderConfigurations "Create HeaderFields or Add HeaderFields to existing headers."

    // Step 2  Create new custom ConfigurationKey

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Reference Data", 'OnGetReferenceData_OnAddHeaderConfigurations', '', true, true)]
    local procedure OnGetReferenceData_OnAddHeaderConfigurations(var _HeaderFields: Record "MOB HeaderField Element")
    begin
        // Identifier for new ConfigurationKey - replace by your own key name
        _HeaderFields.InitConfigurationKey('WorkDescriptionHeader');

        // Add headerConfiguration elements here                
        _HeaderFields.Create_TextField(1, 'BackendID');
    end;

Step 3: Handle lookup

When the Header has been accepted, a final request is made to lookup the information ("Lookup")

In this step you must handle your custom lookup named "WorkDescription" and read the collected values (BackendID).

We will return a "LookupResponseElement" containing only DisplayLine1.

Subscribe to this event

OnLookupOnCustomLookupType... "Implement your own custom LookupType."

    // Step 3  Handle lookup
    
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Lookup", 'OnLookupOnCustomLookupType', '', true, true)]
    local procedure MyOnLookupOnCustomLookupType(_MessageId: Guid; _LookupType: Text; var _RequestValues: Record "MOB NS Request Element"; var _XmlResultDoc: XmlDocument; var _RegistrationTypeTracking: Text; var _IsHandled: Boolean)
    begin
        if _LookupType <> 'WorkDescription' then
            exit;

        WorkDescriptionLookup(_LookupType, _RequestValues, _XmlResultDoc);
        _IsHandled := true;
    end;

    local procedure WorkDescriptionLookup(var _LookupType: Text; var _RequestValues: Record "MOB NS Request Element"; var _XmlResultDoc: XmlDocument)
    var
        TempLookupResponseElement: Record "MOB NS WhseInquery Element" temporary;
        MobWmsLookup: Codeunit "MOB WMS Lookup";
        MobToolbox: Codeunit "MOB Toolbox";
        MobXmlMgt: Codeunit "MOB Xml Management";
        XmlResponseData: XmlNode;
        BackendId: Code[20];
    begin
        // Read Request        
        Evaluate(BackendId, _RequestValues.Get_BackendID());

        // Initialize the response xml
        MobToolbox.InitializeResponseDocWithNS(_XmlResultDoc, XmlResponseData, CopyStr(MobXmlMgt.NS_WHSEMODEL(), 1, 1024));

        // Create new Response Element
        TempLookupResponseElement.Create();
        TempLookupResponseElement.Set_DisplayLine1(GetWorkDescription(BackendId));
        TempLookupResponseElement.Save();

        MobWmsLookup.AddLookupResponseElements(_LookupType, XmlResponseData, TempLookupResponseElement);
    end;

    local procedure GetWorkDescription(_BackendId: Code[20]): Text
    var
        WhseActHeader: Record "Warehouse Activity Header";
        SalesHeader: Record "Sales header";
    begin
        if WhseActHeader.Get(WhseActHeader.Type::"Invt. Pick", _BackendId) then
            if SalesHeader.Get(SalesHeader."Document Type"::Order, WhseActHeader."Source No.") then
                exit(SalesHeader.GetWorkDescription());
    end;

NOTE:

<BackendID> or <OrderBackendID> ?

Depending on the context where you are adding the new menu Item, the xml response will be different and require you to change the code accordingly.

• Use the new action on an "Orders List"
  • Request
    • Will use <requestData name="GetPickOrders">
  • Response
    • Will use the element named <BackendID>

• Use the new action on an "Order Lines List"
  • Request
    • Will use the <requestData name="GetPickOrderLines">
  • Response
    • Will use the element named <OrderBackendID>

// Read Request, use either Get_BackendID or Get_OrderBackendID depending on Context
Evaluate(BackendId, _RequestValues.Get_BackendID());

// or

Evaluate(OrderBackendId, _RequestValues.Get_OrderBackendID());