Batch Link Table Build

This section describes how to generate the address link table using the batch tool provided in the Harmony package.

Steps to Build the Link Table

1. Prepare Input Data:

   • Ensure the required HELLO SOTs (Sources of Truth) are available under: $HARMONY_HOME/ROAD Examples include:

     • HELLO_CNAR

     • HELLO_NZAD

     • HELLO_CUSTOM/TUI

   • Confirm the PDP role is correctly configured in: scrubbing_pdp.xml

   • Define the link table build settings in: link_table.properties

2. Run the Batch Tool:

   • Navigate to the $HARMONY_HOME/tools directory in the Harmony package and run the build script

   • Run the appropriate script based on your operating system:

     • Windows:

     # Build the link table from the specified source and role to the destination directory
     build_linktable_nz.bat -from "HELLO_CUSTOM/TUI" -pdp-role "AddrTranslitNZADCNARRole" -to "C:\data\Harmony\tools\LINK_TABLE_NZ"

     • Linux:

     build_linktable_nz.sh -from "HELLO_CUSTOM/TUI" -pdp-role "AddrTranslitNZADCNARRole" -to "/data/Harmony/tools/LINK_TABLE_NZ"

3. Output:

   • The tool generates a consolidated link table that maps equivalent address records across the configured sources.

   • The output location is determined by the -to parameter in the command. For example:

     • C:\data\Harmony\tools\LINK_TABLE_NZ (Windows)

     • /data/Harmony/tools/LINK_TABLE_NZ (Linux)

Configuration

To build a link table that links source addresses from HELLO_CUSTOM/TUI with other sources such as HELLO_NZAD and HELLO_CNAR, you need to configure both the PDP group for the role and the link table properties.

scrubbing_pdp.xml

The link table build process uses PDP chains defined in $HARMONY_HOME/config/scrubbing/scrubbing_pdp.xml, based on the specified role name.

Example configuration:

  <msi:pdp-group msi:name="AddressTranslitNZADCNARGroup" msi:role="AddrTranslitNZADCNARRole" msi:model="ADDRESS_DATA" msi:locale="NEW_ZEALAND">
    <msi:pdp-name>AddressTransliteration</msi:pdp-name>
    <msi:pdp-name>NZADValidation</msi:pdp-name>
    <msi:pdp-name>CNARGeocode</msi:pdp-name>      
  </msi:pdp-group>

This configuration defines the PDP chain used to validate and link addresses across the specified sources.

Link Table Properties (link_table.properties)

The batch supports the following command line options:

• -from: the source name or the hello index location of the source. (e.g. HELLO_CUSTOM/TUI)

• -pdp-role: the pdp role to be used for process. (e.g. AddressTranslitNZADCNARGroup)

• -to: Output locaiton for the generated link table.

A sample link_table.properties file located in $HARMONY_HOME/tools might look like:

# The name of the link table
link_table.name=LINKTABLE_NZ

# The version of the link table
link_table.version=LINKTABLE_NZ_2025_05

# The expiration date of the link table in YYYY-MM-DD format
link_table.expire_date=2025-03-31

# The source name to be used to build the link table, e.g., "NZPAF"
# This can be overridden in the command line
link_table.source_name=

# The PDP role name to be used to build the link table.
# This can be overridden in the command line
link_table.role=

# The number of threads to use for the link table build, default is 4 if not set
link_table.thread_count=

Additional Notes

• This configuration is tailored for the NZ locale, supporting sources such as NZPAF, NZAD, CNAR, and CUSTOM.

• These sources can be used either as the -from source or as part of the PDP validation chain.

• In the generated link table

  • link_message is populated based on the MatchedRule.

  • link_type reflects the rule type used, with possible values: EXACT, MPP, STREET_RANGE, TBC (To Be Confirmed).

  • target_id and source_id may be:

    • DPID (for NZPAF, NZAD)

    • Hash ID (if available)

    • CNAR ID (if no hash ID)

    • Custom ID (if no hash ID)

  • record_type (e.g., rooftop, single) for target/source are not yet populated.

Support and Assistance

If you encounter any issues or have questions about building the link table, feel free to reach out to our support team at [email protected].

⚠️ Important: To enable the use of the link table within the HRA address lookup, you must request access to the required access.dat.key file. When making the request, include the link_table.name you defined in the properties file.

This key is essential for activating link table functionality in HRA and must be obtained through Customer Support.