Skip to main content

Providing and Registering Documents to an XDS Document Repository

InterSystems products can provide and register a document to an XDS repository via the IHE “XDS.b Provide and Register Document Set” transaction. If the document uses the Clinical Document Architecture (CDA), then InterSystems can extract the document metadata directly from the document. For all other kinds of documents, for example PDF files, you must provide the document metadata in the message.

Provide and Register a CDA Document

InterSystems products can provide and register a CDA document to a document repository within the Affinity Domain via the IHE “XDS.b Provide and Register Document Set” transaction (PnR). InterSystems products can extract the metadata from the document itself.

If an MPI ID is not included in the Provide and Register, then a PIX Query is automatically performed. The PIX query uses the extracted MRN to get the MPI ID of the patient.

If the CDA is replacing another document (<ReplacementContext> is specified in the Provide and Register), then an XDS query is performed to get the unique ID of the document to be replaced.

This section includes:

CDA Provide and Register Message Trace

The following diagram is an annotated XDS provide and register message trace for a CDA document, showing both the optional search request and replacement query.

The test service shown in the diagram is a simple message router. Trace operations is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below.

CDA Provide and Register Procedure

  1. You provide a Provide and Register RequestOpens in a new tab with minimal metadata to the InterSystems Document Source.

    The minimum required document metadata includes the <MIMEType>, <FormatCode>, and the file contents in <BodyCharacter>. When you open the file to include in <BodyCharacter>, be sure to open it as the correct file type, for example, open a CDA document in XML format as a text file.

    When a new Provide and Register Request is created, it automatically generates a document unique ID.

  2. The InterSystems Document Source extracts the document metadata from the CDA and uses it to build a complete IHE “ProvideAndRegisterDocumentSetRequest”:

    1. If an MPI ID is not included in the Provide and Register request, the InterSystems Document Source extracts the MRN and assigning authority from the CDA and performs a PIX query using the procedure described earlier.

    2. If the Provide and Register indicates that this document should replace an existing document, the Document Source performs an XDS query to get the ID of the document to be replaced in the repository. The Provide and Register may include a variety of conditions for the replacement context, but the MPI ID and default entry status of “approved” are included by default if not specified.

    3. Using the XSL transformation specified in the DocumentTransform setting, the Document Source extracts additional metadata from the CDA and uses it to populate the Provide and Register request.

  3. The InterSystems Document Source forwards the Provide and Register request to the XDS document repository endpoint on another system that is named in the XDSbRepositoryServiceName setting. The Provide and Register contains both the extracted document metadata and the document itself (the contents of <BodyCharacter>) as an MTOM attachment.

    Note:

    Because the InterSystems Document Source uses the XDSbRepositoryServiceName setting to determine where to send documents, if you post documents to more than one repository, then you must have a separate document source operation for each repository. Use a message router to determine which document source operation to send the document to, based on whatever criteria you use to determine the appropriate repository for a particular document.

  4. The document repository on the other system stores the document and updates the Affinity Domain’s document registry with the document metadata provided in the request.

  5. The document repository on the other system responds with a success (or failure) message.

  6. The InterSystems Document Source returns an XML message of the “RegistryResponse” variety, indicating success or failure. If the transaction fails before the document is sent to the registry, the InterSystems Document Source returns null.

CDA Provide and Register Components and Settings

Components and Settings Used in Provide and Register of a CDA Document
Component Setting
Business Hosts Document Source: HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab
Business Hosts PIX Consumer: HS.IHE.PIXv3.Consumer.OperationsOpens in a new tab
  • if needed to get MPI ID

Business Hosts Document Consumer: HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab
  • if <Replacement Context> is specified in the message

Production Settings DocumentTransform in the Document Source
Production Settings XDSbRepositoryServiceName in the Document Source
Production Messages HS.Message.IHE.XDSb.ProvideAndRegisterRequestOpens in a new tab
Production Messages HS.Message.XMLMessageOpens in a new tab:
  • RegistryResponse

Production Messages HS.Message.PatientSearchRequestOpens in a new tab (if PIX)
Production Messages HS.Message.PatientSearchResponseOpens in a new tab (if PIX)
Production Messages HS.Message.IHE.XDSb.QueryRequestOpens in a new tab (if replacement)
Production Messages HS.Message.IHE.XDSb.QueryResponseOpens in a new tab (if replacement)

Minimum Document Metadata when Sending to InterSystems products.

(See IHE Metadata Requirements for Third Party Systems for details on minimum IHE requirements.)

Open the file as the correct type, for example, open an XML as a text file.

Metadata:

  • <ContentTypeCode> — indicating the content type of the document

  • <SourceId> — the OID of the facility that is providing the document

  • <MIMEType> — usually text/xml

  • <FormatCode> — indicating the document type

  • <BodyCharacter> — containing the file contents

  • <HealthCareFacilityTypeCode> — indicating the facility type

  • <PracticeSettingCode> — indicating the practice type

XSL Transformations IHE/XDSb/Version1/DocumentToProvideAndRegister.xsl
Service Registry Entries XDSb.Repository
Service Registry Entries PIXv3.Manager (if PIX)
Service Registry Entries XDSb.Registry (if replacement)
External IHE Actor Endpoint XDS Document Repository
External IHE Actor Endpoint PIX Manager (if PIX)
External IHE Actor Endpoint XDS Document Registry (if replacement)

CDA Provide and Register Example

The method below opens a CDA file and provides the minimum metadata required to provide and register the document. To use the method, go to HS.IHE.XDSb.DocumentSource.Operations in your Foundation production and change the value on the XDSbConsumerOperations setting from HS.IHE.XDSb.Consumer.Operations to HS.HC.IHE.XDSb.Consumer.Operations.

 ClassMethod CDAPnR()
 {
    /// Provide and Register a CDA document
 
    // Create the Provide and Register message, which automatically assigns a 
    // document unique ID
    Set tMessage=##class(HS.Message.IHE.XDSb.ProvideAndRegisterRequest).%New()
 
    // Identify the message source
    Set tMessage.SourceId="1.3.6.1.4.1.21367.1"
 
    // Create a document instance to hold the document metadata
    Set tDocument = ##class(HS.Message.IHE.XDSb.Document).%New()
 
    // Open the document file and insert it into <BodyCharacter> (for non-CDA, 
    // this is <Body>). The document will become an MTOM attachment in the 
    // outbound message. In this case, we are providing a Consolidated CDA (C-CDA) 
    //in XML, so open the file as a text file.
    Set tFile = ##class(%File).%New()
    Set tFile.Name="C:\wtemp\testccda.xml"
    Do tFile.Open("R")
    Do tFile.Rewind()
    Do tDocument.BodyCharacter.CopyFrom(tFile)
    Kill tFile
 
    // Set the required minimum document metadata. For CDA, the <MIMEType> is "text/xml"
    Set tDocument.MimeType="text/xml"
    Set tDocument.FormatCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
          "urn:hl7-org:sdwg:ccda-structuredBody:1.1",
          "1.3.6.1.4.1.19376.1.2.3",
          "Consolidated CDA R1.1 Structured Body Document")
    Set tDocument.HealthcareFacilityTypeCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
          "22232009”,”2.16.840.1.113883.6.96","Hospital")
    Set tDocument.PracticeSettingCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
          "394802001","2.16.840.1.113883.6.96","General Medicine")
 
    // This is optional and controls replacement. If you specify a ReplacementContext,
    // then an XDS.B query is performed to obtain the document unique ID
    // of documents that match the context.
    //
    // In the case below, it is looking for documents that match the specified 
    // format code. You may include other context items as well. InterSystems 
    // automatically adds the Patient ID and the Status of "approved"
    // to the context.
    Set tContext = ##class(HS.Message.IHE.XDSb.QueryItem).CodedValue(
           "$XDSDocumentEntryFormatCode",
           "urn:hl7-org:sdwg:ccda-structuredBody:1.1",
           "1.3.6.1.4.1.19376.1.2.3")
 
    Do tDocument.ReplacementContext.Insert(tContext)
 
    /// Insert the document metadata into the message
    Do tMessage.Documents.Insert(tDocument)
 
    /// Send to the routing service (or directly to 
    /// HS.IHE.XDSb.DocumentSource.Operations)
    Write ##class(HS.Test.Service).SendSync(tMessage,.rr)
 
    quit
 }

Provide and Register a Non-CDA Document

InterSystems products can provide and register any kind of document to a document repository within the Affinity Domain via the IHE “XDS.b Provide and Register Document Set” transaction (PnR). You must provide your InterSystems product with the document metadata.

If the CDA is replacing another document (<ReplacementContext> is specified in the Provide and Register), then an XDS query is performed to get the unique ID of the document to be replaced.

This section includes:

Non-CDA Provide and Register Message Trace

The following diagram is an annotated XDS provide and register message trace for a non-CDA document, that includes the query request for replacement context.

The test service shown in the diagram is a simple message router. Trace operations is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below.

Provide and Register a Non-CDA Document Procedure

InterSystems products can provide and register any clinical document (for example a PDF) to a document repository within the Affinity Domain via the IHE “XDS.b Provide and Register Document Set” transaction (PnR).

  1. You provide a Provide and Register RequestOpens in a new tab with complete document metadata to the InterSystems Document Source. You must include the MPI ID of the patient in <SourcePatientId> in the message. If you only have the MRN, perform a PIX query to get the MPI ID before creating the message.

    The minimum required document metadata includes the <MIMEType>, <FormatCode>, <Body>, <SourcePatientInfo>, and author information. When you open the file to include in <Body>, be sure to open it as the correct file type, for example open a PDF file as a binary.

    When a new Provide and Register Request is created, it automatically generates a document unique ID.

  2. If the Provide and Register indicates that this document should replace an existing document, the Document Source performs an XDS Query to get the ID of the document to be replaced in the repository. The Provide and Register may include a variety of conditions for the replacement context, but the MPI ID and default entry status of “approved” are included by default if not specified.

  3. The InterSystems Document Source transforms the message into an IHE “ProvideAndRegisterDocumentSetRequest” using the XSL transformation specified in the DocumentTransform setting.

  4. The InterSystems Document Source forwards the Provide and Register request to the XDS document repository endpoint on another system that is named in the XDSbRepositoryServiceName setting. The Provide and Register contains both the document metadata and the document itself (the contents of <Body>) as an MTOM attachment.

  5. The XDS document repository on the other system stores the document and updates the Affinity Domain’s XDS document registry with the document metadata provided in the request.

  6. The XDS document repository on the other system responds with a success (or failure) message.

  7. The InterSystems Document Source returns an XML message of the “RegistryResponse” variety, indicating success or failure. If the transaction fails before the document is sent to the registry, the InterSystems Document Source returns null.

Non-CDA Provide and Register Components and Settings

Components and Settings Used in Provide and Register of a non-CDA Document
Component Setting
Business Hosts Document Source: HS.IHE.XDSb.DocumentSource.OperationsOpens in a new tab
Business Hosts Document Consumer: HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab
  • if <Replacement Context> is specified in the message

Production Settings XDSbRepositoryServiceName in the Document Source
Production Messages HS.Message.IHE.XDSb.ProvideAndRegisterRequestOpens in a new tab
Production Messages HS.Message.XMLMessageOpens in a new tab:
  • RegistryResponse

Production Messages HS.Message.IHE.XDSb.QueryRequestOpens in a new tab (if replacement)
Production Messages HS.Message.IHE.XDSb.QueryResponseOpens in a new tab (if replacement)

Minimum Document Metadata when Sending to InterSystems products

Open the file as the correct type, for example, open a PDF as a binary.

Metadata:

  • <MIMEType> — for example, application/pdf. See iana.orgOpens in a new tab for a complete list of MIME types.

  • <FormatCode> — indicating document type

  • <Body> — containing the file contents

  • <SourcePatientInfo> — patient demographics as HL7 segments

  • <HealthCareFacilityTypeCode> — indicating the facility type

  • <PracticeSettingCode> — indicating the practice type

  • <Author...> (...Institution, ...Role, ...Person, ...Specialty)

XSL Transformations IHE/XDSb/Version1/DocumentToProvideAndRegister.xsl
Service Registry Entries XDSb.Repository
Service Registry Entries XDSb.Registry (if replacement)
External IHE Actor Endpoints XDS Document Repository
External IHE Actor Endpoints XDS Document Registry (if replacement)

Provide and Register a Non-CDA Document Example

The method below generates an XDS provide and register for a PDF document. To use the method, go to HS.IHE.XDSb.DocumentSource.Operations in your Foundation production and change the value on the XDSbConsumerOperations setting from HS.IHE.XDSb.Consumer.Operations to HS.HC.IHE.XDSb.Consumer.Operations.

 ClassMethod CDAPnR2()
 {
   // Create the message, which automatically assigns a document unique ID
   Set tMessage=##class(HS.Message.IHE.XDSb.ProvideAndRegisterRequest).%New()

   // Provide SubmissionSet metadata (see "Note 1" below)
   Set tMessage.PatientId="100000001^^^&1.3.6.1.4.1.21367.2010.1.2.300&ISO"
   Set tMessage.SourceId="1.3.6.1.4.1.21367.2010.1.2.300.2.0"
   Set tMessage.ContentTypeCode = ##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "11488-4","2.16.840.1.113883.6.1","Consultation Note")
   
   // Create a document instance to hold the document metadata
   Set tDocument = ##class(HS.Message.IHE.XDSb.Document).%New()
   
   // Open the document (see "Note 2" below)
   Set tFile = ##class(%Stream.FileBinary).%New()
   Set tFile.Filename="C:\wtemp\testdoc.pdf"
   Do tFile.Rewind()
   Do tDocument.Body.CopyFrom(tFile)
   Kill tFile
   
   // Set the "MIMEType" (see "Note 3" below)
   Set tDocument.MimeType="application/pdf"
   
   // Enter the document metadata (see "Note 4" below)
   Set tDocument.CreationTime="20180821102615-0400"
   Set tDocument.LanguageCode="en-CA"
   
   Set tDocument.ClassCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "26435-8","2.16.840.1.113883.6.1","MOLECULAR PATHOLOGY STUDIES")
   Set tDocument.FormatCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "urn:ihe:iti:xds-sd:pdf:2008","1.3.6.1.4.1.19376.1.2.3","Scanned Documents PDF")
   Set tDocument.HealthcareFacilityTypeCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "OF","2.16.840.1.113883.5.11","Outpatient facility")
   Set tDocument.PracticeSettingCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "394802001","2.16.840.1.113883.6.96","General Medicine")
   Set tDocument.TypeCode=##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "18768-2","2.16.840.1.113883.6.1","CELL COUNTS+DIFFERENTIAL STUDIES")
   
   Do tDocument.ConfidentialityCode.Insert(##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "N","2.16.840.1.113883.5.25","Normal"))
   Do tDocument.EventCodeList.Insert(##class(HS.IHE.XDSb.Types.CodedValue).Create(
       "1.2.840.10065.1.12.1.13","1.2.840.10065.1.12","Review Signature"))
   
   // Patient demographics
   Set tDocument.SourcePatientId="1111222^^^&1.3.6.1.4.1.21367.2010.1.2.310&ISO"
   Do tDocument.SourcePatientInfo.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New(
       "PID-3|1111222^^^&1.3.6.1.4.1.21367.2010.1.2.310&ISO"))
   Do tDocument.SourcePatientInfo.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New(
       "PID-5|Smith^James^"))
   Do tDocument.SourcePatientInfo.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New(
       "PID-7|20000930"))
   Do tDocument.SourcePatientInfo.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New("PID-8|M"))
   Do tDocument.SourcePatientInfo.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New(
       "PID-11|123 Money Street^^Somewhere^SW^"))
   
   // Document author
   Set tAuthor= ##class(HS.IHE.XDSb.Types.Author).%New()
   Set tAuthor.AuthorPerson="John Smith"
   Do tAuthor.AuthorInstitution.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New("Johns Hopkins"))
   Do tAuthor.AuthorRole.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New("Role"))
   Do tAuthor.AuthorSpecialty.Insert(##class(HS.IHE.XDSb.Types.SlotValue).%New("Specialty"))
   Do tDocument.Author.Insert(tAuthor)
   
   // Optional replacement context (see "Note 5" below)
   Set tContext = ##class(HS.Message.IHE.XDSb.QueryItem).CodedValue("$XDSDocumentEntryEventCodeList",
      "1.2.840.10065.1.12.1.13","1.2.840.10065.1.12")
   Do tDocument.ReplacementContext.Insert(tContext)
   
   // Insert the document metadata into the message
   Do tMessage.Documents.Insert(tDocument)
   
   // Send the message to the test service (or directly to HS.IHE.XDSb.DocumentSource.Operations)  
   Write ##class(HS.Test.Service).SendSync(tMessage,.rr)
   
   Quit
}

To trap errors when using the Test Service, replace the final Write statement in the above example with:

  Set tSC = ##class(HS.Test.Service).SendSync(tMessage,.rr)
  if $$$ISOK(tSC) {   
  set statusSuccess=rr.ContentStream.FindAt(
     1,"urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success")
  set statusFail=rr.ContentStream.FindAt(
     1,"urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure")    
  if statusFail0 { w !, "Response Status was a failure!"   
     Do rr.ContentStream.Rewind() w !, rr.ContentStream.Read(231), " ... " }
  if statusSuccess>0 { w !, "Response Status was Success"  } 
  } else { Do $System.Status.DisplayError(tSC) }
Note 1

The submission set metadata includes Patient ID (MPIID & Home Community OID), document source, and content code:

  • Use a PIX query to obtain the Patient ID if you have only the MRN.

  • The SourceId should be the OID of a facility associated with your repository.

  • Select a ContentTypeCode from the Coded Entry Registry (HS.IHE.CodedEntry).

    The “Scheme” OID in the example, 2.16.840.1.113883.6.1 means LOINC.

Note 2

Open the document file and insert it into Body (for CDA, this is CharacterBody). The document will become an MTOM attachment in the outbound message. In this case, we are providing a PDF, so open the file as a binary.

Note 3

The MIMEType for a PDF is application/pdf. See http://www.iana.org/assignments/media-types/index.htmlOpens in a new tab for a list of valid types.

Note 4

Note that document creation time uses YYYYMMDDHHMMSS-offset format according to the IHE specification. The following will produce the current time in the correct format:

$REPLACE($TR($ZDT($H,3,6),":T"),"-","",,2)
Note 5

This is optional and controls replacement. If you specify a ReplacementContext, then an XDS.B query is performed to obtain the document unique ID of documents that match the context.

In this case, it is looking for documents that match the specified eventcode. You may include other context items as well. The Patient ID and the Status of "approved" are added to the to the context automatically.

IHE Metadata Requirements for Third Party Systems

The tables below indicate what metadata attributes are required by the IHE specification. When sending a document to a third party system, they may require all or a subset of the required metadata attributes. For example, when providing a CDA document to InterSystems products, it does not require the source patient ID to appear in the metadata as it can extract this information from the document. Other systems may not support that behavior.

DocumentEntry Metadata Attribute Requirements (Required* means “required if known”)

Metadata Attribute

XDS.b

Provide and Register

XDS.b

Register

XDM

Distribute

XDR

Provide and Register

XDR (Metadata-limited)

Provide and Register

author

Required

Required*

Required*

Required*

Required*

availabilityStatus

Optional

Optional

Optional

Optional

Optional

classCode

Required

Required

Required*

Required

Required*

comments

Optional

Optional

Optional

Optional

Optional

confidentialityCode

Required

Required

Required*

Required

Required*

creationTime

Required

Required

Required*

Required

Required*

entryUUID

Required

Required

Required

Required

Required

eventCodeList

Optional

Optional

Optional

Optional

Optional

formatCode

Required

Required

Required*

Required

Required*

hash

Optional

Required

Required

Optional

Optional

healthcareFacility TypeCode

Required

Required

Required*

Required

Required*

homeCommunityId Optional Optional Optional Optional Optional
languageCode

Required

Required

Required*

Required

Required*

legalAuthenticator Optional Optional Optional Optional Optional
mimeType

Required

Required

Required

Required

Required

patientId Required

Required

Required*

Required

Required*

practiceSettingCode

Required

Required

Required*

Required

Required*

repositoryUniqueId Optional Required Optional Optional Optional
serviceStartTime

Required*

Required*

Required*

Required*

Required*

serviceStopTime

Required*

Required*

Required*

Required*

Required*

size Optional

Required

Required

Optional Optional
sourcePatientId

Required

Required

Required*

Required

Required*

sourcePatientInfo Optional Optional

Required*

Optional

Required*

title Optional Optional Optional Optional Optional
typeCode

Required

Required

Required*

Required

Required*

uniqueId

Required

Required

Required

Required

Required

URI Optional Optional

Required

Optional Optional
SubmissionSet Metadata Attribute Requirements (Required* means “required if known”)

Metadata Attribute

XDS.b

Provide and Register

XDS.b

Register

XDM

Distribute

XDR

Provide and Register

XDR (Metadata-limited)

Provide and Register

author

Required*

Required*

Required*

Required*

Required*

availabilityStatus Optional Optional Optional Optional Optional
comments Optional Optional Optional Optional Optional
contentTypeCode

Required

Required

Required*

Required

Required*

entryUUID

Required

Required

Required

Required

Required

homeCommunityId Optional Optional Optional Optional Optional
intendedRecipient Optional Optional

Required*

Required*

Required*

patientId

Required

Required

Required*

Required

Required*

sourceId

Required

Required

Required

Required

Required

submissionTime

Required

Required

Required

Required

Required

FeedbackOpens in a new tab