Read Relay Operation

Experimental

This is an early access feature and is subject to change.

OPERATION: POST [base]/[Resource]/$read-relay

The Read Relay operation is used to relay requests to another FHIR server.

Supported Resources

This operation has been implemented for the following resources:

• Location
• Organization

Workflow

Authorization

This operation will require the application obtain authorization to read the resource to relay using one of the following SMART clinical scopes.

• v1: [patient|user|system]/[Location|Organization].[read|*]
• v2: [patient|user|system]/[Location|Organization].[r] (future)

Parameters

Use	Name	Cardinality	Type	Documentation
IN	id	1..1	Reference	The ID assigned to the resource.
IN	target-system	1..1	string	The unique ID assigned to the external FHIR server.
OUT	resource	0..1	Resource	The returned resource, if found.
OUT	outcome	1..1	OperationOutcome	The outcome of the operation. On success this will provide a success statement or warnings related to the change. If the operation was unsuccessful, the OperationOutcome will include the reason for the failure.

Examples

Production

curl -X POST 'https://fhir.netsmartcloud.com/v4/Organization/$read-relay' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Preview

curl -X POST 'https://fhirtest.netsmartcloud.com/v4/Organization/$read-relay' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d @payload.json

Payloads

Sample Read Relay Payload

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "id",
      "valueReference": {
        "reference": "Organization/[id]",
        "type": "Organization"
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    }
  ]
}

Sample Read Relay Response Payloads

Read Relay Success

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "id",
      "valueReference": {
        "reference": "Organization/[id]",
        "type": "Organization"
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    },
    // outcome of request
    {
      "name": "resource",
      "resource": {
        // The matching Organization resource, if found
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "details": {
              "text": "Success message"
            }
          }
        ]
      }
    }
  ]
}

Invalid Read Relay Payload or Other Unprocessable Request

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Exception message"
      }
    }
  ]
}

Rejections or Other Read Relay Processing Errors

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "id",
      "valueReference": {
        "reference": "Organization/[id]",
        "type": "Organization"
      }
    },
    {
      "name": "target-system",
      "valueString": "ac97a53f-54cc-4d73-8f9a-ffae5f503d78"
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "processing",
            "details": {
              "text": "status note"
            }
          }
        ]
      }
    }
  ]
}

Errors

Errors will be reported within an OperationOutcome and could include:

Issue	Description	HTTP Status
T.B.D.	T.B.D.	400 Bad Request
T.B.D.	T.B.D.	500 Internal Server Error
T.B.D.	T.B.D.	501 Not Implemented