Manual Steps For Testing Calculation of TX-PVLS and TX-CURR Indicators Using CQL-based Approach

These Steps are meant specifically for Testing Indicator Calculation using an Integrated CQL engine into the HAPI FHIR server.

See Automated Testing
For the complete Project setup,  see PLIR Local Installation

  1. Set Up the OpenMRS Hapi Fhir server Locally .
    use the Docker Compose file below to easily spin up a fully configured Hapi FHIR server Instance that has Support for  both the $collect-data  and $evaluate-measure FHIR operations

    docker-compose.yml
    version: "3"
    services:
      hapi-fhir-jpaserver-start:
        image: openmrsinfra/openmrs-hapi-fhir:openmrs-fhir-plir_cql
        container_name: hapi-fhir-cql
        restart: on-failure
        ports:
          - "8090:8080"

    Move to directory of the the above docker-compose.yml file and run 

    docker-compose up

    This will spin up an instance of the hapi fhir jpa server and should be accesible at http://localhost:8090/
    In order to acces the server end points . use the Basic Credentials below

    username : hapi
    password : hapi123
  2. Load a sample Testing Dataset with Observations , Patients and Encounters.
    For The purpose of this Testing , we will load/Post the sample Data set directly to the Hapi fhir Server.  Create a sample Dataset with Observations linked to these Concepts  .
    Alternatively you can use an already created Sample Observation Fhir Data For Testing TX-PVLS Indicator Calculation or the one for TX-CURR when calculating for TX-CURR indicator  . We can use a simple API client like Postman to Load the data into the hapi fhir server.
    Load the sample dataset into the POST Body for Postman and make a Post  request to the endpoint below 

    POST : http://localhost:8090/fhir
  3. Load the Required Libraries For the Calculation of TX_PVLS or TX-CURR .
    See FHIR CQL Libraries for the Calculation of TX_PVLS or FHIR CQL Libraries for TX-CURR. In Order to persist the Library Resource IDs into the Hapi FHIR server , we shall use PUT instead of POST.
    Note that we Load both the TX_PVLS LIbrary or TX_CURR  and FHIRHelpers Library into the HAPI Fhir server .

    i) Load the FHIRHelpers Library Resource into the PUT Body for Postman and send the PUT request to this end point below

    PUT: http://localhost:8090/fhir/Library/library-FHIRHelpers-4.0.1


    ii) Load TX_PVLS LIbrary Resource into the PUT Body for Postman and send the  PUT request to this end point below

     PUT : http://localhost:8090/fhir/Library/TX-PVLS or http://localhost:8090/fhir/Library/TX-CURR


  4. Load the TX-PVLS Measure resource  .
    see the FHIR Measure Resource For Calculation of TX_PVLS  or FHIR Measure Resource for calculating TX_CURR indicator . In order to persist the Resource ID , we shall use PUT instead of POST. 
    Load the TX-PVLS or TX-CURR resource into the PUT Body for Postman and send a PUT request to the endpoint below 

    PUT : http://localhost:8090/fhir/Measure/TX-PVLS or http://localhost:8090/fhir/Measure/TX-CURR


  5. Generating the Data set relevant for TX_PVLS/TX-CURR
    In order to generate the relevant dateset for the TX_PVLS or TX_CURR  Indicator , invoke the collect-data operation using the following request

    GET : http://localhost:8090/fhir/Measure/TX-PVLS/$collect-data?periodStart=2021-01-01&periodEnd=2021-12-31 or http://localhost:8090/fhir/Measure/TX-CURR/$collect-data?periodStart=2021-01-01&periodEnd=2021-12-31


    This should return a sample result-set like below 

     Sample Result set
    {
        "resourceType": "Parameters",
        "parameter": [
            {
                "name": "measureReport",
                "resource": {
                    "resourceType": "MeasureReport",
                    "status": "complete",
                    "type": "data-collection",
                    "measure": "Measure/TX_PVLS",
                    "evaluatedResource": [
                        {
                            "reference": "http://localhost:8090/fhir/Observation/5"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Observation/7"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Observation/8"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Observation/9"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Patient/9c5162a4-1cbb-4239-8813-da2d10be1ff4"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Patient/337679e5-aae4-4d95-8583-758e6551b953"
                        },
                        {
                            "reference": "http://localhost:8090/fhir/Patient/337679e5-aae4-4d95-8583-758e6551b9xx"
                        }
                    ]
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Observation",
                    "id": "5",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:52.968+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "laboratory",
                                    "display": "Laboratory"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "code": "1305AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                                "display": "HIV VIRAL LOAD, QUALITATIVE"
                            },
                            {
                                "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                                "code": "1305",
                                "display": "HIV VIRAL LOAD, QUALITATIVE"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/9c5162a4-1cbb-4239-8813-da2d10be1ff4",
                        "type": "Patient",
                        "display": "Obs_Test2 Obs_Test2 Obs_Test2 (OpenMRS ID: 10001V)"
                    },
                    "encounter": {
                        "reference": "Encounter/13cbf9b8-24fa-4806-8f2b-8e4f489b1f96",
                        "type": "Encounter"
                    },
                    "effectiveDateTime": "2021-01-26T08:12:28+00:00",
                    "issued": "2021-01-26T08:12:28.000+00:00",
                    "valueCodeableConcept": {
                        "coding": [
                            {
                                "code": "1306AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                                "display": "BEYOND DETECTABLE LIMIT"
                            },
                            {
                                "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                                "code": "1306",
                                "display": "BEYOND DETECTABLE LIMIT"
                            }
                        ]
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Observation",
                    "id": "7",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:52.968+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "laboratory",
                                    "display": "Laboratory"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "code": "856AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                                "display": "HIV viral load"
                            },
                            {
                                "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                                "code": "856",
                                "display": "HIV viral load"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/337679e5-aae4-4d95-8583-758e6551b953",
                        "type": "Patient",
                        "display": "Obs_Test1 Obs_Test1 Obs_Test1 (OpenMRS ID: 10000X)"
                    },
                    "encounter": {
                        "reference": "Encounter/4b91bc4f-9eef-4144-a88f-d8998ae932cf",
                        "type": "Encounter"
                    },
                    "effectiveDateTime": "2021-01-26T08:11:12+00:00",
                    "issued": "2021-01-26T08:11:12.000+00:00",
                    "valueQuantity": {
                        "value": 23
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Observation",
                    "id": "8",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:52.968+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "laboratory",
                                    "display": "Laboratory"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "code": "856AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                                "display": "HIV viral load"
                            },
                            {
                                "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                                "code": "856",
                                "display": "HIV viral load"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/337679e5-aae4-4d95-8583-758e6551b953",
                        "type": "Patient",
                        "display": "Obs_Test1 Obs_Test1 Obs_Test1 (OpenMRS ID: 10000X)"
                    },
                    "encounter": {
                        "reference": "Encounter/4b91bc4f-9eef-4144-a88f-d8998ae932cf",
                        "type": "Encounter"
                    },
                    "effectiveDateTime": "2021-01-26T08:11:12+00:00",
                    "issued": "2021-01-26T08:11:12.000+00:00",
                    "valueQuantity": {
                        "value": 23
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Observation",
                    "id": "9",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:52.968+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "laboratory",
                                    "display": "Laboratory"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "code": "856AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                                "display": "HIV viral load"
                            },
                            {
                                "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                                "code": "856",
                                "display": "HIV viral load"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/337679e5-aae4-4d95-8583-758e6551b9xx",
                        "type": "Patient",
                        "display": "Obs_Test1 Obs_Test1 Obs_Test1 (OpenMRS ID: 10000X)"
                    },
                    "encounter": {
                        "reference": "Encounter/4b91bc4f-9eef-4144-a88f-d8998ae932cf",
                        "type": "Encounter"
                    },
                    "effectiveDateTime": "2021-01-26T08:11:12+00:00",
                    "issued": "2021-01-26T08:11:12.000+00:00",
                    "valueQuantity": {
                        "value": 2000
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Patient",
                    "id": "9c5162a4-1cbb-4239-8813-da2d10be1ff4",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:53.514+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "text": {
                        "status": "generated",
                        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody/></table></div>"
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Patient",
                    "id": "337679e5-aae4-4d95-8583-758e6551b953",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:53.594+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "text": {
                        "status": "generated",
                        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody/></table></div>"
                    }
                }
            },
            {
                "name": "resource",
                "resource": {
                    "resourceType": "Patient",
                    "id": "337679e5-aae4-4d95-8583-758e6551b9xx",
                    "meta": {
                        "versionId": "1",
                        "lastUpdated": "2021-03-08T07:45:53.699+00:00",
                        "source": "#aoXNf2q7CgVTGdH3"
                    },
                    "text": {
                        "status": "generated",
                        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody/></table></div>"
                    }
                }
            }
        ]
    }


    OR collect-data operation for TX-CURR 
Sample result for tx-curr
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "measureReport",
            "resource": {
                "resourceType": "MeasureReport",
                "status": "complete",
                "type": "data-collection",
                "measure": "Measure/TX_CURR",
                "evaluatedResource": [
                    {
                        "reference": "http://localhost:8090/fhir/Observation/3"
                    },
                    {
                        "reference": "http://localhost:8090/fhir/Observation/5"
                    },
                    {
                        "reference": "http://localhost:8090/fhir/Patient/9c5162a4-1cbb-4239-8813-da2d10be1ff4"
                    },
                    {
                        "reference": "http://localhost:8090/fhir/Patient/337679e5-aae4-4d95-8583-758e6551b953"
                    }
                ]
            }
        },
        {
            "name": "resource",
            "resource": {
                "resourceType": "Observation",
                "id": "3",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-06-11T14:08:01.343+00:00",
                    "source": "#SWejcS1NYfNe3dbs"
                },
                "status": "final",
                "category": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                "code": "laboratory",
                                "display": "Laboratory"
                            }
                        ]
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "code": "160119AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                            "display": "CURRENTLY TAKING ARV"
                        },
                        {
                            "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                            "code": "160119",
                            "display": "CURRENTLY TAKING ARV"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/9c5162a4-1cbb-4239-8813-da2d10be1ff4",
                    "type": "Patient",
                    "display": "Obs_Test2 Obs_Test2 Obs_Test2 (OpenMRS ID: 10001V)"
                },
                "encounter": {
                    "reference": "Encounter/13cbf9b8-24fa-4806-8f2b-8e4f489b1f96",
                    "type": "Encounter"
                },
                "effectiveDateTime": "2021-06-01T08:12:28+00:00",
                "issued": "2021-06-01T08:12:28.000+00:00",
                "valueCodeableConcept": {
                    "coding": [
                        {
                            "code": "1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                            "display": "YES"
                        },
                        {
                            "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                            "code": "1065",
                            "display": "YES"
                        }
                    ]
                }
            }
        },
        {
            "name": "resource",
            "resource": {
                "resourceType": "Observation",
                "id": "5",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-06-11T14:08:01.343+00:00",
                    "source": "#SWejcS1NYfNe3dbs"
                },
                "status": "final",
                "category": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                "code": "laboratory",
                                "display": "Laboratory"
                            }
                        ]
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "code": "160119AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                            "display": "CURRENTLY TAKING ARV"
                        },
                        {
                            "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                            "code": "160119",
                            "display": "CURRENTLY TAKING ARV"
                        }
                    ]
                },
                "subject": {
                    "reference": "Patient/337679e5-aae4-4d95-8583-758e6551b953",
                    "type": "Patient",
                    "display": "Obs_Test1 Obs_Test1 Obs_Test1 (OpenMRS ID: 10000X)"
                },
                "encounter": {
                    "reference": "Encounter/4b91bc4f-9eef-4144-a88f-d8998ae932cf",
                    "type": "Encounter"
                },
                "effectiveDateTime": "2021-06-01T08:11:12+00:00",
                "issued": "2021-06-01T08:11:12.000+00:00",
                "valueCodeableConcept": {
                    "coding": [
                        {
                            "code": "1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                            "display": "NO"
                        },
                        {
                            "system": "https://openconceptlab.org/orgs/CIEL/sources/CIEL",
                            "code": "1066",
                            "display": "NO"
                        }
                    ]
                }
            }
        },
        {
            "name": "resource",
            "resource": {
                "resourceType": "Patient",
                "id": "9c5162a4-1cbb-4239-8813-da2d10be1ff4",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-06-11T14:08:01.844+00:00",
                    "source": "#SWejcS1NYfNe3dbs"
                },
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody/></table></div>"
                }
            }
        },
        {
            "name": "resource",
            "resource": {
                "resourceType": "Patient",
                "id": "337679e5-aae4-4d95-8583-758e6551b953",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-06-11T14:08:01.956+00:00",
                    "source": "#SWejcS1NYfNe3dbs"
                },
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody/></table></div>"
                }
            }
        }
    ]
}
  1. Calculating the TX-PVLS or TX-CURR Indicator and Generating the Measure Report 
    In order to generate the Measure report as a result of the indicator calculation , invoke the evaluate-measure operation using the following request

    GET : http://localhost:8090/fhir/Measure/TX-PVLS/$evaluate-measure?periodStart=2019-01-01&periodEnd=2030-12-31 or http://localhost:8090/fhir/Measure/TX-CURR/$evaluate-measure?periodStart=2019-01-01&periodEnd=2030-12-31

    This should generate and return a MesureReport for TX-PVLS result like below 

    {
        "resourceType": "MeasureReport",
        "status": "complete",
        "type": "summary",
        "measure": "Measure/TX-PVLS",
        "period": {
            "start": "2019-01-01T00:00:00+00:00",
            "end": "2030-12-31T00:00:00+00:00"
        },
        "group": [
            {
                "id": "population",
                "population": [
                    {
                        "code": {
                            "coding": [
                                {
                                    "code": "initial-population"
                                }
                            ]
                        },
                        "count": 3
                    },
                    {
                        "code": {
                            "coding": [
                                {
                                    "code": "numerator"
                                }
                            ]
                        },
                        "count": 2
                    },
                    {
                        "code": {
                            "coding": [
                                {
                                    "code": "denominator"
                                }
                            ]
                        },
                        "count": 3
                    }
                ],
                "measureScore": {
                    "value": 0.6666666666666666
                }
            }
        ],
        "evaluatedResource": [
            {
                "reference": "#Observation/9"
            },
            {
                "reference": "#Observation/8"
            },
            {
                "reference": "#Observation/7"
            },
            {
                "reference": "#Observation/5"
            }
        ]
    }

     

    OR TX-CURR result like below
TX-CURR
{
    "resourceType": "MeasureReport",
    "status": "complete",
    "type": "summary",
    "measure": "Measure/TX-CURR",
    "period": {
        "start": "2021-01-01T00:00:00+00:00",
        "end": "2021-06-02T00:00:00+00:00"
    },
    "group": [
        {
            "id": "population",
            "population": [
                {
                    "code": {
                        "coding": [
                            {
                                "code": "initial-population"
                            }
                        ]
                    },
                    "count": 1
                }
            ]
        }
    ],
    "evaluatedResource": [
        {
            "reference": "#Observation/5"
        },
        {
            "reference": "#Observation/3"
        }
    ]
}