Code maps

When you have defined the details of your Lookup, it is time to create any code table mappings required as a result (the system will tell you when maps are required – which is whenever you have defined that data from the external data source should be saved into a RefTracker code table).

Code maps are required where data from an external data source is going to be used to select and entry from a RefTracker code table. The code mapping defines which RefTracker code table entry should be selected for each of the values that come across from the external data source.

Using external data to select a value from a code table is very effective if the data coming from the external table is numeric, or a short form, and in RefTracker you want your users to be able to see a textual description of what that code or short form means.

It might also be used to allow the data coming from the external data source to be saved in RefTracker using the values in a code table because the code table is used to represent that same data in other places in RefTracker where it is not obtained from the external data source – in other words, for consistency reasons.

Code tables are often used in RefTracker to ensure that data is stored in a consistent way so that statistics can be reliably generated. You do not need to use a code table for that purpose when data is coming from an external data source. When data comes from an external data source in this way, the external data source will ensure that it is delivered in a consistent fashion. For example, in RefTracker, you may have a “Client’s department” code table that shows just the departments in your organisation. If the “Client’s department” information is now to come from a lookup, we would advise that you save the “client’s department” information that comes from the external data source into a suitably named User defined text box field in RefTracker (created by going to System>Data dictionary menu then selecting the Client table). Text that gets saved into that field will be consistent and so suitable for statistical analysis, simply because it is controlled by the external data source. Of course you could use the Code mapping function described in this section to map the data to a RefTracker code table, and some organisations will do that, but if you do it, and a change is made to the values for “Client’s department” in your external data source, you will also have to make a corresponding change to the values in your RefTracker code table and create a mapping for the new value in System>Lookups menu>Code maps. So, unless you want to use the code table for consistency reasons, using a code table in this scenario will just create an unnecessary level of extra administration.

So, let’s take a look. Go back to the Lookups menu and choose Code Map to show the code maps that will be required to support the mapping of retrieved data into RefTracker code tables as defined in your Lookup definition details.

For the data source we have been working with, only one RefTracker code table has been used.

For your data source you may have mapped to any number of RefTracker code tables – such as the example below.

Clicking on the “edit” icon allows the External data source Source field to which this RefTracker code table is being mapped, to be changed.

RefTracker table is the RefTracker code table that has been detected as being used in the Lookup definition. Click on this column heading to sort the listed Code mappings by RefTracker table.

Source object is the field in the source data source that is providing the data to be mapped. Click on this column heading to sort the listed Code mappings by the Source object.

Valid lets you know if the source object is valid, and whether or not the fields are mapping correctly. Invalid objects will throw a validation error when displaying anything within the Lookups module.

Clicking on the Spy glass icon allows the mapping to be created. It does a Lookup of the source data file and returns the values in use so that they can be mapped. They are presented in order of the newest values added to the data source first, so that those new ones are obvious and can be easily mapped to the appropriate RefTracker code table value that should be stored when that value appears in the source file.

Each value in the Source object column should be mapped to a RefTracker code table value. New values are automatically mapped to the default value set in the code map (so make sure the default value is something you can easily notice and resent to the correct mapping – use a default value like *New value* ):

To edit a source file mapping, click on the Edit icon at the end of the line. The system will provide a drop down box showing all of the values in the RefTracker code table, so that you can choose the entry that will be saved into the RefTracker Request form when this source file value is retrieved.

It is possible to map multiple data source values to the same code table value.
Pagination of these code mappings max out at 20 records per page, and there are no limits to the size of the code tables.

If the record no longer exists in the data source, it is no longer viewable within a code mapping, and it’s mapping cannot be changed. Upon it’s return in the data source, the mapping will be retained, as long as the code table value is enabled. When a code mapping is no longer appearing in the source data AND it is no longer mapped to an enabled code table entry, that mapping will be automatically deleted, significantly reducing the size of the mappings table and so helping with the speed with which it can be maintained.  If you no longer need statistics about an entry in your Code table, Disable it and its Code table mapping/s will be automatically cleaned up.