Basics for JSON in ensemble

For basic JSON-to-HL7/XML work in Ensemble, these concepts and patterns are a good starting point:

• If the input is a JSON file, you can use a file-based service such as EnsLib.File.PassthroughService, which reads the file into an Ens.StreamContainer. That stream can then be routed to a business process or transformation for conversion to HL7. [1]
• Because Ens.StreamContainer is not an HL7 object, routing is typically done with a General Message Routing Rule using Ens.StreamContainer as the message class. In the DTL, use Ens.StreamContainer as the source type and EnsLib.HL7.Message as the target type. [1]
• For simple JSON structures, you may not need a custom business service or a BPL; a passthrough file service plus DTL can be enough to create an HL7 message from JSON input. [1]

A common approach for JSON handling is to define a class that represents the JSON structure:

• One example described is creating a class for the JSON message structure, receiving JSON in a business service, converting it into that class, and then passing the object to a business process where a transform converts it to HL7. [1]
• An example JSON message class extends Ens.Request and contains properties matching the JSON fields, such as MessageId, ControlId, AppointmentID, PatientInfo, and nested object properties like PatientResources and ProviderResources. [1]
• Another recommendation is to create a new request class to hold values extracted from a JSON proxy object, then send that request into a router and use a DTL to transform that request class into the target HL7 message. [2]

For parsing JSON content, the examples in the retrieved material show these patterns:

• If the inbound payload is a stream, read the content into a string and then parse it with %FromJSON. One example shows:
  • read the stream content,
  • call SET tReq = {}.%FromJSON(tContent),
  • then extract fields from the resulting dynamic object. [1]
• If you already use {} to assign a JSON object, then the value is already a %Library.DynamicObject; in that case, calling %FromJSON on it again is unnecessary. [3]
• If the JSON is stored as a string literal, it must be escaped correctly before calling %FromJSON. An example that worked was:
  
  Set Jsonobj="{""Doctype"":""ADT^A01"",""PatientId"":""123"",""PatientName"":""Alex""}"
  
  followed by:
  
  set dynmicobj={}.%FromJSON(Jsonobj) [3]

For converting JSON to HL7, the material points to DTL-based mapping as the key concept:

• After the JSON is available either as a stream, dynamic object, or custom request object, a DTL can map JSON fields into an EnsLib.HL7.Message. [1][2]
• One example used JSON input like:
  
  {"Doctype":"ADT^A01","PatientId":"123","PatientName":"Alex"}
  
  and mapped it into an HL7 message using BPL and DTL. [1]
• Another example used a simple patient JSON document, fed it through EnsLib.File.PassthroughService, then in DTL set default HL7 values and populated PID fields, successfully creating an HL7 message from the JSON. [1]

If you are deciding between dynamic objects and classes for JSON, two options were suggested:

• Use dynamic-object APIs such as %Get() / %GetNext() to read JSON and manually populate the HL7 message. This is described as straightforward, but it requires careful initialization of expected values. [4]
• On IRIS, another option mentioned is to define intermediate data-model classes extending %JSON.Adaptor, so JSON is read directly into objects before mapping into HL7. This was described as easier to maintain and troubleshoot when structures change. [4]

For XML-related basics:

• Ensemble provides DataTransform as a built-in message DOCTYPE converter with a graphical interface, and it can convert between XML and HL7 structures. [5]
• For HL7-to-XML, one example uses EnsLib.HL7.Util.FormatSimpleXMLv2 to write an XML representation of an HL7 message into a stream. [6]
• For XML-to-JSON, one approach is to correlate XML into classes with %XML.Reader and then write JSON from the object using %ZEN.Auxiliary.jsonProvider. [7][8]

If you want a simple beginner path for your use case, the retrieved examples suggest this flow:

1. Use EnsLib.File.PassthroughService or an HTTP inbound service to receive the JSON. [1]
2. Represent the JSON either as:
   • an Ens.StreamContainer,
   • a dynamic object from %FromJSON,
   • or a custom request class that mirrors the JSON fields. [1][2][3]
3. Route the message using a General Message Routing Rule if the source is not an HL7 virtual document. [1]
4. Use DTL to map the JSON-derived source into EnsLib.HL7.Message or another target format such as XML. [1][5]

If your input is a simple single JSON object, the examples indicate this can be done without building a custom service or BPL. If the input is more complex, such as a JSON array or batch of records, one example notes that you would need a BPL to process that. [1]

Sources: