SDA Documents

Information in SDA format is represented by an object that consists of instances of HS.SDA3.PatientOpens in a new tab, HS.SDA3.EncounterOpens in a new tab, and other classes. These classes are XML-enabled.

This topic describes:

Customizing the SDA describes the options available to customize and extend the SDA.

Note:

SDA, when used in this document, refers to the HS.SDA3 classes. HS.SDA classes are also present in your instance, but these are for backward compatibility only.

The Basic XML Structure of an SDA Document

The major sections in an SDA document are as follows:

<Container>
  <Patient/>
  <Encounters/>
  <AdvanceDirectives/>
  <Alerts/>
  <Allergies/>
  <Appointments/>
  <Problems/>
  <Diagnoses/>
  <Documents/>
  <LabOrders/>
  <RadOrders/>
  <OtherOrders/>
  <Medications/>
  <Vaccinations/>
  <Observations/>
  <PhysicalExams/>
  <Procedures/>
  <FamilyHistories/>
  <IllnessHistories/>
  <SocialHistories/>
  <CustomObjects/>
  <Referrals/>
  <ClinicalRelationships/>
  <ProgramMemberships/>
  <MemberEnrollments/>
  <MedicalClaims/>
  <GenomicsOrders/>
  <CarePlans/>
  <HealthConcerns/>
  <Goals/>
  <SocialDeterminants/>
</Container>

The following rules apply to an SDA document:

There is a single <Patient>.
<Patient> is required and must be the first section that appears (after properties of the <Container> such as <Action>, <EventDescription>, or <SendingFacility>, see the class reference for specific details).
All sections other than <Patient> are optional.

All sections other than <Patient> may contain multiple entries, for example:

<Procedures>

   <Procedure>
        ...
   </Procedure>

   <Procedure>
        ...
   </Procedure>

</Procedures>

The <Encounters> section, if included, must appear directly after the <Patient> section.
All other sections may appear in any order.
Any entry may optionally reference an encounter number. In this case, <Encounters> must be included and must contain an <Encounter> with that <EncounterNumber>.
Some sections may also include an <ActionCode> or <ActionScope> to indicate that some action relative to persistence should be performed. In HealthShare Unified Care Record, these elements direct the system to perform some action when it stores the SDA, while in InterSystems IRIS for Health, you can direct that some action be taken against persisted SDA. For example, an <ActionCode> of D deletes a matching entry from the Unified Care Record. See the class reference for specific details relevant to each SDA section.

The Patient in SDA

The HS.SDA3.PatientOpens in a new tab class represents the patient. This class contains properties that store information such as the following:

Demographic information and other basics, for example: name, a list of addresses, gender, marital status, race, religion, and so on
Patient numbers

The following table shows the properties of HS.SDA3.PatientOpens in a new tab. Some of these properties are simple (for example, strings), some are complex objects which contain properties of their own, and some are lists of complex objects:

Properties in HS.SDA3.Patient

Simple Property	Complex Object	List of Complex Objects
ActionCode*	BirthGender	Addresses
BirthOrder	BirthPlace	Aliases
BirthTime	Citizenship	Organizations
BlankNameReason	ContactInfo	OtherLanguages
Comments	CreatedBy	PatientNumbers
CommunicationPreference	DeathDeclaredBy	PriorPatientNumbers
CreatedOn	EnteredAt	Providers
DeathLocation	EnteredBy	Races
DeathTime	EthnicGroup	SupportContacts
EnteredOn	Extension	(CustomPairs)
ImmunizationRegistryStatus	FamilyDoctor
ImmunizationRegistryStatusEffectiveDate	Gender
InactiveMRNs	MaritalStatus
IsDead	MothersFullName
IsProtected	Name
MothersMaidenName	Occupation
MPIID	PrimaryLanguage
ProtectedEffectiveDate	PublicityCode
PublicityEffectiveDate	Race
UpdatedOn	Religion

*A <Patient> SDA section may include an <ActionCode>. An <ActionCode> of D instructs HealthShare Unified Care Record to delete a patient with the matching MRN. An <ActionCode> of R instructs Unified Care Record to replace an existing patient with this patient, based on MRN. See the class reference for specific details.

Encounters in SDA

An encounter encompasses all of the medical information related to a specific medical incident. The HS.SDA3.EncounterOpens in a new tab class represents a medical encounter of a patient. Other sections in the SDA, representing orders, procedures, exams and the like can refer to the encounter number, and thus be tied together.

The following table shows the properties of HS.SDA3.EncounterOpens in a new tab, some of which are simple (for example, strings), some of which are complex objects (containing properties of their own), and some of which are lists of complex objects:

Properties in HS.SDA3.Encounter

Simple Property	Complex Object	List of Complex Objects
ActionCode*	AdmissionSource	AttendingClinicians
AccountNumber	AdmissionType	ConsultingClinicians
AssignedBed	AdmitReason	Guarantors
AssignedRoom	AdmittingClinician	HealthFunds
AssignedWard	DiagnosisRelatedGroup	RecommendationsProvided
EmergencyAdmitDateTime	DischargeLocation	Specialties
EncounterMRN	EncounterCodedType	(CustomPairs)
EncounterMRNAA	Extension
EncounterNumber	HealthCareFacility
EncounterType	EnteredAt
EndTime	EnteredBy
EnteredOn	Priority
ExpectedAdmitTime	PublicityCode
ExpectedDischargeTime	ReferringClinician
ExpectedLOAReturnTime	SeparationMode
ExternalId
FromTime
PreAdmissionNumber
PriorBed
PriorRoom
PriorWard
PriorVisitNumber
ToTime
TransferredFromED
UpdatedOn
VisitDescription

*An encounter may also include an <ActionCode> directing HealthShare Unified Care Record to take an action. Possible values include:

D = Delete
E = Delete if Empty
C = Clear All
R = Replace

See the class reference for specific details of the <ActionCodes> for an encounter.

For More Information on SDA Classes

For complete details on the SDA format, see the class reference for HS.SDA3.ContainerOpens in a new tab and the other classes in the HS.SDA3 package.

To access the class reference for the SDA classes:

Either click on the “Class Reference” link in the InterSystems launcher (Windows only), or navigate to the following URL in your browser, using the <baseURL> for your instance: https://<baseURL>/csp/documatic/%25CSP.Documatic.cls.
Log in, if required.
Using the drop-down list at the top of the left-hand pane, change to the HSLIB namespace.
Clear the Percent Classes check box to reduce visual clutter.
Drill down the hierarchy of package names to HS, then SDA3 and then to the class of interest.

You may also view the XML document structure for any SDA class:

In the Management Portal, select an Edge Gateway namespace and navigate to Home > Interoperability > Interoperate > XML > XML Schema Structures.
In the HS.SDA3 schema, select the name of the class whose structure you want to view.

Tip:

To navigate through the HS.SDA3 XML schema, you may find it easiest to select Container, and then drill down from there.

The “CDA and SDA Annotations” feature provides an alternate view into the SDA class structure.

Creating an SDA Stream from SDA Objects

Note:

This section describes a methodology that will accommodate an SDA of any size. Rather than instantiate an entire patient record as an SDA object (which in the context of HealthShare Unified Care Record may contain thousands of encounters), the approach described here instantiates only the individual sections, and then constructs the SDA stream manually. If you are certain that your SDA is small, then you can instantiate the entire SDA as an object and write the stream directly.

If you have a set of SDA objects and you wish to combine them to produce an SDA stream, use the following methodology:

Instantiate a new stream.
Write the <Container> opening tag to the stream.
For the Patient object, which must come first, use the ToQuickXML()Opens in a new tab method of the SDA object to write the object to the stream as XML.
For subsequent objects, which should be grouped by type (Encounter, LabOrder etc.), use the StartXMLList()Opens in a new tab method of the SDA object to write the opening tag for the collection, for example, <Encounters>. Remember that <Encounters>, if included, must come directly after <Patient>.
Use the ToQuickXML()Opens in a new tab method to write each object of that type to the stream.
When finished with a collection of a particular type, use the EndXMLList()Opens in a new tab method to write the closing tag for the collection.
Repeat for other collections.
When finished, write the </Container> closing tag.

Note:

ToQuickXML()Opens in a new tab will not output tags if the content in the tag is double quotes. To generate XML that includes double quotes use XMLExportToString()Opens in a new tab or XMLExportToStream()Opens in a new tab instead.

Streamlet Matching (Deduplication) in Unified Care Record Edge Gateways

In a Unified Care Record Edge Gateway, SDA is stored as streamlets by Information Type.

Each streamlet classOpens in a new tab has distinct matching criteria defined in that class's MATCHINGS parameter. HealthShare uses the MATCHINGS parameter in two different ways:

At the Edge Gateways, streamlet matching is used to deduplicate inbound data. Streamlet matching logic allows HealthShare to determine whether an inbound streamlet represents a new set of data for a given patient (MRN), or whether the data in the streamlet is an update to data that has already been stored for that patient.
At the Access Gateway, the MATCHINGS parameter is used to aggregate data across the various MRNs associated with a given MPIID. Aggregation is not discussed in this section. For more information on aggregation, consult the class reference for the HS.SDA3.Streamlet.Abstract.Aggregate() method.

This section describes:

Deduplication Logic

When inbound data arrives at an Edge Gateway, it is converted into SDA and stored as streamlets. Before streamlets are stored, they are deduplicated. Deduplication involves comparing the inbound streamlet to the stored streamlets of the same type for a given MRN (understood as facility^AA^MRN).

If no matching stored streamlet is found, the inbound streamlet is recognized as new, and it is stored as a new record.
If a matching streamlet is found, the inbound streamlet is recognized as an update to an existing streamlet, and the existing streamlet is updated with the inbound data.

The sections below describe:

Which Streamlets are Compared for Deduplication?

Only streamlets of the same type for the same MRN are ever compared.
If two streamlets have the same Encounter Number, they are compared.
If neither streamlet has an Encounter Number, they are compared.

How Are Compared Streamlets Matched?

If the streamlet type is Encounter, just match on EncounterNumber.
If a set of compared streamlets have the same ExternalId, then they are an automatic match.
In the absence of an external identifier, an evaluation of the MATCHINGS parameter specification for the streamlet type determines if two streamlets match.

Summary of Deduplication Logic

Streamlets are never deduplicated across encounters.
Encounter streamlets match if they have the same EncounterNumber.
Streamlets of a given type for the same MRN match if they have the same ExternalId (external identifier).
For streamlets without an external identifier, they match if they pass the MATCHINGS evaluation.

In tabular form, streamlets with the same facility^AA^MRN and the same streamlet type match each other in the following five cases:

Same Encounter Number	No Encounter Number	Same External ID	No External ID	Pass MATCHINGS




Encounter streamlets only

How the MATCHINGS Parameter Works

The MATCHINGS parameter takes the form:

MatchList1 || MatchList2

where each MatchList item takes the form:

MatchType/MatchProp1,MatchProp2,.../NullProp1,NullProp2,....

These elements are defined as follows:

MatchType is an arbitrary name for the matching specification.
Each MatchProp is the name of a property in the SDA streamlet class whose value must match in both streamlets. In some complex cases, this can be a transient or computed property. Where there are two or more MatchProp elements specified, all of the properties must match (logical AND).
NullProp is the name of a property where an empty value counts as a match. Where there are two or more NullProp elements, a match on any combination of them is sufficient (logical OR).
An asterisk after either a MatchProp or NullProp indicates that the property is a CodeTableDetailOpens in a new tab. Both the Code and SDACodingStandard (code system) property values must match.

For a MatchType to pass evaluation, both the MatchProp and NullProp must match (logical AND).

Consider the following MATCHINGS parameter in a hypothetical custom Allergy streamlet class:

"ALG/Allergy*/FromTime,AllergyCategory* || ZATC/ATCCode*/FromTime"

In this case, HealthShare will attempt to match the Allergy streamlets according to the following criteria:

First try MatchType: ALG
- Match on the AllergyOpens in a new tab property, which is a CodeTableDetail requiring a match on both the code and code system values.
- If the FromTime property or AllergyCategoryOpens in a new tab CodeTableDetail property have values in both streamlets, those values must match as well.
If ALG fails, try MatchType: ZATC
- Match on the ATCCode CodeTableDetail property.
- If the FromTime property has a value in both streamlets, match on FromTime as well.

If either ALG or ZATC pass evaluation, then the streamlets match, and an update is performed.

The MATCHINGS parameter may be modified, as described in Customizing the SDA.

Note:

Aggregation of data across MRNs for an MPIID at the Access Gateway's aggregation cache also use the MATCHINGS parameter. Encounter Number is not a criterion for aggregation, because different MRNs from different facilities are being compared. For more information on this process, consult the class reference for the HS.SDA3.Streamlet.Abstract.Aggregate() method.