Using CQL With FHIR
3.0.0-ballot - STU 3 Ballot International flag

This page is part of the Using CQL with FHIR Implementation Guide (v3.0.0-ballot: STU 3 Ballot) based on FHIR (HL7® FHIR® Standard) R4. This version is a pre-release. The current official version is 2.0.0. For a full list of available versions, see the Directory of published versions

: CQL Group Evaluate

Page standards status: Trial-use Maturity Level: 1

Raw json | Download

{
  "resourceType" : "OperationDefinition",
  "id" : "cql-group-evaluate",
  "language" : "en",
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: OperationDefinition cql-group-evaluate</b></p><a name=\"cql-group-evaluate\"> </a><a name=\"hccql-group-evaluate\"> </a><p>URL: [base]/Group/$evaluate</p><p>URL: [base]/Group/[id]/$evaluate</p><h3>Parameters</h3><table class=\"grid\"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>url</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#canonical\">canonical</a></td><td/><td><div><p>The canonical url (with optional version) of the group to be evaluated. This parameter is only used when the operation is invoked at the type level, and is exclusive with the group parameter.</p>\n</div></td></tr><tr><td>IN</td><td>group</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/group.html\">Group</a></td><td/><td><div><p>The group to be evaluated, provided as an input. This parameter is only used when the operation is invoked at the type level, and is exclusive with the url parameter.</p>\n</div></td></tr><tr><td>IN</td><td>subject</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\">string</a><br/>(<a href=\"https://hl7.org/fhir/R4/search.html#reference\">reference</a>)</td><td/><td><div><p>Subject(s) for which the group definition will be evaluated. This corresponds to the context in which the group will be evaluated and is represented as a relative FHIR id (e.g. Patient/123), which establishes both the context and context value for the evaluation. This MAY be a reference to a Group, in which case the membership criteria is evaluated for every member of the subject group. This parameter cannot be used with the subjectGroup parameter. If no subject or subjectGroup is provided, the group definition is evaluated for all potential subjects.</p>\n</div></td></tr><tr><td>IN</td><td>subjectGroup</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/group.html\">Group</a></td><td/><td><div><p>A Group of subjects for which the group definition will be evaluated, provided directly as a Group resource. This parameter cannot be used with the subject parameter. If no subject or subjectGroup is provided, the group definition is evaluated for all potential subjects.</p>\n</div></td></tr><tr><td>IN</td><td>parameters</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/parameters.html\">Parameters</a></td><td/><td><div><p>Any input parameters to the evaluation. The Parameters resource provided in this input <strong>SHALL</strong> conform to the <a href=\"StructureDefinition-cql-parameters.html\">CQLParameters</a> profile. Parameters defined in this input will be bound by name to the evaluation context. If the membership criteria is a CQL expression, these parameters will be available to the expression. If the membership criteria is a CQL identifier, these parameters will be bound by name to the parameters defined in the CQL library (or included libraries, recursively). Parameter types are mapped to CQL as specified in the Using CQL section of this implementation guide. If a parameter appears more than once in the input Parameters resource, it is represented with a List in the input CQL. If a parameter has parts, it is represented as a Tuple in the input CQL. Note that parameters may be arbitrarily nested, for example, a list of tuples, or tuples that have list or interval valued elements. If parameter names are qualified, the parameter will be bound only to parameters in the library with the qualifier name, and the qualifier name must be the name of a library included by the library being evaluated (or an included library, recursively).</p>\n</div></td></tr><tr><td>IN</td><td>artifactEndpointConfiguration</td><td/><td>0..*</td><td/><td/><td><div><p>Configuration information to resolve canonical artifacts</p>\n<ul>\n<li><code>artifactRoute</code>: An optional route used to determine whether this endpoint is expected to be able to resolve artifacts that match the route (i.e. start with the route, up to and including the entire url)</li>\n<li><code>endpointUri</code>: The URI of the endpoint, exclusive with the <code>endpoint</code> parameter</li>\n<li><code>endpoint</code>: An Endpoint resource describing the endpoint, exclusive with the <code>endpointUri</code> parameter</li>\n</ul>\n<p><strong>Processing semantics</strong>:</p>\n<p>Create a canonical-like reference (e.g.\n<code>{canonical.url}|{canonical.version}</code> or similar extensions for non-canonical artifacts).</p>\n<ul>\n<li>Given a single <code>artifactEndpointConfiguration</code>\n<ul>\n<li>When <code>artifactRoute</code> is present\n<ul>\n<li>And canonical or artifact reference <em>starts with</em> <code>artifactRoute</code></li>\n<li>Then attempt to resolve with <code>endpointUri</code> or <code>endpoint</code></li>\n</ul>\n</li>\n<li>When <code>artifactRoute</code> is not present\n<ul>\n<li>Then attempt to resolve with <code>endpointUri</code> or <code>endpoint</code></li>\n</ul>\n</li>\n</ul>\n</li>\n<li>Given multiple <code>artifactEndpointConfiguration</code>s\n<ul>\n<li>Then rank order each configuration (see below)</li>\n<li>And attempt to resolve with <code>endpointUri</code> or <code>endpoint</code> in order until resolved</li>\n</ul>\n</li>\n</ul>\n<p>Rank each <code>artifactEndpointConfiguration</code> such that:</p>\n<ul>\n<li>if <code>artifactRoute</code> is present <em>and</em> canonical or artifact reference <em>starts with</em> <code>artifactRoute</code>: rank based on number of matching characters</li>\n<li>if <code>artifactRoute</code> is <em>not</em> present: include but rank lower</li>\n</ul>\n<p>NOTE: For evenly ranked <code>artifactEndpointConfiguration</code>s, order as defined in the\nOperationDefinition.</p>\n</div></td></tr><tr><td>IN</td><td>artifactEndpointConfiguration.artifactRoute</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#uri\">uri</a></td><td/><td/></tr><tr><td>IN</td><td>artifactEndpointConfiguration.endpointUri</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#uri\">uri</a></td><td/><td/></tr><tr><td>IN</td><td>artifactEndpointConfiguration.endpoint</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/endpoint.html\">Endpoint</a></td><td/><td/></tr><tr><td>IN</td><td>timestamp</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#dateTime\">dateTime</a></td><td/><td><div><p>The timestamp of the evaluation request.</p>\n</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/group.html\">Group</a></td><td/><td><div><p>The results of the group evaluation, returned as an actual Group resource with members as determined by the evaluation of the membership criteria against the data present in the server.</p>\n</div></td></tr></table></div>"
  },
  "extension" : [
    {
      "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
      "valueInteger" : 1
    },
    {
      "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
      "valueCode" : "cds"
    },
    {
      "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
      "valueCode" : "trial-use"
    }
  ],
  "url" : "http://hl7.org/fhir/uv/cql/OperationDefinition/cql-group-evaluate",
  "version" : "3.0.0-ballot",
  "name" : "CQLGroupEvaluate",
  "title" : "CQL Group Evaluate",
  "status" : "active",
  "kind" : "operation",
  "experimental" : false,
  "date" : "2023-11-27T16:26:11+00:00",
  "publisher" : "HL7 International / Clinical Decision Support",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "url",
          "value" : "http://www.hl7.org/Special/committees/dss"
        }
      ]
    }
  ],
  "description" : "Evaluates the membership criteria of a group definition returns the results as an actual Group resource. The Group is expected to use the characteristicsExpression extension to define membership criteria.",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "http://unstats.un.org/unsd/methods/m49/m49.htm",
          "code" : "001",
          "display" : "World"
        }
      ]
    }
  ],
  "purpose" : "This operation is defined to support evaluating the membership criteria of a group definition directly via an operation",
  "affectsState" : false,
  "code" : "evaluate",
  "resource" : [
    "Group"
  ],
  "system" : false,
  "type" : true,
  "instance" : true,
  "parameter" : [
    {
      "name" : "url",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The canonical url (with optional version) of the group to be evaluated. This parameter is only used when the operation is invoked at the type level, and is exclusive with the group parameter.",
      "type" : "canonical"
    },
    {
      "name" : "group",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The group to be evaluated, provided as an input. This parameter is only used when the operation is invoked at the type level, and is exclusive with the url parameter.",
      "type" : "Group"
    },
    {
      "name" : "subject",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "Subject(s) for which the group definition will be evaluated. This corresponds to the context in which the group will be evaluated and is represented as a relative FHIR id (e.g. Patient/123), which establishes both the context and context value for the evaluation. This MAY be a reference to a Group, in which case the membership criteria is evaluated for every member of the subject group. This parameter cannot be used with the subjectGroup parameter. If no subject or subjectGroup is provided, the group definition is evaluated for all potential subjects.",
      "type" : "string",
      "searchType" : "reference"
    },
    {
      "name" : "subjectGroup",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "A Group of subjects for which the group definition will be evaluated, provided directly as a Group resource. This parameter cannot be used with the subject parameter. If no subject or subjectGroup is provided, the group definition is evaluated for all potential subjects.",
      "type" : "Group"
    },
    {
      "name" : "parameters",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "Any input parameters to the evaluation. The Parameters resource provided in this input **SHALL** conform to the [CQLParameters](StructureDefinition-cql-parameters.html) profile. Parameters defined in this input will be bound by name to the evaluation context. If the membership criteria is a CQL expression, these parameters will be available to the expression. If the membership criteria is a CQL identifier, these parameters will be bound by name to the parameters defined in the CQL library (or included libraries, recursively). Parameter types are mapped to CQL as specified in the Using CQL section of this implementation guide. If a parameter appears more than once in the input Parameters resource, it is represented with a List in the input CQL. If a parameter has parts, it is represented as a Tuple in the input CQL. Note that parameters may be arbitrarily nested, for example, a list of tuples, or tuples that have list or interval valued elements. If parameter names are qualified, the parameter will be bound only to parameters in the library with the qualifier name, and the qualifier name must be the name of a library included by the library being evaluated (or an included library, recursively).",
      "type" : "Parameters"
    },
    {
      "name" : "artifactEndpointConfiguration",
      "use" : "in",
      "min" : 0,
      "max" : "*",
      "documentation" : "Configuration information to resolve canonical artifacts\n* `artifactRoute`: An optional route used to determine whether this endpoint is expected to be able to resolve artifacts that match the route (i.e. start with the route, up to and including the entire url)\n* `endpointUri`: The URI of the endpoint, exclusive with the `endpoint` parameter\n* `endpoint`: An Endpoint resource describing the endpoint, exclusive with the `endpointUri` parameter\n\n**Processing semantics**:\n\nCreate a canonical-like reference (e.g.\n`{canonical.url}|{canonical.version}` or similar extensions for non-canonical artifacts).\n\n* Given a single `artifactEndpointConfiguration`\n  * When `artifactRoute` is present\n    * And canonical or artifact reference *starts with* `artifactRoute`\n    * Then attempt to resolve with `endpointUri` or `endpoint`\n  * When `artifactRoute` is not present\n    * Then attempt to resolve with `endpointUri` or `endpoint`\n* Given multiple `artifactEndpointConfiguration`s\n  * Then rank order each configuration (see below)\n  * And attempt to resolve with `endpointUri` or `endpoint` in order until resolved\n\nRank each `artifactEndpointConfiguration` such that:\n* if `artifactRoute` is present *and* canonical or artifact reference *starts with* `artifactRoute`: rank based on number of matching characters \n* if `artifactRoute` is *not* present: include but rank lower\n\nNOTE: For evenly ranked `artifactEndpointConfiguration`s, order as defined in the\nOperationDefinition.",
      "part" : [
        {
          "name" : "artifactRoute",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "type" : "uri"
        },
        {
          "name" : "endpointUri",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "type" : "uri"
        },
        {
          "name" : "endpoint",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "type" : "Endpoint"
        }
      ]
    },
    {
      "name" : "timestamp",
      "use" : "in",
      "min" : 0,
      "max" : "1",
      "documentation" : "The timestamp of the evaluation request.",
      "type" : "dateTime"
    },
    {
      "name" : "return",
      "use" : "out",
      "min" : 1,
      "max" : "1",
      "documentation" : "The results of the group evaluation, returned as an actual Group resource with members as determined by the evaluation of the membership criteria against the data present in the server.",
      "type" : "Group"
    }
  ]
}