Using Key Function

Owned by Gunjan Tulwani (Unlicensed)
Last updated: Aug 25, 2015Version comment
3 min read

The Key function is used to extract information from two or more related input data sources. For example, if there are two input data sources: source1 andsource2, then the Key function will extract information from source2 based on the matching field from source1. 

Key function is always created in context of source2 (the data source from where data needs to be fetched based on matching field ). All the parameters of theKey function correspond to source2 only. It has the following 3 parameters:

  • Key Name : It is a name that you want to give to the Key function (for example, Key1))
  • Key Match : It is the XPath of source2 that will be returned as output by the Key function . This XPath is assumed to be present in the source2 . A valid Xpath needs to be specified as this path will be returned as output. A schema name cannot be used here in the Xpath.
  • Key Use: It is the name of the field from source2 which will be used to find the matching record from source2 based on the value passed to Keyfunction. For example, if the Key Match is /Root/Record and Key Use is EmpID, and if we pass value 25 to the Key function , then it will start scanningEmpID of the source2 inside each record of source2. Whenever EmpID=25, the Key function will pass that record (Root/Record) as output.


Once the Key function is created, you need to pass the value to the Key function that will be used to match the Key Use defined for source2 and map the output to the target element. For this, you need to use the Key mapping function. The syntax of the Key Mapping is :
key( , ) 
This function accepts 2 parameters. The first parameter is the name of the Key function (Key1) to be used and the second parameter is the actual value that will be passed to the Key function to perform the match on source2. The parameters will be: 
key( 'key1', 25 ) 
Once XSLT transformer finds a mapping it will call the Key function Key1 and pass the value 25 to that function. The Key function Key1 on receiving the mapping will pick this value 25 and start scanning EmpID of the source2 inside each record of source2. Whenever EmpID= 25, the Key function will pass that record (Root/Record) as output. 
The Key function always executes inside current context or nearest For Each that is applied to the target element where Key function is mapped. So if the For Each is applied is for source2 on the target element, then the Key function will use source2 as the data source on which EmpID scanning will be performed . So the For Each applied, helps the Key function to decide which data source to use, to perform the scanning and fetch the output. 
  Usage Scenario
For example, there are two source schemas: Schema_EmpDetails and Schema_Emp_incrementalDetails. There is one target schema: Schema_EmpCompleteDetails. The objective is to map the fields EmpName, EmpID ,Age, Salary, City and Email from Schema_EmpDetails and map the field Address from Schema_Emp_incrementalDetails to the target schema. The Address from the Schema_Emp_incrementalDetails is fetched using Key function and using EmpID as Key Use. 
The parameters are defined as:

  • Key Name: Key1
  • Key Match: /Root/Record
  • Key Use: EmpID


The first For Each is applied from record of first Schema on target Record node. This will insure that target data will contain as many records as there are inSchema_EmpDetails. Now Key mapping is used on the target Address element. So the deciding For Each ($Input_Schema_Emp_incrementalDetails/Root) forKey function is applied on this element. The For Each applied here is up to Root element only not Record so that only single Address target element is created per record . The Key mapping is defined as: 
key( 'key1',$_varEmpID )/Address 
Local variable _varEmpID is used as second parameter which is dynamically picking value from the EmpID of the first schema (due to For Each applied on target Record node). Once the Key function finds the match, it will return the matching record Root/Record from the second schema. Since the Addresselement is inside the Record element, /Address is appended to the Key mapping, which becomes Root/Record/Address. 
Using key function involves: