NextGen Consulting

IT Consulting CRM BSS OSS

Implementing Lookup Control

About Lookup Control


The Lookup control assists users search for data with which they need to associate.

For example, when creating a new contact, we need to need to associate it with a site to which this contact belongs.

The lookup button launches a search form which allows the user to select the relevant record that update the necessary values in the launching form.

The lookup button is often used in create and edit forms, where the main focus object (in our above example – a new contact) needs to be related to another object (site in above example.

The Lookup control allows users to search and associate objects in the application. The control provides standard drop-down button functionality plus additional specific ones.

The Lookup control contains the following predefined menu items:

  • Lookup
  • Lookup & Details
  • Details
  • Clear

The Lookup menu item should be associated with SearchLaunchAction. The Launch action should have a Data Communication Element that returns data from a listing form when ‘postSelectionCommit’ event is fired by the Grid control on the launched form.



LookedUp Property

 The Lookup Control is set to lookedUp if the data models targeted by the DCE are updated after lookup. 

  • The  lookedUp  property status is visually reflected by a green checkmark icon displayed over the lookup glasses.
  • The  lookedUp  property can be set programmatically using the following code:




Lookup Control Flow




Implementing Lookup Control 

The following step by step example illustrates how to use the Lookup control.


Our goal is to allow the user to enter in the textbox part of the contact’s first name.

  • Upon clicking on the Lookup Button,  Its corresponding Search Launch Action will invoke the Search Contact form and set its search criteria to look for a contact whose first name starts with the entered string.
  • If the Search Contact form finds a single record, the Search Contact form will remain invisible and immediately return back to the Lookup form while passing selected fields of the found contact record using CDE (Communication Data Elements).
  • If more than a single record is found, the Search Contact Form will be opened displaying a list of records which address the query. The user can then manually select any of the displayed records and click the Grids ‘Select’ button to pass the information back to the calling form.
  • The data returned to the calling form (the one which contains the LookUp button) should contain the found contact’s first and last names (first_name, last_Name).
  • The returned data for  first_name and last_name will be formatted to construct a single field which contains the user full name. This field (‘formatted_name”) is part of the contactDM Data Model and is bound to the textbox “txtContactName”.
  • When updated with the full name, the contatDM field will be immediately rendered by the textbox.




A.   Add Controls on form’s panel.

We first add the following controls:

  • Lookup Button     name: “LookUpContact”
  • TextBox               name: “txtContactName”
  • Label                   name: “lblContactName”


Lookup Control:



B.   Add data Models:

  • contactDM
  • contactSearchInfoDM
  • contactSearchCriteriaTDM


contactDM properties:




contactDM Data Model Definition




contactSearchInfoDM Data Model Definition




contactSearchCriteriaTDM Data Model Definition




C.      Add Search Launch Action:

Name: “contactLookupAction”



Set Search Launch Action properties




Search Launch Action Launch Data Map

Search Launch Action LogicalFormName:


Search Launch Action Events




The contactLookup_ActionStart event prepares the search criteria data




D.     Add DCE_ContactLookup Data Communication Element:




DCE_ContactLookup Properties

The triggerEvent sets the name of the event that triggers this DCE.

If the triggerSource property is not set, then this is considered as a user event which needs to be fired by the application code by calling DataCommSet.triggerEvent.


DCE_ContactLookup Events


The DCE_ContactLookup_postExecuteInTarget event handler copies first_name and last_name fields values back to contactDM ‘formatted_name’ field value. The ‘formatted_name’ value is bound to the textbox ‘text’ property. This field will be populated with first and last names.




DCE_ContactLookup Item Properties

SourceDMPath:    $DataProvider:gridListing:SelectedRowsTDM




DCE_ContactLookup Item field #1 properties




DCE_ContactLookup Item field #2 properties:



Test it – Run the application


Step 1:

  • The user enters first two letters of contact’s name.
  • The User clicks the Lookup button

  • The Search Launch action launches the Search Contacts form and passes it the search criteria data model (first_name startsWith ‘yu’).
  • The Search Contact form silently searches for contact’s first name that starts with ‘yu’ and find a single record that match these criteria.
  • Records first and last names are passed back to the calling form by Data Communication Elements.




Step 2:

  • The calling form pass first_name and last_name to the contactDM field named formatted_name.
  • The formatted_name is bound to the Contact Name textbox. Full name displayed.
  • The LookedUp propery is set to ‘validated’.






  1. Hi Yuval
    In the case, I don’t input data into textbox and I click button lookup then what is the result?

    It will display context list screen?


    Comment by quantran | 06/10/2010 | Reply

  2. It will display contact list screen

    Comment by quantran | 06/10/2010 | Reply

  3. In case, when you click the lookup button it may take the information from various data models.

    If the search criteria finds a single record, all details will be filled by the DCE.

    If the search does not find any record, it will show the relevant Search grid (search contacts).

    The type of the search grid which will be serached depends on the parameters provided to the lookup control launch action. The example above provides the following parameter:

    Search Launch Action

    General comments:
    Textbox is only one way of providing input to related (bound) data model field. There are many other ways to feed this information (i.e programatically) and invoke the lookup control.

    A nice example for this is the CIM Find Caller functionality. This CimFindCaller form takes the search input, and pass the information to onother form (FindCaller Toolbar). The FindCaller Toolbar PROGRAMATICALLY invokes appropriate lookup search (Contact and Accound, Contact and Subscruption, Contact and Customer) using the above input.

    In other words, the input is provided programatically and is also used to select the search algorithm.

    Comment by Yuval R. | 06/10/2010 | Reply

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: