Getting Started (My "Notes")

[granadacoder]

Wow.

This took a bit to try and figure out the "basics".

So I thought I'd share.

Documentation:

Getting a list of the templateCollections:

az acr repository list --name healthplatformregistry.azurecr.io --output table

(COMMENT (it is public, so empty-string is ok for username and pwd if prompted))

Username: 
Password: 

(and results below)

Result

--------------------------------------

ccdadefaulttemplates
ccdasampledata
fhir-analytics-data-source
fhirconverter
fhirtodatalake
fhirtodatalaketool
growth-chart-app
hardwareinfo
health-paas-codespaces
healthdatatodatalaketool
hl7v2
hl7v2defaulttemplates
hl7v2sampledata
jsondefaulttemplates
jsonsampledata
medications-app
public/healthcareapis/r4-fhir-server
public/healthcareapis/r4b-fhir-server
public/healthcareapis/r5-fhir-server
public/healthcareapis/stu3-fhir-server
r4_fhir-server
r4b_fhir-server
r5_fhir-server
samples/counter-image
stu3_fhir-server
stu3sampledata
stu3tor4defaulttemplates
wordclouddata

(pick one of the above for the --repository argument below)

az acr repository show-tags --name healthplatformregistry.azurecr.io  --repository ccdadefaulttemplates --orderby time_desc --output table

(and results below)

Result
--------
v5.1
v5.0
v4.5
v4.4
v4.3
v4.1
v4.0

...

Using the templateCollections

Note, anywhere below where there is a path or filename location specified with

"./"

You may need to put in the full-path or full-file-name.

Prerequisite: You must create an azure-container-registry..which is referred to as "mycustomacr123.azurecr.io" below.

Ok, first, what "works" using Microsoft default templates:

(all the command line argumenst below are used with Microsoft.Health.Fhir.Liquid.Converter.Tool.exe)

#(1 command line execution)

pull healthplatformregistry.azurecr.io/hl7v2defaulttemplates:v5.1 ./zzzMicrosoftTemplatesFromPull/ -ftrue

(1 result)
all of the liquid templates are downloaded to my local folder ./zzzMicrosoftTemplatesFromPull/
one noteworthy mention the below file "exists":

./zzzMicrosoftTemplatesFromPull/metadata.json

(2 command line execution)
note, the ADT-A01-01.hl7 file below is an example (sample) from this repo's source code

convert -n/data/SampleData/Hl7v2/ADT-A01-01.hl7 -d./zzzMicrosoftTemplatesFromPull/  -rADT_A01 -f./zzzOutputFolder/MyOutputFileOne.txt

(2 result)
the file './zzzOutputFolder/MyOutputFileOne.txt' is successfully created and --contains-- a FHIR (resource) BUNDLE.
The contents of the output file is a "wrapper", where the BUNDLE" is nested under "FhirResource": json element.
(This below wrapper is defined here: https://github.com/microsoft/FHIR-Converter/blob/main/src/Microsoft.Health.Fhir.Liquid.Converter.Tool/Models/ConverterResult.cs#L11L22 )

The contents of the transformation are quite large, and not pasted here.

But I will paste the START of the result so you can see the "FhirResource": json element and the nested Bundle.

{
  "Status": "OK",
  "FhirResource": {
  "resourceType": "Bundle",
  "type": "batch",
  "timestamp": "1989-08-18T11:26:00+02:15",
  "identifier": {
    "value": "MSG00001"
  },
  "id": "513a3d06-5e87-6fbc-ad1b-170ab430499f",
  "entry": [
    {
      "fullUrl": "urn:uuid:b4ca189b-51ae-33df-cbe2-559b4423a321",
      "resource": {
        "resourceType": "MessageHeader",
        "id": "b4ca189b-51ae-33df-cbe2-559b4423a321",
        "source": {
          "name": "24GHH",

==========

Now using a custom defined template.

I have a folder below:
./zzzMyFirstTemplatesSource/

and a custom liquid template:

./zzzMyFirstTemplatesSource/MyFirstTemplateEmployeeToR4Patient.liquid

below is the contents of the above file: (note, this is a template I created, but I "learned" from a file in the repo : ./data/Templates/Json/ExamplePatient.liquid )

note the "msg." prefix. it is not "content" like many examples. this comes from here : https://github.com/microsoft/FHIR-Converter/blob/main/src/Microsoft.Health.Fhir.Liquid.Converter/Processors/BaseProcessor.cs#L28

This "msg." prefix threw me for a loop for most of a day (before I found ExamplePatient.liquid)

{
    "resourceType": "Patient",
    "id": "{{ msg.EmployeeKey | to_json_string | generate_uuid }}",
    "identifier": [
        {
            "use": "usual",
            "system": "gyms.r.us.national.registry",
            "value": "{{ msg.GymMembershipNumber }}"
        }
    ],
    "active": true,
    "name": [
        {
            "family": "{{ msg.LastName }}",
            "given": [
                "{{ msg.FirstName }}"
            ]
        }
    ],
    "telecom": [
        {% comment -%} use "[]" to access value if the key contains spaces or other special characters {% endcomment -%}
        {% for p in msg["Phone Number"] -%}
        {
            "system": "phone",
            "value": "{{ p }}",
            },
        {% endfor -%}
    ],
    "gender":   
        {% if msg.Gender == 'M' -%}
	        "male",
        {% elsif msg.Gender == 'F' -%}
	        "female",
        {% elsif msg.Gender == 'U' -%}
	        "unknown",
        {% elsif code -%}
	        "other",
        {% else %}
            "",
        {% endif -%}
    "birthDate": "{{ msg.DOB | add_hyphens_date }}"
}

And I added the file: (this is a mandatory file)

./zzzMyFirstTemplatesSource/metadata.json

with the context below:

{
	"type": "json"
}

Ok, now I run the Microsoft.Health.Fhir.Liquid.Converter.Tool.exe with the arguments (for future readers, note, you have to do an "az login" and a "az acr login --name mycustomacr123.azurecr.io" before doing the below)

push mycustomacr123.azurecr.io/templatetest:default ./zzzMyFirstTemplatesSource/ -ntrue

Ok, the above "works" and I get this output:

Digest: sha256:000000000000000000000000000000000000000000000000000000000000000
Successfully pushed artifacts to mycustomacr123.azurecr.io/templatetest:default

I also notice that the below file was created:

./zzzMyFirstTemplatesSource/.image/layers/layer1.tar.gz

Ok, great.

Now I try a pull : so execute "Microsoft.Health.Fhir.Liquid.Converter.Tool.exe" with below arguments

(the same az command (as above) have to be run before the below : "az login" and a "az acr login --name mycustomacr123.azurecr.io" before doing the below)

pull mycustomacr123.azurecr.io/templatetest:default ./zzzMyFirstTemplatesFromPull/ -ftrue

and that works with below output

Digest: sha256:000000000000000000000000000000000000000000000000000000000000000
Successfully pulled artifacts to ./zzzMyFirstTemplatesFromPull/ folder

Note, the directories/files of the above operation:

./MyFirstTemplateEmployeeToR4Patient.liquid
./.DS_Store
./metadata.json
./.image
./.image/.DS_Store
./.image/layers/layer1.tar.gz
./.image/meta.info
./.image/base/layer1.tar.gz

Note, the file "./MyFirstTemplateEmployeeToR4Patient.liquid"

Ok, now try to run a transformation.

Here is a sample .json input file... I am using "employee" as a "something NOT FHIR related" example.
the "input-data" file name :

./zzzSampleInputData/EmployeeInputDataExample.json

and below is the contents of the above json file:

{
  "EmployeeKey": "EmpKey123456789",
  "LastName": "Somebody",
  "FirstName": "Mary",
  "GymMembershipNumber": "Y0M1C2A3",
  "Gender": "F",
  "DOB": "20011231",
  "Phone Number": ["703-555-1234", "540-555-2345"]
}

and now execute "Microsoft.Health.Fhir.Liquid.Converter.Tool.exe" with below arguments arguments:

note, do NOT use ".liquid" after the template name of "MyFirstTemplateEmployeeToR4Patient" below

convert -n./zzzSampleInputData/EmployeeInputDataExample.json -d./zzzMyFirstTemplatesFromPull/ -rMyFirstTemplateEmployeeToR4Patient.liquid -f./zzzOutputFolder/MyCustomOutputFileEmployeeToR4Patient.txt

Note the format of the output (aka, the contents of MyCustomOutputFileEmployeeToR4Patient.txt):

It is a "wrapper", where the R4-Patient is nested under "FhirResource": json element.
(This below wrapper is defined here: https://github.com/microsoft/FHIR-Converter/blob/main/src/Microsoft.Health.Fhir.Liquid.Converter.Tool/Models/ConverterResult.cs#L11L22 )

{
  "Status": "OK",
  "FhirResource": {
  "resourceType": "Patient",
  "id": "53856e08-1b01-f9aa-dd53-a035cedf85a0",
  "identifier": [
    {
      "use": "usual",
      "system": "gyms.r.us.national.registry",
      "value": "Y0M1C2A3"
    }
  ],
  "active": true,
  "name": [
    {
      "family": "Somebody",
      "given": [
        "Mary"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "703-555-1234"
    },
    {
      "system": "phone",
      "value": "540-555-2345"
    }
  ],
  "gender": "female",
  "birthDate": "2001-12-31"
}
}

I hope that helps someone. I hit 2-3 curve balls trying to get the basics to work.