Skip to main content
Previous sectionNext section

ObjectScript Applications

The FHIR server’s Service (HS.FHIRServer.Service) allows an ObjectScript application to perform CRUD operations on the server directly without going over HTTP. The same method, DispatchRequest( ), that the REST handler calls to send a FHIR request to the server can be used by an ObjectScript application to send a request to the server. If an application wants to manipulate the server’s FHIR data, it would send a request through the Service and then manipulate the Json property of the response. For more information about manipulating a server’s FHIR data, see Working with FHIR Data.

Your ObjectScript application can also validate a resource.

Note:

Because the FHIR server’s Service is not, in most cases, used by Health Connect, the following methods of performing CRUD operations do not apply.

GET Resources

Your ObjectScript application can use the server’s Service to retrieve resources. For example, assuming 178.16.235.12 is the IP address of InterSystems server and 52783 is the superserver port, a REST call might be:

GET http://178.16.235.12:52783/fhirapp/namespace/fhir/r4/patient/1

Using ObjectScript to access the same endpoint looks like:

set url = "/fhirapp/namespace/fhir/r4"
set fhirService = ##class(HS.FHIRServer.Service).EnsureInstance(url)
set request = ##class(HS.FHIRServer.API.Data.Request).%New()
set request.RequestPath = "/Patient/1"
set request.RequestMethod = "GET"
do fhirService.DispatchRequest(request, .response)
Copy code to clipboard

In this example, the response is a data object (HS.FHIRServer.API.Data.Response) with the JSON response represented in a dynamic object.

Note:

The first request to the server must instantiate the FHIR service by calling the EnsureInstance method. It does not cause problems to make this call before every request, but it takes a miniscule amount of time to check whether the service has been modified.

POST Resources

You can also post data to the FHIR server programmatically. In the following example, suppose the application is creating a Patient resource that is described in a JSON object in the file MyPatient.json. The ObjectScript code might look like:

set url = "/csp/fhirapp/namespace/fhir/r4/"
set fhirService = ##class(HS.FHIRServer.Service).EnsureInstance(url)
set request = ##class(HS.FHIRServer.API.Data.Request).%New()
set request.RequestPath = "/Patient"
set request.RequestMethod = "POST"
set request.Json = {}.%FromJSON("c:\resources\MyPatient.json")
do fhirService.DispatchRequest(request, .response)
Copy code to clipboard

In this example, the source of the JSON stored in the request could have come from a dynamic object in your application rather than an external file.

Bypassing the Service

A server-side application can call the methods of an Interactions subclass directly instead of submitting programmatic requests via the Service. For example, an application could call the Interactions subclass’ Add method directly rather than sending a POST request to the Service. This is especially useful if the server-side application needs to perform actions that are prohibited by the Service. For example, if the server’s metadata configures the endpoint as read-only, programmatic requests to the Service cannot create resources. However, using method calls to the Interactions subclass, a server-side application could update the storage strategy with resources, effectively bypassing the restrictions enforced by the Service.

Programmatic calls to methods of the Interactions class pass FHIR data as dynamic objects. For more information about working with this data, see FHIR Data and Dyanmic Objects.

Handling FHIR Data as XML

When you use a REST client to perform CRUD operations on the FHIR server, the FHIR server automatically accepts or returns FHIR data as XML based on the incoming request. However, when you are performing CRUD operations programmatically, all data going into the FHIR service must be in JSON format. Likewise, all data returned by the service is in JSON format. The FHIR server provides helper methods to convert XML to JSON and JSON to XML.

To send XML data into the FHIR service, put the XML into a stream object and send it to the HS.FHIRServer.Service.StreamToJSON() method, specifying that the format is XML. For example, the following code turns the XML payload into a JSON request that can be passed to the FHIR service:

set url = "/csp/fhirapp/namespace/fhir/r4/"
set fhirService = ##class(HS.FHIRServer.Service).EnsureInstance(url)
set request = ##class(HS.FHIRServer.API.Data.Request).%New()
set request.Json= fhirService.StreamToJSON(MyStream,"XML")
Copy code to clipboard

To convert a JSON response from the FHIR service into XML, use the HS.FHIRServer.Util.JSONToXML.JSONToXML() method.

Handling FHIR Data as a Stream

The HS.FHIRServer.Service.StreamToJSON() method converts an XML or JSON stream into a JSON object so it can be passed to the FHIR service as part of a request. The FHIR service cannot handle a stream directly. The method accepts two arguments: the stream and the format of the data in the stream. For example, the following lines of code turn a JSON stream into a JSON object so it can be sent to the FHIR service:

set url = "/csp/fhirapp/namespace/fhir/r4/"
set fhirService = ##class(HS.FHIRServer.Service).EnsureInstance(url)
set request = ##class(HS.FHIRServer.API.Data.Request).%New()
set request.Json= fhirService.StreamToJSON(MyStream,"JSON")
Copy code to clipboard

For XML streams, simply pass XML as the second argument.

Validating FHIR Resources

Your ObjectScript application can programmatically validate a resource against the FHIR server’s metadata without using the FHIR $validate operation as long as the resource is represented as a dynamic object. For example, the following code validates a Patient resource against the server’s FHIR Release 4 metadata, which includes the schema for the Patient resource. When calling the LoadSchema method, you can specify the common name of the FHIR version (for example, R4 or STU3) or the name of the server’s base metadata (for example, HL7v40 or HL7v30).

// Put JSON representation of Patient resource into a dynamic object
set patient = ##class(%DynamicObject).%FromJSON("c:\localdata\myPatient.json")

//Validate the patient resource
set schema = ##class(HS.FHIRServer.Schema).LoadSchema("R4")
set resourceValidator = ##class(HS.FHIRServer.Util.ResourceValidator).%New(schema)

do resourceValidator.ValidateResource(patient)
Copy code to clipboard