Update docs for stu3 to r4

README.md

@@ -4,45 +4,45 @@ FHIR Converter is an open source project that enables conversion of health data
 
 The first version of the FHIR Converter released to open source on Mar 6th, 2020. It used Handlebars template language and Javascript runtime. A new converter engine was released on Nov 13, 2020 that uses Liquid templating language and .Net runtime.
 
-Currently, Microsoft supports two types of converter engines, Handlebars engine and Liquid engine, along with templates and filters. **We strongly recommend using the Liquid converter** for a better alignment with [Azure Healthcare APIs](https://docs.microsoft.com/azure/healthcare-apis/), [Azure API for FHIR](https://azure.microsoft.com/services/azure-api-for-fhir/), [FHIR Server for Azure](https://github.com/microsoft/fhir-server), and [Microsoft Logic Apps](https://azure.microsoft.com/services/logic-apps/).
+Currently, Microsoft supports two types of converter engines, Handlebars engine and Liquid engine, along with templates and filters. **We strongly recommend using the Liquid converter** for a better alignment with [Azure Healthcare APIs](https://docs.microsoft.com/azure/healthcare-apis/), [Azure Health Data Services](https://azure.microsoft.com/en-us/services/health-data-services/#overview), [FHIR Server for Azure](https://github.com/microsoft/fhir-server), and [Microsoft Logic Apps](https://azure.microsoft.com/services/logic-apps/).
 
 The following table shows the differences between two converter engines:
 
 |  | Handlebars engine | Liquid engine | 
 | ----- | ----- | ----- |
 | **Template language** | [Handlebars](https://handlebarsjs.com/) | [Liquid](https://shopify.github.io/liquid/) |
 | **Template authoring tool** | Self-hosted web-app | [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-health-fhir-converter)|
-| **Supported conversions** | 1. HL7v2 to FHIR <br> 2. C-CDA to FHIR | 1. HL7v2 to FHIR <br> 2. C-CDA to FHIR <br> 3. JSON to FHIR **(new!)** |
-| **Available as** | 1. Self-deployed web service <br> (on-prem or on Azure)| 1. Command line tool <br> 2. $convert-data operation in  [FHIR Server for Azure (OSS)](https://github.com/microsoft/fhir-server/blob/main/docs/ConvertDataOperation.md) <br> 3. $convert-data operation in both [Azure API for FHIR](https://docs.microsoft.com/azure/healthcare-apis/azure-api-for-fhir/convert-data) and [Azure Healthcare APIs (preview)](https://docs.microsoft.com/azure/healthcare-apis/fhir/convert-data)|
+| **Supported conversions** | 1. HL7v2 to FHIR <br> 2. C-CDA to FHIR | 1. HL7v2 to FHIR <br> 2. C-CDA to FHIR <br> 3. JSON to FHIR <br> 4. FHIR STU3 to FHIR R4 **(new Command Line Tool!)** |
+| **Available as** | 1. Self-deployed web service <br> (on-prem or on Azure)| 1. Command line tool <br> 2. $convert-data operation in  [FHIR Server for Azure (OSS)](https://github.com/microsoft/fhir-server/blob/main/docs/ConvertDataOperation.md) <br> 3. $convert-data operation in both [Azure Health Data Services](https://docs.microsoft.com/en-us/azure/healthcare-apis/fhir/convert-data) and [Azure API for FHIR](https://docs.microsoft.com/azure/healthcare-apis/azure-api-for-fhir/convert-data)|
 
 ⚠ Rest of this document is about the Liquid converter. For the Handlebars converter, please refer to the [Handlebars branch](https://github.com/microsoft/FHIR-Converter/tree/handlebars).
 
-Currently, FHIR Converter supports three types of conversions, **HL7v2 to FHIR**, **C-CDA to FHIR**, and **JSON to FHIR**. The converter uses templates that define mappings between these different data formats. The templates are written in [Liquid](https://shopify.github.io/liquid/) templating language and make use of custom [filters](docs/Filters-and-Tags.md).
+Currently, FHIR Converter supports four types of conversions, **HL7v2 to FHIR**, **C-CDA to FHIR**, **JSON to FHIR** and **FHIR STU3 to FHIR R4**. The converter uses templates that define mappings between these different data formats. The templates are written in [Liquid](https://shopify.github.io/liquid/) templating language and make use of custom [filters](docs/Filters-and-Tags.md).
 
 The converter comes with a few ready-to-use templates. If needed, you can create a new template, or modify existing templates to meet your specific conversion requirements.
 
-FHIR Converter with DotLiquid engine transforms the input data into FHIR bundles that are persisted to a FHIR server. The converter is integrated into both [Azure API for FHIR](https://docs.microsoft.com/azure/healthcare-apis/azure-api-for-fhir/) and [Azure Healthcare APIs (preview)](https://docs.microsoft.com/azure/healthcare-apis/), as well as in the open-source [FHIR Server](https://github.com/microsoft/fhir-server) as a [`$convert-data` operation](#using-convert-data-in-fhir-server). It is also available as a [command line tool](#using-command-line-tool).
+FHIR Converter with DotLiquid engine transforms the input data into FHIR bundles that are persisted to a FHIR server. The converter is integrated into both [Azure Health Data Services](https://azure.microsoft.com/en-us/services/health-data-services/#overview) and [Azure API for FHIR](https://docs.microsoft.com/azure/healthcare-apis/azure-api-for-fhir/), as well as in the open-source [FHIR Server](https://github.com/microsoft/fhir-server) as a [`$convert-data` operation](#using-convert-data-in-fhir-server). It is also available as a [command line tool](#using-command-line-tool).
 
 ## Using $convert-data in FHIR server
 
-The `$convert-data` operation is integrated into both Azure API for FHIR and FHIR server to run as part of the service. After enabling `$convert-data` in your server, you can make API calls in the form of ```<<your FHIR server URL>>/$convert-data``` to the server to convert your data into FHIR. In the API call request body, you would include parameters such as `inputData`, `inputDataType`, `templateCollectionReference`, and `rootTemplate`, to specify the message and the type of message you are converting. 
+The `$convert-data` operation is integrated into Azure Health Data Services, Azure API for FHIR and FHIR server to run as part of the service. After enabling `$convert-data` in your server, you can make API calls in the form of ```<<your FHIR server URL>>/$convert-data``` to the server to convert your data into FHIR. In the API call request body, you would include parameters such as `inputData`, `inputDataType`, `templateCollectionReference`, and `rootTemplate`, to specify the message and the type of message you are converting. 
 
 For more information on configuring and using `$convert-data` operation on your server, please refer to these documentation:
 
+- [$convert-data for Azure Health Data Services](https://docs.microsoft.com/en-us/azure/healthcare-apis/fhir/convert-data)
 - [$convert-data for Azure API for FHIR](https://docs.microsoft.com/azure/healthcare-apis/azure-api-for-fhir/convert-data)
-- [$convert-data for Azure Healthcare APIs](https://docs.microsoft.com/azure/healthcare-apis/fhir/convert-data)
 - [$convert-data for FHIR Server](https://github.com/microsoft/fhir-server/blob/main/docs/ConvertDataOperation.md)
 
 ## Using Command line tool
 
 ### Supported parameters
 
-The command line tool is another way of converting data, as well as managing templates. The tool converts a folder containing input messages (HL7v2, C-CDA, or JSON) into FHIR resources. It accepts the following parameters in the command line:
+The command line tool is another way of converting data, as well as managing templates. The tool converts a folder containing input messages (HL7v2, C-CDA, JSON or FHIR STU3) into FHIR R4 resources. It accepts the following parameters in the command line:
 
 | Option | Name | Optionality | Default | Description |
 | ----- | ----- | ----- |----- |----- |
 | -d | TemplateDirectory | Required | | Root directory of templates. |
-| -r | RootTemplate | Required | | Name of root template.<br><br> **HL7v2 to FHIR**: "ADT_A01", "ADT_A02", "ADT_A03", "ADT_A04", "ADT_A05", "ADT_A08", "ADT_A11",  "ADT_A13", "ADT_A14", "ADT_A15", "ADT_A16", "ADT_A25", "ADT_A26", "ADT_A27", "ADT_A28", "ADT_A29", "ADT_A31", "ADT_A47", "ADT_A60", "OML_O21", "ORU_R01", "ORM_O01", "VXU_V04", "SIU_S12", "SIU_S13", "SIU_S14", "SIU_S15", "SIU_S16", "SIU_S17", "SIU_S26", "MDM_T01", "MDM_T02" <br><br> **C-CDA to FHIR**: "CCD", "ConsultationNote", "DischargeSummary", "HistoryandPhysical", "OperativeNote", "ProcedureNote", "ProgressNote", "ReferralNote", "TransferSummary" <br><br> **JSON to FHIR**: "Stu3ChargeItem", "ExamplePatient" <br> (*These JSON templates are sample templates for use, not default templates that adhere to any pre-defined JSON message types. JSON does not have any standardized message types, unlike HL7v2 messages or C-CDA documents. Therefore, instead of "default" templates we provide you with some sample templates that you can use as a starting guide for you to modify and customize.*)  |
+| -r | RootTemplate | Required | | Name of root template.<br><br> **HL7v2 to FHIR**: "ADT_A01", "ADT_A02", "ADT_A03", "ADT_A04", "ADT_A05", "ADT_A08", "ADT_A11",  "ADT_A13", "ADT_A14", "ADT_A15", "ADT_A16", "ADT_A25", "ADT_A26", "ADT_A27", "ADT_A28", "ADT_A29", "ADT_A31", "ADT_A47", "ADT_A60", "OML_O21", "ORU_R01", "ORM_O01", "VXU_V04", "SIU_S12", "SIU_S13", "SIU_S14", "SIU_S15", "SIU_S16", "SIU_S17", "SIU_S26", "MDM_T01", "MDM_T02" <br><br> **C-CDA to FHIR**: "CCD", "ConsultationNote", "DischargeSummary", "HistoryandPhysical", "OperativeNote", "ProcedureNote", "ProgressNote", "ReferralNote", "TransferSummary" <br><br> **JSON to FHIR**: "Stu3ChargeItem", "ExamplePatient" <br> (*These JSON templates are sample templates for use, not default templates that adhere to any pre-defined JSON message types. JSON does not have any standardized message types, unlike HL7v2 messages or C-CDA documents. Therefore, instead of "default" templates we provide you with some sample templates that you can use as a starting guide for you to modify and customize.*) <br><br> **FHIR STU3 to R4**: Name of the root template that is the same as the STU3 resource name e.g., "Patient", "Observation", "Organization". Some of the STU3 resources are renamed or removed from R4. Please refer to [Resource differences and constraints for STU3 to R4](docs/Stu3R4-resources-differences.md). |
 | -c | InputDataContent | Optional| | Input data content. Specify OutputDataFile to get the results. |
 | -n | InputDataFile | Optional| | Input data file. Specify OutputDataFile to get the results. |
 | -f | OutputDataFile | Optional | | Output data file. |

docs/Filters-and-Tags.md

@@ -109,8 +109,76 @@ DateTime filters usage examples:
 
 ## Tags
 
-By default, Liquid provides a set of standard [tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#tags) to assist template creation. Besides these tags, FHIR Converter also provides some other tags that are useful in conversion, which are listed below. If these tags do not meet your needs, you can also write your own tags.
+By default, Liquid provides a set of standard [tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#tags) to assist in template creation. Besides these tags, FHIR Converter also provides some other tags useful in conversion, which are listed below. If these tags do not meet your needs, you can write your own tags.
 
 | Tag | Description | Syntax |
 |-|-|-|
 | evaluate | Evaluates an ID with an ID generation template and input data | `{% evaluate patientId using 'Utils/GenerateId' obj:msg.ClinicalDocument.recordTarget.patientRole -%}` |
+|mergeDiff|Merge diff JSON on input JSON data. The input data and difference in content should be a valid JSON format.| `{% mergeDiff msg -%}` <br> `<diff json>` <br> `{% endmergeDiff -%}`   |
+
+**Examples to use mergeDiff**
+
+**Add or update an item:**
+```
+{% mergeDiff msg -%}
+{
+    "added": "value"
+}
+{% endmergeDiff %}
+```
+
+**Remove an item:**
+```
+{% mergeDiff msg -%}
+{
+    "removed": ""
+}
+{% endmergeDiff %}
+```
+**Choice type item:**
+
+Using `[x]` to represent item with choice type. ( e.g. value[x] includes
+valueString, valueReference, valueInteger, etc. )
+The key in diff json can use `[x]` to simplfy the template.
+
+Here is a sample to remove choice type element for "value": 
+
+
+```
+{% mergeDiff msg -%}
+{
+    "value[x]" : ""
+}
+{% endmergeDiff %}
+```
+
+**Examples for STU3 input**
+
+Since FHIR resources are in JSON format and since the FHIR STU3 and R4 versions of resources have the same structure and share most datetypes, the mergeDiff tag can be widely used in FHIR STU3 to R4 conversion.
+
+Here is an example to convert ChargeItem resource from STU3 to R4 :
+
+
+ChargeItem.liquid：
+```
+{% mergeDiff msg -%}
+{
+  "definitionUri" : {{msg.definition | to_json_string | default : '""'}},
+  "performer" : [ {{ msg.participant | to_array | batch_render: 'ChargeItem/ChargeItemPerformer', 'msg' }} ],
+  "participant" : "",
+  "definition" : ""
+}
+{% endmergeDiff -%}
+```
+_ChargeItemPerformer.liquid:
+```
+{% mergeDiff msg -%}
+{
+  "function" : {{msg.role | to_json_string | default : '""'}},
+  "role" : ""
+}
+{% endmergeDiff -%}
+```
+In this sample, the field "definition" will be renamed to "definitionUri" and field "participant" will be renamed to "performer". All other other fields in the ChargeItem resource are copied as is from STU3 to R4. 
+
+

docs/Stu3R4-resources-differences.md

@@ -0,0 +1,65 @@
+# Resources Differences for STU3 to R4
+## Renamed Resources
+|STU3|R4|
+|--|--|
+|BodySite|BodyStructure|
+|EligibilityRequest|CoverageEligibilityRequest|
+|EligibilityResponse|CoverageEligibilityResponse|
+|Sequence|MolecularSequence|
+
+## STU3 Resources Removed from R4
+- DataElement 
+- DeviceComponent 
+- ExpansionProfile
+- ImagingManifest
+- ProcedureRequest
+- ProcessRequest
+- ProcessResponse
+- ReferralRequest
+- ServiceDefinition
+
+## Constraints with STU3 to R4 templates
+Note the following constraints in the default templates: 
+- Code System and Terminology URLs are copied as is 
+- Extension fields are copied as is
+- Cannot guarantee FHIR R4 cardinality constraints
+
+## New Resources Added to R4
+- BiologicallyDerivedProduct
+- CatalogEntry
+- ChargeItemDefinition
+- DeviceDefinition
+- EffectEvidenceSynthesis
+- EventDefinition
+- Evidence
+- EvidenceVariable
+- ExampleScenario
+- ImmunizationEvaluation
+- InsurancePlan
+- Invoice
+- MedicationKnowledge
+- MedicinalProduct
+- MedicinalProductAuthorization
+- MedicinalProductContraindication
+- MedicinalProductIndication	
+- MedicinalProductIngredient	
+- MedicinalProductInteraction	
+- MedicinalProductManufactured	
+- MedicinalProductPackaged	
+- MedicinalProductPharmaceutical	
+- MedicinalProductUndesirableEffect
+- ObservationDefinition
+- OrganizationAffiliation
+- ResearchDefinition	
+- ResearchElementDefinition
+- RiskEvidenceSynthesis
+- ServiceRequest
+- SpecimenDefinition
+- SubstanceNucleicAcid	
+- SubstancePolymer	
+- SubstanceProtein	
+- SubstanceReferenceInformation	
+- SubstanceSourceMaterial	
+- SubstanceSpecification
+- TerminologyCapabilities
+- VerificationResult