Setting up for Web service access (notes for the programmer)

To enable these Lookups functions to operate, the Programmer providing your local web service to access the external data source will need to code a SOAP compliant web service interface that provides data in the format specified by the Schema provided by your RefTracker system. The schema will be different for each RefTracker system in order to ensure that it meshes with how your RefTracker system is set up.

Within that local web service, and utilising that schema, the programmer will be able to define lookups that return different types of data, by associating a different “token” with each different lookup. For example one lookup might bring back a list of client email addresses for an autocomplete function and be assigned a token of “EmailLookup”, another might bring back all the client contact details for the email address selected using the “EmailLookup” autocomplete and be assigned a token of “ContactDetails”.

Obtaining the Schema for your RefTracker system

The Schema that must be used by your local web service to send data to RefTracker via the Dynamic Lookups Native web service method can be obtained by using the following web services:

– To return XMLschema object (most commonly used in Microsoft environments as it returns System.Xml.Schema.XmlSchemaObject Member of System.Xml.Schema) =

<ReftrackerDomain>/exchange/api.asmx/RefTrackerXSD

– To return XMLschema in string format –

<ReftrackerDomain>/exchange/api.asmx/RefTrackerSchema

– The schema definition includes the definitions for all of the fields in the following RefTracker tables =

  • Question
  • Client
  • BIB
  • ILL

The documentation for each field (element) includes the actual RefTracker field name (such as question_useful_date as shown in the following example)

Any Lookup fields will include all possible lookup values formatted as Lookup Value = Description *(default)

How does this Schema relate to the Request form that will use it?

The RefTracker Dynamic Lookup Native web service schema defines how the data you are providing relates to the fields that have been used in the Request form that uses your lookup.

Each field (element) defined in the Schema relates to the field in the RefTracker data dictionary that uses the same name. The System>Data dictionary>Question tables>Question screen shown below shows the RefTracker data dictionary field for the last useful date.

The column Column/Variable name shows the name used for the field in the RefTracker Schema.

The column Label shows the common name by which this field is known, which is the name used to refer to it in the RefTracker form design.

So what this means is that if you include data in an element of your XML response, the Column/Variable name for that element will be saved to the field with the corresponding Label, as used in the Request form that this Lookup is being used in. So data in the question_useful_date field will be mapped to the Last useful date field in the Request form that this lookup is used in, if the Last useful date field has been used in that form.

The XML record that you return should provide data (elements) for every field in the Request form it will be used with, for which that type of lookup will supply data. It can supply more data than is used for a specific Request form (which might allow you to create one generic lookup that is used in Request forms with slightly different data fields needing to be populated by the lookup).

Note that if you select a RefTracker code list (code table) as defined in the Column Type, as the field that data is being passed into by your XML response, you will also need to create a code map for that field (see a later section of this document about Code maps). Code maps are required because the data coming from the source Data source may well be different to the code table data held in RefTracker for that field (for example, a “3” in the source data source may equate to “Accounts” in your RefTracker Department code table).

The number of fields that are mapped to code list field (code tables) should be minimal – the most common need for a code table map is where data needs to be mapped to either the Staff or Client location fields. Code tables are used in RefTracker to ensure data is stored in a consistent fashion so that it can be easily converted to statistics. When data comes from an external data source using the lookups functionality, it will be provided in a consistent manner by the external data source, so it can be stored as text in text boxes or text areas and still be easily analysed for statistics – there is no need to store it in a code table just to ensure data uniformity.

Set a web service Lookup token

Use the LookupToken code table to allow the tokens that you will use in your local web service to specify the different types of data being sent to RefTracker as a result of a SOAP compliant request from RefTracker.  The Token values are included in the SOAP compliant request from the Dynamic Lookup Module Native web service calls, and in the XML data that your local web service returns, in order to indicate the type of lookup occurring.  The Lookup token is used in the Lookup definition (see the next step) to indicate what type of call is being made and therefore what data will be returned by your local web service.  You can create as many of these Tokens as you require to designate the different types of data being returned.

The Lookup token code table is found at System>Code tables menu>Other>Lookup token.  For example you may have a token “EmailLookup” that indicates that the data being sent back to RefTracker will be a list of email addresses that match the characters supplied by the RefTracker request, and you may have another called “ClientDetails”, for example, that is used to return all the contact details of a client based on the single email address provided in the RefTracker request.

Define your local web service


You need to provide a local web service that delivers the data requested by RefTracker in the format defined by the RefTracker schema.

RefTracker makes a SOAP call to your local web service and your local web service should return an XML record that contains XML items in a format that is compatible with the RefTracker schema.

The action (method) of your local web service that you write must be named ‘RefTrackerLookup‘

There are three values passed to your Local/external web service from RefTracker’s Native web service:

  • Type (string)
    • 0 – Validate
    • 100 – Dynamic Population (return one XML record compatible with the schema)
    • 200 – Auto complete list (return a list of values in XML format)
    • 300 – Form Population (return one XML record compatible with the schema)
    • Token (string)

The appropriate token from the ones you defined in the Lookup token code table

  • Searchterm (string)

This is the search term provided by RefTracker for which it needs data from the external Data Source returned. 

For a 200 (Auto complete list) request this might be any number of characters for which all values matching them should be returned (including null for which all values would be returned). For example, if this was used for an email address lookup and the characters supplied were “be” you would return all email addresses starting with “be”

For a 100 or 300 request the search term will be a unique data key for which a number of fields/data elements will be returned (as required to complete the lookup fields in the Request form it is being used with. For example, the search term might be beth@somewhere.com and the fields returned might be Phone number and Department.

Example Code for your local web service:

Sample XML Records that your web service will return back to RefTracker

Type 200 – Auto Complete List