Add GET Compositions request with basic search parameters

[heathfrankel]

Request

GET ./ehr/{ehr_id}/composition?start_time=ge20170218T0000Z&archetype_id=openEHR-EHR-COMPOSITION.report.v1&template_id=pathology_report

Response

Good question. Following the RM it would be SET<OBJECT_REF>. This wouldn't be very useful for an application so we need a Resultset structure of the matching compositions or a minimal composition data structure.
My preference would be a Resultset structure that aligns with an AQL query results with a server defaulted set of composition attributes. An additional request parameter of comma separated composition attributes could be provided to override these default attributes. For example:
&selectedAttributes=uid,name,start_time,health_care_facility-name

EDIT: There is a wikipage diskussing this issue too https://openehr.atlassian.net/wiki/spaces/spec/pages/94005928/Filtering+for+Simple+Queries+in+REST+APIs

[bjornna]

As you write - the result of such an operation should most likely be an RESULT_SET object.
And it would be really easy to map this kind of endpoint outside an AQL resource.

One example might be the following AQL and RESULT_SET (DIPS style currently). I think we first should focus on finishing the AQL endpoint (and RESULT_SET class) and then see how to apply this on the kind of filter/queries defined in this PR.

    select
        c/uid as uid, 
	c/context/start_time as start_time        
    from
        composition c[openEHR-EHR-COMPOSITION.trajectory.v1]  
    where
        c/archetype_details/archetype_id/value = 'openEHR-EHR-COMPOSITION.trajectory.v1'      
        and c/archetype_details/template_id/value = 'CancerTrajectory_v4.1.0'     
        and c/context/start_time/value > '2016-04-13T22:32:08.973+02:00'  
    limit
        2

{
  "_type": "RESULTSET",
  "_schemaVersion": "1.0.0",
  "_format": "raw",
  "_created": "2017-08-18T08:50:10.68+02:00",
  "_generator": "DIPS.OpenEhr.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)",
  "name": null,
  "totalResults": 2,
  "columns": [
    {
      "name": "uid",
      "path": "/uid"
    },
    {
      "name": "start_time",
      "path": "/context/start_time"
    }
  ],
  "rows": [
    [
      {
        "_type": "OBJECT_VERSION_ID",
        "value": "58100f83-427f-4504-b30b-5102cd2987db::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      {
        "_type": "DV_DATE_TIME",
        "value": "2016-04-13T22:32:56.715+02:00"
      }
    ],
    [
      {
        "_type": "OBJECT_VERSION_ID",
        "value": "84ac7b27-3dcd-4853-b76d-c755bd464e16::91215053-854b-45b8-bb2a-3b0d255858d1::1"
      },
      {
        "_type": "DV_DATE_TIME",
        "value": "2016-10-06T11:03:49.225+02:00"
      }
    ]
  ]
}

Below is also the XML representation of the RESULT_SET:

<?xml version="1.0" encoding="utf-16"?>
<!--DIPS.OpenEhr.ResultSets.Serialization.Xml.ResultSetXmlWriter (5.0.0.0)-->
<resultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.openehr.org/v1">
  <correlationid>00000000-0000-0000-0000-000000000000</correlationid>
  <totalResults>2</totalResults>
  <columns>
    <name>uid</name>
    <path>/uid</path>
  </columns>
  <columns>
    <name>start_time</name>
    <path>/context/start_time</path>
  </columns>
  <rows>
    <row>
      <items xsi:type="OBJECT_VERSION_ID">
        <value>58100f83-427f-4504-b30b-5102cd2987db::91215053-854b-45b8-bb2a-3b0d255858d1::1</value>
      </items>
      <items xsi:type="DV_DATE_TIME">
        <value>2016-04-13T22:32:56.715+02:00</value>
      </items>
    </row>
    <row>
      <items xsi:type="OBJECT_VERSION_ID">
        <value>84ac7b27-3dcd-4853-b76d-c755bd464e16::91215053-854b-45b8-bb2a-3b0d255858d1::1</value>
      </items>
      <items xsi:type="DV_DATE_TIME">
        <value>2016-10-06T11:03:49.225+02:00</value>
      </items>
    </row>
  </rows>
  <tags />
</resultSet>

[heathfrankel]

Hmm, this Resultset schema looks familiar. Good to see, I think we should definitely define and get concensus on this type. Where in the API spec do we do this, up the top like the other general stuff?

I don't see that the query endpoint has to be deferred because it is not in the BASE, so if you want to work on this, and agree on the response type and reuse this for the Composition Search request then that's fine. In the meantime we can still define what the request looks like.

[ppazos]

Result set for compo should include locatable data: name, archid, template is, etc.

[bjornna]

@ppazos here is the same example (almost) - but now I ask for the composition. Does this answer your comment?

select
        c       
    from
        composition c[openEHR-EHR-COMPOSITION.trajectory.v1]  
    where
        c/archetype_details/archetype_id/value = 'openEHR-EHR-COMPOSITION.trajectory.v1'      
        and c/archetype_details/template_id/value = 'CancerTrajectory_v4.1.0'     
        and c/context/start_time/value > '2016-04-13T22:32:08.973+02:00'  
    limit
        1

{
  "_type": "RESULTSET",
  "_schemaVersion": "1.0.0",
  "_format": "raw",
  "_created": "2017-08-18T14:12:26.497+02:00",
  "_generator": "DIPS.OpenEhr.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)",
  "name": null,
  "totalResults": 1,
  "columns": [
    {
      "name": "c",
      "path": null
    }
  ],
  "rows": [
    [
      {
        "_type": "COMPOSITION",
        "archetype_node_id": "openEHR-EHR-COMPOSITION.trajectory.v1",
        "name": {
          "value": "Pakkeforløp for kreft"
        },
        "uid": {
          "_type": "OBJECT_VERSION_ID",
          "value": "58100f83-427f-4504-b30b-5102cd2987db::91215053-854b-45b8-bb2a-3b0d255858d1::1"
        },
        "archetype_details": {
          "archetype_id": {
            "value": "openEHR-EHR-COMPOSITION.trajectory.v1"
          },
          "template_id": {
            "value": "CancerTrajectory_v4.1.0"
          },
          "rm_version": "1.0.1"
        },
        "language": {
          "terminology_id": {
            "value": "openehr"
          },
          "code_string": "nb"
        },
        "territory": {
          "terminology_id": {
            "value": "openehr"
          },
          "code_string": "NO"
        },
        "category": {
          "value": null,
          "defining_code": {
            "terminology_id": {
              "value": "openehr"
            },
            "code_string": "433"
          }
        },
        "composer": {
          "_type": "PARTY_IDENTIFIED",
          "name": "default"
        },
        "context": {
          "start_time": {
            "value": "2016-04-13T22:32:56.715+02:00"
          },
          "setting": {
            "value": null,
            "defining_code": {
              "terminology_id": {
                "value": "openehr"
              },
              "code_string": "232"
            }
          }
        },
        "content": [
          {
            "_type": "SECTION",
            "archetype_node_id": "openEHR-EHR-SECTION.adhoc.v1",
            "name": {
              "value": "Avslutning"
            },
            "archetype_details": {
              "archetype_id": {
                "value": "openEHR-EHR-SECTION.adhoc.v1"
              },
              "template_id": {
                "value": "CancerTrajectory_v4.1.0"
              },
              "rm_version": "1.0.1"
            },
            "items": [
              {
                "_type": "ACTION",
                "archetype_node_id": "openEHR-EHR-ACTION.trajectory_follow_up.v1",
                "name": {
                  "value": "Avslutning andre årsaker"
                },
                "archetype_details": {
                  "archetype_id": {
                    "value": "openEHR-EHR-ACTION.trajectory_follow_up.v1"
                  },
                  "template_id": {
                    "value": "CancerTrajectory_v4.1.0"
                  },
                  "rm_version": "1.0.1"
                },
                "language": {
                  "terminology_id": {
                    "value": "ISO_639-1"
                  },
                  "code_string": "nb"
                },
                "encoding": {
                  "terminology_id": {
                    "value": "IANA"
                  },
                  "code_string": "UTF-8"
                },
                "subject": {
                  "_type": "PARTY_SELF"
                },
                "time": {
                  "value": "2016-04-13T22:32:50+02:00"
                },
                "description": {
                  "_type": "ITEM_TREE",
                  "archetype_node_id": "at0001",
                  "name": {
                    "value": "Tre"
                  },
                  "items": [
                    {
                      "_type": "ELEMENT",
                      "archetype_node_id": "at0002",
                      "name": {
                        "value": "Hendelse"
                      },
                      "value": {
                        "_type": "DV_CODED_TEXT",
                        "value": "Avslutning av pakkeforløp (andre årsaker)",
                        "defining_code": {
                          "terminology_id": {
                            "value": "Kreftpakke"
                          },
                          "code_string": "X"
                        }
                      }
                    },
                    {
                      "_type": "ELEMENT",
                      "archetype_node_id": "at0010",
                      "name": {
                        "value": "Beskrivelse"
                      },
                      "value": {
                        "_type": "DV_TEXT",
                        "value": "Test"
                      }
                    }
                  ]
                },
                "ism_transition": {
                  "current_state": {
                    "value": "aborted",
                    "defining_code": {
                      "terminology_id": {
                        "value": "openehr"
                      },
                      "code_string": "531"
                    }
                  },
                  "careflow_step": {
                    "value": "Avbryt",
                    "defining_code": {
                      "terminology_id": {
                        "value": "local"
                      },
                      "code_string": "at0005"
                    }
                  }
                }
              }
            ]
          }
        ]
      }
    ]
  ]
}

And in XML:

<?xml version="1.0" encoding="utf-16"?>
<!--DIPS.OpenEhr.ResultSets.Serialization.Xml.ResultSetXmlWriter (5.0.0.0)-->
<resultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.openehr.org/v1">
  <correlationid>00000000-0000-0000-0000-000000000000</correlationid>
  <totalResults>1</totalResults>
  <columns>
    <name>c</name>
    <path />
  </columns>
  <rows>
    <row>
      <items xsi:type="COMPOSITION" archetype_node_id="openEHR-EHR-COMPOSITION.trajectory.v1">
        <name>
          <value>Pakkeforløp for kreft</value>
        </name>
        <uid xsi:type="OBJECT_VERSION_ID">
          <value>58100f83-427f-4504-b30b-5102cd2987db::91215053-854b-45b8-bb2a-3b0d255858d1::1</value>
        </uid>
        <archetype_details>
          <archetype_id>
            <value>openEHR-EHR-COMPOSITION.trajectory.v1</value>
          </archetype_id>
          <template_id>
            <value>CancerTrajectory_v4.1.0</value>
          </template_id>
          <rm_version>1.0.1</rm_version>
        </archetype_details>
        <language>
          <terminology_id>
            <value>openehr</value>
          </terminology_id>
          <code_string>nb</code_string>
        </language>
        <territory>
          <terminology_id>
            <value>openehr</value>
          </terminology_id>
          <code_string>NO</code_string>
        </territory>
        <category>
          <value />
          <defining_code>
            <terminology_id>
              <value>openehr</value>
            </terminology_id>
            <code_string>433</code_string>
          </defining_code>
        </category>
        <composer xsi:type="PARTY_IDENTIFIED">
          <name>default</name>
        </composer>
        <context>
          <start_time>
            <value>2016-04-13T22:32:56.715+02:00</value>
          </start_time>
          <setting>
            <value />
            <defining_code>
              <terminology_id>
                <value>openehr</value>
              </terminology_id>
              <code_string>232</code_string>
            </defining_code>
          </setting>
        </context>
        <content xsi:type="SECTION" archetype_node_id="openEHR-EHR-SECTION.adhoc.v1">
          <name>
            <value>Avslutning</value>
          </name>
          <archetype_details>
            <archetype_id>
              <value>openEHR-EHR-SECTION.adhoc.v1</value>
            </archetype_id>
            <template_id>
              <value>CancerTrajectory_v4.1.0</value>
            </template_id>
            <rm_version>1.0.1</rm_version>
          </archetype_details>
          <items xsi:type="ACTION" archetype_node_id="openEHR-EHR-ACTION.trajectory_follow_up.v1">
            <name>
              <value>Avslutning andre årsaker</value>
            </name>
            <archetype_details>
              <archetype_id>
                <value>openEHR-EHR-ACTION.trajectory_follow_up.v1</value>
              </archetype_id>
              <template_id>
                <value>CancerTrajectory_v4.1.0</value>
              </template_id>
              <rm_version>1.0.1</rm_version>
            </archetype_details>
            <language>
              <terminology_id>
                <value>ISO_639-1</value>
              </terminology_id>
              <code_string>nb</code_string>
            </language>
            <encoding>
              <terminology_id>
                <value>IANA</value>
              </terminology_id>
              <code_string>UTF-8</code_string>
            </encoding>
            <subject xsi:type="PARTY_SELF" />
            <time>
              <value>2016-04-13T22:32:50+02:00</value>
            </time>
            <description xsi:type="ITEM_TREE" archetype_node_id="at0001">
              <name>
                <value>Tre</value>
              </name>
              <items xsi:type="ELEMENT" archetype_node_id="at0002">
                <name>
                  <value>Hendelse</value>
                </name>
                <value xsi:type="DV_CODED_TEXT">
                  <value>Avslutning av pakkeforløp (andre årsaker)</value>
                  <defining_code>
                    <terminology_id>
                      <value>Kreftpakke</value>
                    </terminology_id>
                    <code_string>X</code_string>
                  </defining_code>
                </value>
              </items>
              <items xsi:type="ELEMENT" archetype_node_id="at0010">
                <name>
                  <value>Beskrivelse</value>
                </name>
                <value xsi:type="DV_TEXT">
                  <value>Test</value>
                </value>
              </items>
            </description>
            <ism_transition>
              <current_state>
                <value>aborted</value>
                <defining_code>
                  <terminology_id>
                    <value>openehr</value>
                  </terminology_id>
                  <code_string>531</code_string>
                </defining_code>
              </current_state>
              <careflow_step>
                <value>Avbryt</value>
                <defining_code>
                  <terminology_id>
                    <value>local</value>
                  </terminology_id>
                  <code_string>at0005</code_string>
                </defining_code>
              </careflow_step>
            </ism_transition>
          </items>
        </content>
      </items>
    </row>
  </rows>
  <tags />
</resultSet>

[ppazos]

@bjornna Gotcha, I miss the projections of the first example.

On the second example, shouldn't the rows contain all the projections for compo? instead of:

    {
      "name": "c",
      "path": null
    }

[bjornna]

No - the "name" tells which parameter is located in a specific location. In this example the whole composition i present in the actual "column" of the result set.

The example below might show how this works better?

i.e.

select c/context/start_time as startTime,  c as comp from Composition c

"columns": [
    {
      "name": "startTime",
      "path": "/context/start_time"
    },
    {
      "name": "comp",
      "path": null
    }
  ]

[ppazos]

@bjornna gotcha. In that case, path seems to be relative to the compo, shouldn't that be "/" instead of null?

[bjornna]

@pablo - you might be right about the / . I am not sure why we choosed current form with null. Will ask my developers about the details.

[sebastian-iancu]

As @heathfrankel initally commented, we should perhaps not involve AQL /query in this issue, but focus on RESULT_SET. It might be a valid response for
GET ./ehr/{ehr_id}/composition?start_time=ge20170218T0000Z&archetype_id=openEHR-EHR-COMPOSITION.report.v1&template_id=pathology_report
plus some pagination, sorting, etc

[ErikSundvall]

Result set was also discussed in https://openehr.atlassian.net/wiki/spaces/spec/pages/33849346/AQL+Result+Set+work+area