Skip to main content

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:

A separate chapter, “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:

  1. There is a single <Patient>.

  2. <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).

  3. All sections other than <Patient> are optional.

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

    <Procedures>
    
       <Procedure>
            ...
       </Procedure>
    
       <Procedure>
            ...
       </Procedure>
    
    </Procedures>
  5. The <Encounters> section, if included, must appear directly after the <Patient> section.

  6. All other sections may appear in any order.

  7. Any entry may optionally reference an encounter number. In this case, <Encounters> must be included and must contain an <Encounter> with that <EncounterNumber>.

  8. 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:

  1. 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.

  2. Log in, if required.

  3. Using the drop-down list at the top of the left-hand pane, change to the HSLIB namespace.

  4. Clear the Percent Classes check box to reduce visual clutter.

  5. 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:

  1. In the Management Portal, select an Edge Gateway namespace and navigate to Home > Interoperability > Interoperate > XML > XML Schema Structures.

  2. 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:

  1. Instantiate a new stream.

  2. Write the <Container> opening tag to the stream.

  3. 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.

  4. 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>.

  5. Use the ToQuickXML()Opens in a new tab method to write each object of that type to the stream.

  6. 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.

  7. Repeat for other collections.

  8. When finished, write the </Container> closing tag.

Streamlet Matching

Each streamlet class has distinct matching criteria defined in that class's MATCHINGS parameter, which is inherited from HS.SDA3.Streamlet.Abstract. Streamlet matching logic allows HealthShare to determine whether or not a streamlet is new, or an update to existing data. Whether or not two streamlets will be compared for matching and deduplication depends on their EncounterNumber properties:

  • In the event that two streamlets have differing EncounterNumbers, or one has a value for EncounterNumber and the other does not, the streamlets are not eligible for comparison.

  • In the event that both streamlets have the same EncounterNumber, they are eligible for comparison.

  • In the event that neither streamlet has a value for EncounterNumber, they are eligible for comparison.

Given eligible streamlets, the matching process happens in three phases:

  1. First, when a streamlet is ingested by an Edge Gateway, its data is compared to streamlets of the same type with the same MRN. In a system with multiple Edge Gateways, comparisons are handled by the Access Gateway's aggregation cache. For more information on this process, consult the class reference for the HS.SDA3.Streamlet.Abstract.Aggregate() method.

  2. If it contains an external identifier, this is used to match it to other streamlets of the same type with that external identifier.

  3. If neither of the above checks yield a match, HealthShare checks each streamlet-specific MATCHINGS key-value pair against other records of the same streamlet type.

In the event that none of these checks yield a match, the streamlet is recognized as new. If any of the checks yield a match, the streamlet is recognized as an update of an existing streamlet and aggregated together with it. This is called deduplication. The MATCHINGS parameter may be modified, as described in “Customizing the SDA” later in this book.

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 type.

  • MatchProp is the name of a property in the SDA streamlet class used for matching. In some complex cases, this can be a transient or computed property. Where there are two or more MatchProp elements, matching must be performed on all of them.

  • NullProp is the name of a property used for matching which is optional. An empty NullProp counts as matching anything. Where there are two or more NullProp elements, matching is performed on any combination of them.

  • An asterisk after either a MatchProp or NullProp indicates that the element is a CodeTableDetail to be matched on Code and SDACodingStandard.

Consider the following code from a hypothetical custom Allergy streamlet:

Parameter MATCHINGS = "ALG/Allergy*/FromTime,AllergyCategory* || 
ZATC/ATCCode*/FromTime";

In this case, Unified Care Record will attempt to match according to the following criteria in order:

  1. Match on Allergy, which is a CodeTableDetail. Optionally, match on FromTime or AllergyCategory–also a CodeTableDetail if either exists.

  2. Match on ATCCode, which is a CodeTableDetail. Optionally, match on FromTime if it exists.

FeedbackOpens in a new tab