Extend API to save and load cohort and dataselection

[juliangruendner]

Extend API to save and load cohort and dataselection.

The API should be extended to allow the saving and loading of a cohort selection (CCDL) and a dataselection (dataExtraction part CRTDL).

Further it should be possible to save a CRTDL, which combines the cohort seleection and dataselection parts.

For this the endpoint POST /query/{queryId}/saved should be changed to POST /query/saved and accept the following body:

{
"label": "my-query-1",
"comment": "I wanted to see how many patients I could find for my study XYZ",
"totalNumberOfPatients": 12345
"ccdlID": "id-of-ccdl",
"dataExtractionID": "id-of-dataExtractionPart"
}

Response: analogous to current saved Reponse, but with additional Id of saved query

{
  "queryId": 123123213,
  "used": 2,
  "total": 10
}

IMPORTANT: It should also be possible to POST a query with a query ID from a query not in /cohort-selection, but in /query (as in a query that has been sent) Further the endpoint /query/by-user/{userId} should still return the totalNumberOfPatients if a query has been previously saved with a query from query instead of cohort-selection

This future post from the UI will then require a ccdlID and a dataExtractionId to be supplied.

For this two new endpoints should be created, one to post each part to the backend.

1. Cohort Selection

POST /cohort-selection Body: = CCDL (equivalent to what is currently send to query)

{
    "version": "http://to_be_decided.com/draft-1/schema#",
    "display": "Ausgewählte Merkmale",
    "inclusionCriteria": [
        [
            {
                "termCodes": [
                    {
                        "code": "263495000",
                        "system": "http://snomed.info/sct",
                        "display": "Geschlecht"
                    }
                ],
                "context": {
                    "code": "Patient",
                    "system": "fdpg.mii.cds",
                    "version": "1.0.0",
                    "display": "Patient"
                },
                "valueFilter": {
                    "selectedConcepts": [
                        {
                            "code": "female",
                            "display": "Female",
                            "system": "http://hl7.org/fhir/administrative-gender"
                        },
                        {
                            "code": "male",
                            "display": "Male",
                            "system": "http://hl7.org/fhir/administrative-gender"
                        }
                    ],
                    "type": "concept"
                }
            }
        ]
    ]
}

Response: analogous to current template endpoint, if successfull 201OK with Location Header and link to successfully stored cohort-selection

2. Data Selection

POST /data-selection Body: the dataExtraction part of the CRTDL = https://github.com/medizininformatik-initiative/clinical-resource-transfer-definition-language example:

{
  "attributeGroups": [
    {
      "groupReference": "https://www.medizininformatik-initiative.de/fhir/core/modul-labor/StructureDefinition/ObservationLab",
      "attributes": [
        {
          "attributeRef": "Observation.code",
          "mustHave": false
        },
        {
          "attributeRef": "Observation.value",
          "mustHave": true
        }
      ],
      "filter": [
        {
          "type": "token",
          "name": "code",
          "codes": [
            {
              "code": "718-7",
              "system": "http://loinc.org",
              "display": "Hemoglobin [Mass/volume] in Blood"
            },
            {
              "code": "33509-1",
              "system": "http://loinc.org",
              "display": "Hemoglobin [Mass/volume] in Body fluid"
            }
          ]
        },
        {
          "type": "date",
          "name": "date",
          "start": "2021-09-09",
          "end": "2021-10-09"
        }
      ]
    }
  ]
}

Response: analogous to current template endpoint, if successfull 201OK with Location Header and link to successfully stored data-selection

[michael-82]

Disclaimer

Since we decided to overhaul the query endpoint after the q4 release, here are some of my thoughts (not yet in a structured way) as a basis for discussion. I am quite sure that there are things I missed (or just do not know for now).

General

Queries will always be saved with the criteria and at least a label. There is no longer a distinction between "query" "saved query" and the dreaded "template". The proposed "split" between cohorts and data extraction only refers to the backend side. This does not have to be that way in the frontend.

Cohorts

Cohorts are similar to our current "query", but they can not have results at any time. They must however have a label and may or may not have a description. In my opinion, we do not need to impose any limits on cohorts. Let users save as many as they want. Maybe we can offer an option to archive them or mark as favorites?

Needed endpoints

• create
• read list (own user)
• read list by user (is this necessary here? I don't think this has to be called externally)
• read one
• update (which parts can be edited? only description? modifying the actual ccdl could lead to problems when linking by id later. if archive/favorite is needed...do it here)
• delete (can we delete this or only mark as deleted? avoid deletion when it is used in queries?)
• validate

Data Extractionl (DEQ part of CRTDL)

Needed endpoints

• create
• read list (own user)
• read list by user (is this necessary here? I don't think this has to be called externally)
• read one
• update (which parts can be edited? only description? modifying the actual ccdl could lead to problems when linking by id later. if archive/favorite is needed...do it here)
• delete (can we delete this or only mark as deleted? avoid deletion when it is used in queries?)
• validate

Queries

Queries are a combination of CCDL query, DEQ query + label + description + results

Feasibility queries

Either a CRTDL with an empty DEQ part or some other format?

Needed endpoints

• create (ccdl+label+description). save only, no dispatch
• create (ccdl-id+label+description). save only, no dispatch
• read list (own)
• read list by user (maybe filter by not-archived or favorites if this is done)
• read one
• update (only label/comment)
• execute/dispatch
• read summary result
• read detailed result
• read detailed obfuscated result

Data Extraction-Queries

CRTDL with filled DEQ part + label + description + results

Needed endpoints

• create (ccdl+deq+label+description). save only, no dispatch
• create (ccdl-id+deq-id+label+description). save only, no dispatch
• read list (own)
• read list by user (maybe filter by not-archived or favorites if this is done)
• read one
• update (only label/comment)
• execute/dispatch (probably limited)
• read result (how do results look here? do we need multiple endpoints? will a limit be imposed here?)

Questions

• what will be retrieved by the "antragsportal"? Only feasibility or also data extraction?
• which endpoints need to be limited? which limits do we need?