RDC Interoperability Guide

Generate AGP report

Client can request to generate AGP report for a patient by sending a POST request with Parameter resource to the server's generateAgpReport endpoint. This process follows the Asynchronous Interaction Request Pattern.For example:

curl -sS -X POST --json @parameter.json "https://${server}/fhir/r5/api/DiagnosticReport/$generateAgpReport" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Whereas parameter.json is file consisting of following contents (for example):

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "subject",
      "valueReference": {
        "reference": "Patient/123"
      }
    },
    {
      "name": "locale",
      "valueString": "en-US"
    },
    {
      "name": "unit",
      "valueCoding": {
        "system": "http://unitsofmeasure.org",
        "code": "mg/dL",
        "display": "mg/dL"
      }
    },
    {
      "name": "effectivePeriod",
      "valuePeriod": {
        "start": "2011-05-23",
        "end": "2011-05-27"
      }
    }
  ]
}

This request sets up a request to generate an AGP report for a patient with the ID 123. The request asks for the report to be generated in the en-US locale, with mg/dL as the unit of measure, and for the effective period between 2011-05-23 and 2011-05-27.

⚠️ Note: The effectivePeriod must be within the maximum allowed period of 14 days for generating the AGP report. If the effectivePeriod exceeds this range, the server will return an error message.

Response

Report generation request successful with 202 ACCEPTED

Upon successful completion of the POST request to generate the AGP report, the server sends back the response header Content-Location with HTTP 202 Accepted. The Content-Location is the root-relative URL of an endpoint for subsequent status requests to check the progress of the report generation.

Report generation request failed

If there is an error that prevent the asynchronous process for report generation , the server returns an OperationOutcome resource .Errors that arise after the asynchronous process has started will be returned by the status endpoint instead.

Here is an example of an Operation outcome response:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "diagnostics": "Report generation processing failed."
        }
    ]
}

Report generation request failed with 403 FORBIDDEN

AFP report generation request can fail with 403 FORBIDDEN error if :

• Access to the patient is denied or the patient does not have a data sharing consent.
• Access is forbidden for the given Professional and Personal FHIR ID.

Here is an example of an error response:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "forbidden",
            "diagnostics": "Report generation processing failed."
        }
    ]
}

• When the Managing Organisation of the requester does not match the managing organisation of the patient record

Here is an example of error response

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "forbidden",
            "diagnostics": "Only the managing organization is authorized to request this report"
        }
    ]
}

Report generation request failed with 404 NOT FOUND

AFP report generation request can fail with 404 NOT FOUND error if :

• No personal patient record exists for the patient.

here is an example of an error response:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "diagnostics": "Report generation processing failed."
        }
    ]
}

Report generation request failed with 400 BAD REQUEST

The request body is expected to be a Parameter resource and request violets the constraints would result in failure with 400 BAD REQUEST error. For example if the effectivePeriod exceeds the maximum allowed period of 14 days for generating the AGP report. Server shall return '400 BAD REQUEST' error with and OperationOutcome resource.

Here is an example of an error response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Effective time-period for AGP report generation cannot be greater than 14 days."
      }
    }
  ]
}

Report generation request failed with 500 INTERNAL SERVER ERROR

The server shall return 500 INTERNAL SERVER ERROR if there is an internal server error while processing the request. Here is an example of an error response:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Report generation processing failed."
    }
  ]
}