Use Key function to group source Header & Details

Mapper's Key function helps aggregate or group related Header and details records.

Need for this function arises when we have two separate source files. A header record in the Header file has related multiple data records in the Details file. Thus we want to group all related Source header and detail records based on a common key.

Assume there are two input data sources source1 and source2 respectively.

Key function is used to extract information from 2 or more related input data sources. e.g, extracting information from source2 based on the matching field from source1.
Key function is always created in context of source2 (data source from where data needs to be fetched based on matching field ). All the parameters of key function corresponds to source2 only.

Key function has following 3 parameters:

1. Key Name : It is a name that you want to give to your key function (say KeySSN)

2. Key Match : It is the xPath of source 2 that will be returned as output by the key function .What ever xPath you provide here ,xslt Key function will assume that this path is present in the source 2 . We can only provide valid xPath here as this is the path that will be returned as output so we can't use schema name here in the xPath.

3. Key Use: It is the name of the field from source2 which will be used to find the matching record from source 2 based on the value passed to key function. e.g. if the Key Match is /Root/Record and Key Use is EmpSSN and we pass value 25 to the Key function , then key function will start scanning EmpSSN of the source 2 inside each record of source 2. When ever EmpSSN= 25, key function will pass that record (Root/Record) as output.

Once the Key function is created using above point 1,2,3 , the next step is 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 we need to use Key mapping (under Aggregation -> Key of the Data Mapper functions ).

The Syntax of the Key Mapping is :

key( , ) This function accepts 2 parameters. The first parameter is the name of the Key function (created using point 1,2,3 above) 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.

Lets say we provide following parameters to the key function : key( 'keySSN',25 )

Once XSLT transformer finds this mapping it will call the Key function KeySSN (created in point 1,2,3 above) and pass the value 25 to that function. The Key function KeySSN on recieving the mapping will pick this value 25 and start scanning EmpSSN of the source2 inside each record of source 2. When ever EmpSSN= 25 key function will pass that record (Root/Record) as output.

The important thing to understand here is how Key function decides which data source to use to perform the scanning and fetch the output from ? The Key function always executes inside current context or you can say 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 Key function will use source2 as the data source on which EmpSSN scanning will be performed . So the For-each applied is the deciding factor for the Key function.

Refer to attachment on how to use this function with an example