FHIR Chat · FHIR async operation status response

Stream: implementers

Topic: FHIR async operation status response

Ivan Dubrov (Jun 17 2020 at 20:38):

Would it make sense to have more formalized description for FHIR async operations? Currently, for bulk FHIR, response is defined in an ad-hoc manner (https://www.hl7.org/fhir/async.html) as a simple JSON structure.

I wonder if this should be generalized and OperationDefinition utilized as well to define format of async operations status?

In our implementation of FHIR server, we use "out" parameters to define async operation status response. This gives a nice symmetry between synchronoous and asynchronous operation: whatever synchronous operation returns immediately, asynchronous operation returns in its status response. An implementation can also allow calling any synchronous operation asynchronously (in which case, operation completes immediately and status is the response itself) or asynchronous operation synchronously (in which case we poll for status internally, then return status response as a regular response).

However, one little challenge is that Bulk FHIR, which is an operation defined in FHIR specification, uses format for its status output which is incompatible with the FHIR Parameters resource format.

To handle that case, we kind of paper over it with the following "trick": we define a process of mapping Parameters response into "simplified JSON response". The mapping is trivial: every singular parameter becomes a field, every list parameter becomes field with JSON array as a value.

For example, the following response:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "message",
      "valueString": "I'm not a teapot!"
    }
  ]
}

converted to simplified JSON response will look like:

{
  "message": "I'm not a teapot!"
}

It's not possible to represent arbitrary JSON this way (for example, array of array is not representable), but luckily, Bulk FHIR (the only one we care about so far) is representable this way.

Currently, we distinguish between two response formats via Accept header: application/fhir+json will return Parameters resource, application/json will return simplified JSON response.

Would this make sense to be proposed for the async specification? I think, having symmetry between sync and async operations is useful, and utilizing existing tools for formal declaration of status response is also very valuable.

My preference, though, would be to limit status response to be Parameters resource always (without any "simplified JSON response"). I don't think it would require async operation implementor to necessarily be FHIR server (I think, I've seen this argument somewhere?) as Parameters JSON can be generated just like a regular JSON. One downside, though, is that Parameters resource is a bit difficult to use / handle, but this is complexity that FHIR has already anyways (for regular extended operations).

Grahame Grieve (Jun 17 2020 at 20:39):

Bulk FHIR, which is an operation defined in FHIR specification, uses format for its status output which is incompatible with the FHIR Parameters resource format

I don't think that's true

Grahame Grieve (Jun 17 2020 at 20:40):

I guess you are referring to the intermediate status update responses, for which we don't use the parameters resource

Ivan Dubrov (Jun 17 2020 at 20:46):

I mean completed status response as defined here (for Bulk FHIR): https://www.hl7.org/fhir/async.html#3.1.6.4.0.4
For example, in our server "FHIR native" status response looks like this:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "transactionTime",
      "valueInstant": "2020-06-17T17:47:29.941100+00:00"
    },
    {
      "name": "request",
      "valueUrl": "<url>"
    },
    {
      "name": "requiresAccessToken",
      "valueBoolean": true
    },
    {
      "name": "output",
      "part": [
        {
          "name": "partition",
          "valueUnsignedInt": 0
        },
        {
          "name": "url",
          "valueUrl": "<url>"
        },
        {
          "name": "count",
          "valueUnsignedInt": 570
        }
      ]
    }
  ]
}

versus "simplified JSON response" which looks like this:

{
  "transactionTime": "2020-06-17T17:47:29.941100+00:00",
  "request": "<url>",
  "requiresAccessToken": true,
  "output": [
    {
      "partition": 0,
      "url": "<url>",
      "count": 570
    }
  ]
}

Grahame Grieve (Jun 17 2020 at 20:48):

well, we deliberately chose not to use the Parameters resource here; the implementers at the time felt that it was simpler not to, and there was no pressing reason to. I guess you're saying that you have a hammer, and you'd rather that this was a nail right here

Lee Surprenant (Jun 18 2020 at 12:00):

I find that whole https://www.hl7.org/fhir/async.html page confusing because there is an entirely separate bulkdata IG which has a different response message defined at https://hl7.org/fhir/uv/bulkdata/

Lee Surprenant (Jun 18 2020 at 12:02):

or, looking at https://hl7.org/fhir/uv/bulkdata/export/index.html#endpoint-1 , I guess it might match today but who is responsible for keeping these in sync

Josh Mandel (Jun 18 2020 at 16:13):

Yeah, this has been a challenge. We developed guidance in the bulk IG and aimed to bring the base FHIR spec into general alignment.

Josh Mandel (Jun 18 2020 at 16:14):

As we make improvements like support for deletions, we'll at the least want to push the same changes into FHIR core. I'm open to ideas about how to better coordinate (FYI @Dan Gottlieb)

Josh Mandel (Jun 18 2020 at 16:15):

(We can continue to raise the question about whether we should switch to Parameters, but I think that's actually a distinct question from: how do we keep things in sync.)

Last updated: Apr 12 2022 at 19:14 UTC

Main menu

FHIR Chat · FHIR async operation status response · implementers