Skip to main content
Previous sectionNext section

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 Request 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.Operations
Business Hosts PIX Consumer: HS.IHE.PIXv3.Consumer.Operations
  • if needed to get MPI ID
Business Hosts Document Consumer: HS.HC.IHE.XDSb.Consumer.Operations
  • 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.ProvideAndRegisterRequest
Production Messages HS.Message.XMLMessage:
  • RegistryResponse
Production Messages HS.Message.PatientSearchRequest (if PIX)
Production Messages HS.Message.PatientSearchResponse (if PIX)
Production Messages HS.Message.IHE.XDSb.QueryRequest (if replacement)
Production Messages HS.Message.IHE.XDSb.QueryResponse (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 Request 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.Operations
Business Hosts Document Consumer: HS.HC.IHE.XDSb.Consumer.Operations
  • if <Replacement Context> is specified in the message
Production Settings XDSbRepositoryServiceName in the Document Source
Production Messages HS.Message.IHE.XDSb.ProvideAndRegisterRequest
Production Messages HS.Message.XMLMessage:
  • RegistryResponse
Production Messages HS.Message.IHE.XDSb.QueryRequest (if replacement)
Production Messages HS.Message.IHE.XDSb.QueryResponse (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.org 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 the SubmissionSet metadata: 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 below "2.16.840.1.113883.6.1" means LOINC
        //
        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 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.
        //
        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", for a PDF, this is "application/pdf".
        // See http://www.iana.org/assignments/media-types/index.html for a list of valid types.
        //
        Set tDocument.MimeType="application/pdf"
        
        // Enter the document metadata
        // 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)
        //
        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"))
        
        // Continued...
        // 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)
        
        // 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 eventcode.
        // 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("$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)
        
        // To trap errors when using the Test Service, use the following instead
        //
        // 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) }
         
        Quit
}

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