Finalizing the Mapper

Mapper Finalization

Now that we have a mapper developed that can convert files from *-to-OHDF, we need to perform some final touches to make sure that our mapper works and can be integrated into OHDF Converters.

Using Regression Testing

Regression testing is extremely useful, as we make changes and improvements to mappers over time (for example, if we have new sample files or if the schema of a source format changes). Moreover, internal library changes, like an update to base-converter, or major dependency updates could change the behavior of a mapper significantly. If a particular change affects a mapping, we will need to regenerate the sample file through the following process:

First, we have to activate the regression testing suite that we created earlier to actually be able to automatically run and review your mapper.

1. Uncomment the lines in the {YOUR-SAMPLE-EXPORT}-hdf.json file. This will allow the regression tests to automatically generate an OHDF output file whenever you run the tests. These files are needed for the tests to check the output of your mappers. The commented out lines should look similar to the following:

// fs.writeFileSync(
//   'sample_jsons/SKELETON_mapper/SKELETON-hdf.json',
//   JSON.stringify(mapper.toHdf(), null, 2)
// );

2. Using the terminal, cd into the hdf-converters directory and run the following command. This command will run your mapper against the sample export file in sample_jsons and tests to see if the output is generated as expected. However, this initial run will be used to create a baseline OHDF file for manual inspection to validate that we wrote the mapper properly and thereafter will be the comparison target for future runs to confirm that no regressions in the mapping occurred.

yarn run test --verbose --silent=false ./test/mappers/forward/{YOUR-EXPORT-NAME-HERE}_mapper.spec.ts

3. After running this command, you should see two files named SKELETON-hdf.json and SKELETON-hdf-withraw.json appear in the sample_jsons/SKELETON_mapper/ directory. Check these files to make sure that the OHDF mapper output looks correct and aligns with your mapping. SKELETON-hdf.json should match your mapping completely, while SKELETON-hdf-withraw.json should also include your original source data in the OHDF output file.

4. Re-comment out the lines from step 1.

5. Future uses of the command in step 2 will now leverage the baseline files you generated to perform regression testing. It will compare the contents of these generated files with temporary outputs created by the mapper instance to check for field alignment. Review the test output to ensure that the tests are all passing.

Documentation

Document your new mapper in the README.md file for hdf-converters under the Supported Formats section. It should be formatted as follows:

{#}. [{YOUR-EXPORT-NAME-HERE}] - {MAPPER INPUT DESCRIPTION}

GitHub Merging

Commit your final changes and mark your pull request as 'ready for review'. You should request for a code review from members of the SAF team and edit your code as necessary. Once approved, your mapper will be merged into the main development branch and scheduled for release as an officially supported conversion format for OHDF Converters.