Adding Pre and Post population lookups to your Request form

Pre and Post population lookup forms will either pre-populate your forms or post-populate your forms, during the client interaction with the form.

Pre population definitions are ideal for Single Sign-On environments; where data needs populated prior to visiting the form, based off of some outside element, such as NetworkID, etc.

Post population definitions are ideal for Email Importing environments; to populate a question with a lot of data about a client (entering data into the form), without the need to include the form input field on the form.

Pre/Post Pop Definition Location

In System/Request forms, select the request form to which you want to add the Lookups, by clicking on “Options” and then the Lookups tab.

The only lookup definitions that will show up in this Lookups tab will be Form Population definitions. These are defined in System->Lookups->Lookup definitions:

You can have as many different Form Population types as you need for lookups, as often times, your SSO needs differ from your Email import needs. However, unlike other Lookup definitions, you can only use one Form Population Lookup definition per form (one for Pre, and one for Pop is allowable).

Creating Pre and Post Population Lookup Definitions

To create a new Pre or Post Population Lookup Definition, click the plus symbol on the first line of your Dynamic Lookups Definitions page (accessed: System->Lookups menu->Lookups definition):

Each column heading corresponds with the following:

Description: This determines the name that shows up when applying the lookup on either the Edit Options->Lookups tab (shown above) or on the Edit Lookups mode of a particular form. Good practice dictates the definition type (Autocomplete, Dynamic Population, Form Population) as well as the what the unique ID used (Email, etc.)

Source object: This is the source of where your lookup data exists. If you are a customer where Altarama hosts your RefTracker instance, your Refracker Support Specialist should be able to direct you to someone who can create you custom source object data, with the data you need. Providing your RefTracker instance with your lookup data is explained here.
However, if you host your own instance of RefTracker, you may need to work with your IT department in order to set these source objects. They can be as simple as a database table, or a complicated database view, pulling from multiple data sources. Whatever best suits your needs for your particular organization.

Where clause: The where clause is literally the WHERE clause in the database SELECT statement that determines what value should be looked up on. This will not only be used for your lookups, but it’s also 
For the purposes of setting up your Pre Pop definitions, this field would identify first the name of the parameter you were looking up. In the case of using your network ID, your where clause could look like this: 
windowsAccount = ‘{$env_account}’.
For the purposes of Post Pop definitions, you’d want to specify the field you’d like to use to identify the user. In an email import environment, this would probably be the email field.
Refer to the proper documentation regarding SSO setup, and please consult your RefTracker Support Specialists should you have any questions. 

Type: This determines the Type of Lookup Definition you are creating. For the purposes of this exercise, we’re creating a Form population type definition.

Valid: You won’t be able to change this value, but it will quickly tell you if the Lookup definition is valid or not. Validity can be based off of not being able to find the Source object, or whether or not the fields mapped within this definition are 

Definition Icons: At the far right of each Lookup definition row, you’ll find three icons: Edit Lookup, Delete Lookup, and View Field Map.

• The Edit Lookup icon allows you to change Lookup definition details:

The Delete Lookup icon allows you to remove the Lookup definition altogether:

• The View Map Details icon is explained in further detail in the next section.

For example purposes, we’ve created a new Dynamic Lookup Definition. We are going to create a new definition, with the Description = Altarama Post Pop Email, the Source object = vRealPeople, the Where clause = email='{email}’ and Type = Form Population.

Setting The Data to Populate

This next section deals with the data that will be populated as a result of creating the Form Population type definition previously.

The fields available to you to use within your lookups are accessible with the View Map Details icon on the same row the Dynamic Lookup Definition is defined. When you click it, another table will display beneath your list of Dynamic Lookup Definitions. Below is a screen shot of an example:

The fields listed underneath the External datasource source column column heading represent the fields available to be imported. More specifically, they are the fields viewable in the Source object of the dynamic lookup definition (see previous section). Not all of these fields need to be used – however, when mapped to a field, the field must be valid. More on that later on in the page.

To map a RefTracker data dictionary field to one of the External datasource source columns, click the far-right icon of the intended row (Edit Mapping). You’ll then see a dropdown list of all valid data dictionary fields available to you within your system. This includes all data dictionary items, including custom data dictionary items you may create.

One important note you should consider is that Form Population type definitions require that all fields that will be needed be included – including the key field used. This differs from the Auto Complete and Dynamic Population options that don’t have this requirement. More on that on these pages. So, a simple way to remember it is, for a Form Population type, include all of the fields you’d expect to be populated.  

Testing Your Newly Created Lookup Definition

You won’t need to go to the form in order to test out if your lookup is populating correctly or not.

At the very bottom of this table is a section named: Test this lookup definition. You can use this to see if your lookup is valid or not. In the case of the example created above, we’ve created a Form Population type definition called Altarama Post Pop Form. In that, we’ve specified that we’re looking for the email field (review steps above, in setting the Where clause. We see this take effect in this testing process – other pertinent data is populating as expected as well. 

Putting Pre and Pop Forms into Use in your Workflow

Below are three practical uses / scenarios where you may want to implement a Pre / Pop Population definition for your forms:

Email Importing

A Post Population Dynamic Lookup definition is needed for this. Ideal for Email Importing, as the only identifiable key we can use is the email address. If that email address exists in the lookup, and the Where clause is set to look for the email address field matching what’s being imported, then it will work, and the fields will populate as the question gets imported.

Single Sign On

A Pre Population definition is needed for this. This would be to automatically populate details for a client upon loading the form. The client would have to exist in the data file provided to your RefTracker system, but this could eliminate the need for a known user to manually enter so many fields in order to properly identify themselves.

Data Collection Details

A Post Population definition is needed for this. This would be used if you did not want to populate a form with each form field you are trying to collect from the user; instead, you’d use only one field (email address, phone number – just something unique and identifiable) in your form. That would be the lookup field you can then use to lookup matching fields. 

Need More Help?

Feel free to reach out to your RefTracker Customer Support person for additional information or to answer any questions you may have.