{"id":18989971,"url":"https://github.com/cdcgov/cs-sdk-dotnet","last_synced_at":"2025-04-22T11:11:58.156Z","repository":{"id":40849714,"uuid":"418965756","full_name":"CDCgov/cs-sdk-dotnet","owner":"CDCgov","description":"SDK for working with case notification messages and message mapping guides","archived":false,"fork":false,"pushed_at":"2025-03-31T16:47:58.000Z","size":1396,"stargazers_count":2,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-17T00:14:43.367Z","etag":null,"topics":["csharp","dotnet","hl7v2","hl7v2-transformation","public-health"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CDCgov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-19T14:42:22.000Z","updated_at":"2025-03-31T16:48:02.000Z","dependencies_parsed_at":"2025-03-28T14:37:26.537Z","dependency_job_id":null,"html_url":"https://github.com/CDCgov/cs-sdk-dotnet","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2Fcs-sdk-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2Fcs-sdk-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2Fcs-sdk-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDCgov%2Fcs-sdk-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CDCgov","download_url":"https://codeload.github.com/CDCgov/cs-sdk-dotnet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250228640,"owners_count":21395958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnet","hl7v2","hl7v2-transformation","public-health"],"created_at":"2024-11-08T17:08:32.250Z","updated_at":"2025-04-22T11:11:58.104Z","avatar_url":"https://github.com/CDCgov.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Case Surveillance SDK for .NET\n\nThe `cs-sdk-dotnet` repository contains software functions for processing case-based surveillance data. All source code is written in C# and targets .NET Standard 2.1. Supported functions include:\n\n- Content validation for case notifications in the following file formats:\n    - Json\n    - HL7 v2.5.1\n- Data format converter:\n    - HL7 v2.5.1 to Json\n    - HL7 v2.5.1 to CSV\n- C# model objects for Message Mapping Guides (MMGs)\n- Debatcher for HL7 v2.5.1 batch files\n\n## Usage\n\n### Validation and Conversion\nUsing the validator and converter in .NET applications is straightforward:\n\n```csharp\n// create services for getting MMGs and vocabulary\nIVocabularyService vocabService = new InMemoryVocabularyService();\nIMmgService mmgService = new InMemoryMmgService();\n\n// an example (fake) HL7v2 message\nstring hl7v2message = @\"MSH|^~\\\u0026|SAN^2.16.840.1.1.nnnn^ISO|SF^2.16.840.1.1.nnnn^ISO|PHINCDS^2.16.840.1.1.4.3.2.10^ISO|PHIN^2.16.840.1.1^ISO|20141225120030.1234-0500||ORU^R01^ORU_R01|CONSYPH_V1_0_TM_TC06|T|2.5.1|||||||||NOTF_ORU_v3.0^PHINProfileID^2.16.840.1.1.4.10.3^ISO~Generic_MMG_V2.0^PHINMsgMapID^2.16.840.1.1.4.10.4^ISO~CongenitalSyphilis_MMG_V1.0^PHINMsgMapID^2.16.840.1.1.4.10.4^ISO\nPID|1||CONSYPH_TC06^^^SAN\u00262.16.840.1.1.nnnn\u0026ISO||~^^^^^^S||20130101|M||2054-5^Black or African American^CDCREC|^^^22^71292^^^^22073|||||||||||2186-5^Not Hispanic or Latino^CDCREC\nOBR|1||CONSYPH_TC06^SAN^2.16.840.1.1.nnnn^ISO|68991-9^Epidemiologic Information^LN|||20131031170100|||||||||||||||20131031170100|||F||||||10316^Syphilis, Congenital^NND\nOBX|1|CWE|78746-5^Country of Birth^LN||USA^United States^ISO3166_1||||||F\";\n\n// Convert the HL7v2 message to JSON\nIConverter converter = new HL7v2ToJsonConverter(vocabService, mmgService);\nConversionResult conversionResult = converter.Convert(hl7v2message);\n\n// Validate the JSON payload against the MMG\nIContentValidator validator = new JsonContentValidator(vocabService, mmgService);\nValidationResult validationResult = validator.ValidateMessage(json);\n```\n\n\u003e The `cs-sdk-dotnet` library requires dependency injection for the converter and validator. Doing so enables these functions to vary how they request MMGs and public health vocabulary. It also avoids hard-coding API calls or database access calls in the business logic. Downstream users of this SDK can then provide their own implementations.\n\n### Debatching\n\nThe HL7v2 debatcher is somewhat more complex in that it requires a callback function. The callback function is executed each time a message is debatched.\n\n```csharp\nIDebatchHandler handler = new StringDebatchHandler(DebatchCallback); // DebatchCallback() is executed for every message in the batch\nHL7v2Debatcher debatcher = new HL7v2Debatcher(); // create the debatcher\nDebatchResult result = debatcher.Debatch(batchmessage, handler, \"1234\"); // run the debatching operation\n```\n\nThe `StringDebatchHandler` might look like this, in simplest form:\n\n```csharp\npublic class StringDebatchHandler : IDebatchHandler\n{\n    private readonly ReadOnlySpanAction\u003cchar, MessageDebatchMetadata\u003e _callback;\n\n    public StringDebatchHandler(ReadOnlySpanAction\u003cchar, MessageDebatchMetadata\u003e callback)\n    {\n        _callback = callback;\n    }\n\n    public MessageHandleMetadata HandleDebatch(ReadOnlySpan\u003cchar\u003e hl7v2message, MessageDebatchMetadata metadata)\n    {\n        _callback(hl7v2message, metadata);\n        return default(MessageHandleMetadata);\n    }\n}\n```\n\nThe `DebatchCallback()` function might look like this:\n\n```csharp\nprivate static void DebatchCallback(ReadOnlySpan\u003cchar\u003e message, MessageDebatchMetadata metadata)\n{\n    string hl7v2message = message.ToString();\n    ConversionResult conversionResult = converter.Convert(hl7v2message, metadata.TransactionId);\n    ValidationResult validationResult = validator.Validate(conversionResult.Content, metadata.TransactionId);\n}\n```\n\n### Example processing pipeline\n\nA public health surveillance use case will likely require these functions to run in a defined sequence. For example, one could author an HL7 v2.5.1 pipeline that runs the functions in the following order:\n\n1. Debatch the HL7 v2.5.1 payload\n2. Convert HL7 v2.5.1 to Json (note that basic structural validation of HL7 v2.5.1 occurs by virtue of the conversion)\n3. Validate the content of the Json document per the Message Mapping Guide\n\nA basic C# pipeline implementation might look as follows:\n\n```cs\nprivate static void RunPipeline(string batchmessage)\n{\n    IDebatchHandler handler = new StringDebatchHandler(DebatchCallbackPipeline);\n    HL7v2Debatcher debatcher = new HL7v2Debatcher();\n    DebatchResult result = debatcher.Debatch(batchmessage, handler, \"1234\");\n\n    // persist the debatch results in a database\n}\n\nprivate static IConverter converter = new HL7v2ToJsonConverter();\nprivate static IContentValidator validator = new JsonContentValidator();\n\nprivate static void DebatchCallbackPipeline(ReadOnlySpan\u003cchar\u003e message, MessageDebatchMetadata metadata)\n{\n    string hl7v2message = message.ToString();\n    ConversionResult conversionResult = converter.Convert(hl7v2message, metadata.TransactionId);\n    ValidationResult validationResult = validator.Validate(conversionResult.Content, metadata.TransactionId);\n\n    // persist the conversion and validation results\n    // persist the converted Json\n}\n\npublic class StringDebatchHandler : IDebatchHandler\n{\n    private readonly ReadOnlySpanAction\u003cchar, MessageDebatchMetadata\u003e _callback;\n\n    public StringDebatchHandler(ReadOnlySpanAction\u003cchar, MessageDebatchMetadata\u003e callback)\n    {\n        _callback = callback;\n    }\n\n    public MessageHandleMetadata HandleDebatch(ReadOnlySpan\u003cchar\u003e hl7v2message, MessageDebatchMetadata metadata)\n    {\n        _callback(hl7v2message, metadata);\n        return default(MessageHandleMetadata);\n    }\n}\n```\n\nThe example pipeline code shown above will debatch 10,000 HL7v2 messages, convert them to Json, and then validate the Json in about 20 seconds. This is single-threaded performance, meaning a scale factor of 1, on 15W TDP Intel CPU.\n\n### HL7v2 to CSV converter\n\nThe SDK can optionally convert case surveillance messages in HL7v2 format to CSV format, where the CSV columns are the data elements in the message mapping guide:\n\n```cs\nIConverter converter = new HL7v2ToCsvConverter(new MmgCsvTemplateGenerator(), new HL7v2ToJsonConverter(), true);\nConversionResult result = converter.Convert(hl7v2message, \"1234\");\nstring csv = result.Content;\n```\n\nThis is an alternative to the SDK's conversion of HL7v2 messages to Json.\n\n## Disclaimer on Case Notification Data\n\nThis repository contains case notification data in various places, including in the [tests/](tests/) folder and in the README.md file. Such data are necessary to both verify the correct functionality of the software as well as provide documentation to users about how to use the software. These data are synthetically generated, representing fictional people and events only. Any similarity to real persons is unintentional.\n\nThe primary source of synthetic case notification data used in this repository is the CDC's publicly-available [Message Mapping Guides](https://ndc.services.cdc.gov/message-mapping-guides/) web page. Each MMG listed on that page contains a ZIP file consisting of a Test Message Package. This test message package contains a handful of synthetically generated, raw HL7v2 messages developed by the CDC that demonstrate how to correctly map every data element in the MMG to the HL7v2 format. In some cases, however, the authors of this library created their own synthetic case notifications or modified the CDC-authored test messages to test specific software functionality.\n\n## Public Domain Standard Notice\nThis repository constitutes a work of the United States Government and is not\nsubject to domestic copyright protection under 17 USC § 105. This repository is in\nthe public domain within the United States, and copyright and related rights in\nthe work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).\nAll contributions to this repository will be released under the CC0 dedication. By\nsubmitting a pull request you are agreeing to comply with this waiver of\ncopyright interest.\n\n## License Standard Notice\nThe repository utilizes code licensed under the terms of the Apache Software\nLicense and therefore is licensed under ASL v2 or later.\n\nThis source code in this repository is free: you can redistribute it and/or modify it under\nthe terms of the Apache Software License version 2, or (at your option) any\nlater version.\n\nThis source code in this repository is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the Apache Software License for more details.\n\nYou should have received a copy of the Apache Software License along with this\nprogram. If not, see http://www.apache.org/licenses/LICENSE-2.0.html\n\nThe source code forked from other open source projects will inherit its license.\n\n## Privacy Standard Notice\nThis repository contains only non-sensitive, publicly available data and\ninformation. All material and community participation is covered by the\n[Disclaimer](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md)\nand [Code of Conduct](https://github.com/CDCgov/template/blob/master/code-of-conduct.md).\nFor more information about CDC's privacy policy, please visit [http://www.cdc.gov/other/privacy.html](https://www.cdc.gov/other/privacy.html).\n\n## Contributing Standard Notice\nAnyone is encouraged to contribute to the repository by [forking](https://help.github.com/articles/fork-a-repo)\nand submitting a pull request. (If you are new to GitHub, you might start with a\n[basic tutorial](https://help.github.com/articles/set-up-git).) By contributing\nto this project, you grant a world-wide, royalty-free, perpetual, irrevocable,\nnon-exclusive, transferable license to all users under the terms of the\n[Apache Software License v2](https://www.apache.org/licenses/LICENSE-2.0.html) or\nlater.\n\nAll comments, messages, pull requests, and other submissions received through\nCDC including this GitHub page may be subject to applicable federal law, including but not limited to the Federal Records Act, and may be archived. Learn more at [https://www.cdc.gov/other/privacy.html](https://www.cdc.gov/other/privacy.html).\n\n## Records Management Standard Notice\nThis repository is not a source of government records, but is a copy to increase\ncollaboration and collaborative potential. All government records will be\npublished through the [CDC web site](https://www.cdc.gov).\n\n## Additional Standard Notices\nPlease refer to [CDC's Template Repository](https://github.com/CDCgov/template)\nfor more information about [contributing to this repository](https://github.com/CDCgov/template/blob/master/CONTRIBUTING.md),\n[public domain notices and disclaimers](https://github.com/CDCgov/template/blob/master/DISCLAIMER.md),\nand [code of conduct](https://github.com/CDCgov/template/blob/master/code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdcgov%2Fcs-sdk-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdcgov%2Fcs-sdk-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdcgov%2Fcs-sdk-dotnet/lists"}