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

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.
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.
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.
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.
The document repository on the other system responds with a success (or failure) message.
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.

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

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.
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.
The InterSystems Document Source transforms the message into an IHE “ProvideAndRegisterDocumentSetRequest” using the XSL transformation specified in the DocumentTransform setting.
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.
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.
The XDS document repository on the other system responds with a success (or failure) message.
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 See IHE Metadata Requirements for Third Party Systems for details on minimum IHE requirements See the class reference for the Provide and RegisterOpens in a new tab request message for complete document metadata details.	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

Querying and Retrieving a Document from another Affinity Domain (XCA)

Querying an XDS Registry and Retrieving a Document from a Repository