Getting Started

Anyone is welcome to extending the itk-payloads code to incorporate other payloads, or to alter the way it works to fit their own needs. I would be keen to incorporate any additional code into the main codestream, and will of course properly attribute changes to the author. For details about how to use the “pull request” feature in bitbucket have a look at this article.
If you don’t want to create a fork you can simply clone the repo using the git clone command:

git clone https://bitbucket.org/itk/itk-payloads.git

How it works

The classes representing the payload objects, as well as the enumerations used for vocabularies are generated from XML configuration files. To create a new CDA document, values can then be populated into the generated classes, either directly or using helper classes. The helper classes make some assumptions about certain aspects of the content (e.g. that user IDs will be SDS IDs rather than local IDs, etc) in order to simplify things as much as possible. The helper classes return populated payload objects, which can also be populated directly if additional flexibility is required.

Finding your way around the code

Once you have a local copy of the code, there are a few key files it is worth reviewing so you are familiar with how they work:

Configuration

• src/main/resources/config.properties : This is the main configuration file. It is used to configure the paths for the code generation steps, including the payload classes as well as the vocabulary enumerations.
• src/main/resources/config : This is the main configuration for the payloads. These XML files are used to drive all the code generation.
• src/main/resources/codegeneratortransforms : This is where the xslt templates used to generate the code are. If all you are doing is adding new payloads you should not need to change these.
• Vocabulary Config: NOTE: The vocabulary XML definitions are published by the HSCIC messaging team, and can be found on TRUD within the NHS Message Specifications Reference Pack . This should be downloaded, and the paths for the vocabs configured in the config.properties file.
• Schemas: Some of the unit tests rely on the schemas for the relevant payloads. These are included within the domain message specifications for each payload, and cannot be distributed with the itk-payloads library unfortunately. Please download the relevant DMS from TRUD and configure the paths for the schemas within the config.properties file.

Code Generators

• src/main/java/uk/nhs/interoperability/payloads/util/GenerateDomainObjects : This is the class used to generate the payload objects. If you have updated the payload configuration, or added a new payload, run the main method in this class to regenerate the code for your new configuration.
• src/main/java/uk/nhs/interoperability/payloads/vocabularies/GenerateVocabularies : This is the class used to generate the vocabulary enumerations. If you have updated the vocab configuration, run the main method in this class to regenerate the enumerations.
• src/main/java/uk/nhs/interoperability/payloads/vocabularies/generated This package contains the generated vocabularies.
• src/main/java/uk/nhs/interoperability/payloads/templates : This package contains some of the generated payload objects – the ones for the CDA templates. Other payload objects are generated into the packages specified in the config.properties file.

Parsing and Serialising

• src/main/java/uk/nhs/interoperability/payloads/util/xml/PayloadParser : This is the main parser class. It makes use of handler classes in the util/fieldtypehandlers package to handle processing for specific field types. The standard SAX parser is used to minimise external dependencies.
• src/main/java/uk/nhs/interoperability/payloads/util/xml/PayloadSerialiser : This is the main serialiser class.

Unit tests

• src/test/java/uk/nhs/interoperability/payloads/helpers : This is where the unit tests for the helper classes are. The code in the unit tests gives a good indication of what can be done using the itk-payloads library. Other payloads all have unit tests also. Most unit tests include serialise tests for both minimal and typical payloads, a serialise test, and a round-trip test (which parses and then re-serialises a payload to check it matches the original).
• src/test/java/uk/nhs/interoperability/payloads/templates : Each template also has its own unit test. When adding new generated templates it is a good idea to also add unit tests to ensure they are correct. The CDA template library on TRUD has useful examples for many templates (although not all currently).
• src/test/java/uk/nhs/interoperability/AllTestsTestSuite : This is a unit test suite which runs all the other unit tests. When making any changes to the code it is a good idea to run this to make sure no errors have been introduced.

Build Scripts

• build.xml This is the main build script used to compile the code and create the itk-payloads.jar file. It also has a target to call runTests.xml which will execute the junit tests. The build-jar-dist target will create a date-stamped release build.

Click here for details on how to add a new payload

Home