Summary of steps you will need to undertake (relevant to programmers and DBA’s)

The steps are:

  • Design your Request form to look how you want it to look for the end user, as you normally would design a Request form using System>Request forms. This means that you need to include all of the fields that are required to successfully elicit the details of the question from the client, and obtain statistics for this type of request. But for forms that will use Lookups, you also need to ensure that you include all of the fields required to obtain and save data from the Lookups. Normally Lookups are used to ensure that information in RefTracker is compliant with other systems in your organisation so you may also need to ensure that fields required for subsequent transfer of information from RefTracker to your other systems using Statistical reports or Data export are also included. Fields required for interfacing can be, and often are, Hidden.
  • Decide what fields in your form will be used for Lookups and exactly what data needs to be retrieved by each of those Lookups. A spreadsheet showing the data relationships might be helpful! For each required Lookup, the table or spreadsheet should define the data that will be used to obtain the Lookup information (e.g. a RefTracker field like Client name, or system information like the Windows logged on user), the data source that needs to be looked up using that information, and the fields that need to be retrieved from that data source by the Lookup. The information you define here will be used in the next steps.
    For Post population, Autocomplete and Dynamic population, something that the client enters into the form, such as their name or email address, will be the key that is used for the Lookup.  But in the case of a Pre-population the key will need to be an environmental variable that can be accessed by the Pre-population lookup.
    One way to do this (relevant to in-house installed RefTracker systems only) is to set Anonymous access off for the RefTracker web. Then set the where clause to
    windowsAccount = ‘{$env_authuser}’
    There are four network variables supported to account for different network setups:  $env_authuser  $env_remoteuser  $env_logonuser  $env_remoteaddr
    Here’s an example of such a Pre-population setup in the Lookup definitions screen, and its associated field mappings showing how windowsAccount is used as the key for the lookup to its associated data source where the client contact details will be obtained based on the network logon:
  • Programmer or DBA defines the access criteria for the data source that the Lookup information needs to be retrieved from (SQL or SOAP compliant local Web service), using System>Lookups menu>External datasources, if it has not already been defined. You can define as many external data sources from which information will be retrieved as you need. Your IT department is best placed to do this setup.
  • Programmer or DBA defines a Lookup function that specifies the data that will be retrieved from adata source. A Lookup definition defines the SQL query or the Web Service that will be used to retrieve data from the external data source, the fields that will be retrieved from the data source using that query, and how those fields are mapped to RefTracker fields. In other words, the Lookup defines the data that will be retrieved, and where that data should be stored in RefTracker. You can define as many Lookups as you need, however the same Lookup will often be used in multiple forms. A Lookup should define all of the relevant data that can be retrieved for this type of Lookup, as not all of the retrieved data has to be saved in the RefTracker Request form each time this Lookup is used. You will also need help from your IT department to do this setup.
    Where you will use SQL for your lookups, you will define the lookup/s using System>Lookup menu>Lookup definitions. The SQL you define can use Views set up specifically for the use of RefTracker.Where you will use a locally provided Web service for your lookups, you will define the lookup using System>Lookup menu>Lookup definitions and System>Lookup menu>Lookup token. Further, your programmer will have to provide a local web service that RefTracker can call to obtain the required data. Your local web service needs to deliver the information from your data source in the format defined by the RefTracker Web service schema for your RefTracker system (see later information about how to obtain this schema).
  • Programmer or DBA creates code maps for each retrieved data field that needs to be saved into a RefTracker code table, if any. The way in which the data is stored in your external data source may not match how it is stored in the RefTracker code table so when external data is to be saved into a RefTracker code table, a code mapping must be provided. The need for code maps should be minimal.
  • Programmer or DBA uses System>Request forms>Edit options and the Lookup tab to specify the Lookup definitions that will be automatically run on initial display (Pre-population) and/or on submission (Post-population), if any. If there are any fields retrieved by these Lookups (as defined in the appropriate Lookup definition) that you want saved in questions created using this form, make sure that these fields have been defined in your Request form layout.
  • Programmer or DBA then uses the Edit lookups function to define how the Autocomplete and Dynamic population lookup data will be mapped to the fields in your Request form. If there are any fields retrieved by these Lookups (as defined in the appropriate Lookup definition) that you want saved in questions created using this form, make sure that these fields have been defined in your Request form layout.
  • Then test your form! 


When you use a form that has been defined with Lookup fields, the data retrieved as a result of the Lookup, will be loaded into the fields of the form that you have defined in the Lookup definition, at the time that you define. In all other respects forms work as they normally do so you can still do things like passing data into the form via URL string parameters with URL string parameters overriding anything designed into the form or brought in through a Pre-population lookup, but auto completes, dynamic populations and post-populations overriding anything that comes in through the URL string.

After clicking Submit, and after any Post-population lookups occur, all of the data currently in fields defined for that form will be saved in those fields as a new question in your RefTracker system.

Exercise 1

Designing your Request form is covered by the standard RefTracker documentation (see the System administration training – this can be done by your library staff). So, when you have a form looking how you want it to look for the users, it is time to think about the Lookups that you need to associate with it.

Exercise 2

Decide on the types of Lookups that you need to use for your form and the fields that they will be associated with.

Your IT person setting up these Lookups will want a description of the data fields that you want retrieved, and from where, for each Lookup.

A spreadsheet showing the data relationships might be helpful. For each required Lookup, the spreadsheet could define the data that will be used to obtain the Lookup information (e.g. a RefTracker field like Client name, or system information like the Windows logged on user), the data source that needs to be looked up using that information, the type of lookup required e.g. Autocomplete, and the fields that need to be retrieved from that data source by that Lookup. The information you define here will be used by your IT person in the next steps.

So with that information in hand, let’s look at the steps involved in setting up Lookups for use in your Request form, in detail.