Skip to content

Provide and Register Document Set

Transaction to store one or more documents to a community. Primary systems shall use this transaction to export documents and the to a community repository to add it to a patients EPR.

Overview

Primary systems shall use this transaction to provide documents and the related document metadata to a patient EPR. In the Swiss EPR the IHE XDS.b profile and transactions shall be used.

To store the document metadata of the document, the the primary system shall perform a Provide And Register Document Set [ITI-41] transaction. Within the request, the primary systems shall provide the master patient ID as retrieved from the PIX Query, the document metadata as defined in the ordinances of the Swiss EPR and the binary data of the document.

The community responds with a code indicating the successful registration of the document.

Transaction

Message Semantics

Messages are encoded as described in the ebXML standard with restrictions defined in the IHE profile and the ordinances to the Swiss EPR.

Request Message

Since the ebXML standard is very generic, the request message is quite lengthy and needs some background information to interpret.

The structure of the result set is as follows (see example below):

  • The metadata of the individual documents are bundled in a ExtrinsicObject element.
  • The metadata attributes are encoded as Slot, as Classification or as ExternalIdentifier elements.
  • Metadata attributes encoded as Slots can be identified and interpreted by the slot's name attribute.
  • Metadata attributes encoded as Classification can be identified and interpreted by the classification's classificationScheme attribute.
  • The unique ID of the document is encoded as ExternalIdentifier, which has an identificationScheme attribute with a fixed value.

The table of the identifier used to indicate the metadata attributes is defined by the metadata model used by IHE XDS.b in IHE ITI Technical Framework Vol. 3, Section 4.2.5.1 and IHE ITI Technical Framework Vol. 3, Section 4.2.5.2 .

The corresponding interpretation of the metadata attributes in the Swiss EPR and the supported value sets may be found in Annex 3 of the ordinances of the Swiss electronic patient dossier.

A request message is quite lengthy. A listing with abrevations used in the step by step interpretation below is found here. The raw version of the request message may be found here.

Message Interpretation

The request message is not very complex, but lengthy due to the genericity of the ebXML standard. Therefore the following step by step interpretation may be of help to interpret the response.

The SOAP Header element conveys the following information:

  • To element: The URL of the provide and register document set service.
  • MessageID element: a UUID of the message.
  • Action element: The SOAP action identifier of the request as defined in the IHE ITI Technical Framework.
  • Security element: The Web Service Security header as defined in the WS Security specification. This element conveys the XUA Assertion used for authorization (see Provide X-User Assertion).
SOAP header
 3
 4
 5
 6
 7
 8
 9
10
11
3 requestType: ITI41
4 Access-Control-Allow-Origin: https://dev.avintis.com/ehgw/api
5 Access-Control-Allow-Methods: OPTION, GET, POST, DELETE, PATCH, PUT, HEAD
6 frameworkMessageId: b2275987-6393-4938-a5c9-a3ad12d5b297
7 frameworkMessageId_old: 2292d845-2ef3-4cf1-b55c-40bdba6f8c14
8 Access-Control-Allow-Headers: Authorization,Access-Control-Allow-Origin,Content-Type,Content-Length, X-Requested-With
9 Cache-Control: private
10 Access-Control-Allow-Credentials: true
11 frameworkContext: PostProcessing^WSO2^WSO2^PostProcessing_aInterface

The SOAP Body element conveys the following objects in ebXML syntax:

  • RegistryRegistryPackage defining the submission set and it's metadata.
  • ExtrinsicObject defining the document metadata (matches the document metadata interpretation in Registry Stored Query).
  • Association linking the document metadata to the submission set.

We will explain the RegistryRegistryPackage object defining the submission set first. For the other elements, see below.

Submission Set

The structure of the RegistryPackage object defining the submission set is as follows (see example below):

  • The metadata attributes are encoded as Slot, as Classification or as ExternalIdentifier elements.
  • Metadata attributes encoded as Slots can be identified and interpreted by the slot's name attribute.
  • Metadata attributes encoded as Classification can be identified and interpreted by the classification's classificationScheme attribute.
  • The unique ID of the document is encoded as ExternalIdentifier, which has an identificationScheme attribute with a fixed value.

The RegistryRegistryPackage object defining the submission set has one Slot child elements with name submissionTime which conveys the request timestamp, and a Name element to convey the display name of the submission set (see lines 17 to 25 below).

RegistryRegistryPackage element
17
18
19
20
21
22
23
24
25
17 Host: 10.2.101.10:11076
18 Connection: Keep-Alive
19 User-Agent: Synapse-PT-HttpComponents-NIO
20 Content-Length: 181931
21 
22 --uuid:df997b05-d075-415b-9cc8-0f68c74cd993
23 Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
24 Content-Transfer-Encoding: binary
25 Content-ID: <root.message@cxf.apache.org>

The RegistryRegistryPackage object defining the submission set has three Classification child elements conveying the submission set metadata:

  • Content Type Code: The submission set content type code attribute, indicated by the value of the classificationScheme equal to urn:uuid:aa543740-bdda-424e-8c96-df4873be8500. The value conveyed with the nodeRepresentation attribute and the codingScheme value must match one of the supported values in the Swiss EPR as defined in Annex 3.
  • submission author: The submission set author element, indicated by the value of the classificationScheme equal to urn:uuid:a7058bb9-b4e4-4307-ba5b-e3f0ab85e12d. The author element is optional in the EPR. If present, it shall convey the information on the person, which initiated the request.
  • submission set identificator: An element with classification scheme urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd required to identify the RegistryPackage object as a XDS.b submission set.
RegistryRegistryPackage element
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
26 
27  <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
28   <soap:Header>
29    <Action soap:mustUnderstand="true"
30 xmlns="http://www.w3.org/2005/08/addressing">urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b</Action>
31    <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:073be420-d838-47c9-b35f-c59af5b147a2</MessageID>
32    <To xmlns="http://www.w3.org/2005/08/addressing">http://ehealthsuisse.ihe-europe.net:8280/xdstools7/sim/epr-testing__for_init_gw_testing/rep/prb</To>
33    <ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
34     <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
35    </ReplyTo>
36    <wsse:Security>
37     <!-- omitted for brevity -->
38    </wsse:Security>
39   </soap:Header>
40   <soap:Body>
41    <xds:ProvideAndRegisterDocumentSetRequest xmlns:rmd="urn:ihe:iti:rmd:2017"
42 xmlns:lcm="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0"
43 xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"
44 xmlns="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"
45 xmlns:xds="urn:ihe:iti:xds-b:2007"
46 xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0">
47     <lcm:SubmitObjectsRequest>
48      <rs:RequestSlotList/>
49      <RegistryObjectList>

50       <ExtrinsicObject mimeType="application/fhir+json" objectType="urn:uuid:7edca82f-054d-47f2-a032-9b2a5b5186c1" id="urn:uuid:af516d8d-c449-4a8b-bbb4-9e36489d474d">
51        <Slot name="creationTime">
52         <ValueList>
53          <Value>20231219102116</Value>
54         </ValueList>
55        </Slot>
56        <Slot name="languageCode">
57         <ValueList>
58          <Value>en</Value>
59         </ValueList>
60        </Slot>
61        <Slot name="sourcePatientId">
62         <ValueList>
63          <Value>CHPAM3946^^^&amp;1.3.6.1.4.1.12559.11.20.1&amp;ISO</Value>

The RegistryRegistryPackage object defining the submission set has three ExternalIdentifier child elements:

  • XDSSubmissionSet.sourceId: Conveys the OID of the primary system performing the request.
  • XDSSubmissionSet.uniqueId: Conveys a UUID of the submission set.
  • XDSSubmissionSet.patientId: The master patient ID (XAD-PID) of the patient in CX format (see PIX Feed).
RegistryRegistryPackage element
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
64         </ValueList>
65        </Slot>
66        <Slot name="urn:e-health-suisse:2020:originalProviderRole">
67         <ValueList>
68          <Value>HCP^^^&amp;2.16.756.5.30.1.127.3.10.6&amp;ISO</Value>
69         </ValueList>
70        </Slot>
71        <Name>
72         <LocalizedString charset="UTF-8" value="Vaccination - FSME-Immun 0.25 ml Junior"/>
73        </Name>
74        <Classification classificationScheme="urn:uuid:93606bcf-9494-43ec-9b4e-a7748d1a838d" classifiedObject="urn:uuid:af516d8d-c449-4a8b-bbb4-9e36489d474d" nodeRepresentation="" id="urn:uuid:1012a5ae-21b8-41d4-895a-a14f6303d23a">
75         <Slot name="authorPerson">
76          <ValueList>
77           <Value>^Max^Mustermann^^^Dr.Med</Value>
78          </ValueList>
79         </Slot>
80         <Slot name="authorRole">
81          <ValueList>
82           <Value>HCP^^^&amp;2.16.756.5.30.1.127.3.10.6&amp;ISO</Value>
83          </ValueList>
84         </Slot>
85         <Slot name="authorSpecialty">
86          <ValueList>
87           <Value>1050^^^&amp;2.16.756.5.30.1.127.3.5&amp;ISO</Value>
88          </ValueList>
89         </Slot>
90        </Classification>
91        <Classification classificationScheme="urn:uuid:41a5887f-8865-4c09-adf7-e362475b143a" classifiedObject="urn:uuid:af516d8d-c449-4a8b-bbb4-9e36489d474d" nodeRepresentation="184216000" id="urn:uuid:98e9bd8c-6d85-4608-a158-792b41b35911">
92         <Slot name="codingScheme">
93          <ValueList>
94           <Value>2.16.840.1.113883.6.96</Value>
Document Metadata

The request contains 1..N ExtrinsicObject representing the document metadata for each document. The interpretation of the document metadata matches the document metadata interpretation, which is explained in detail in step by step example in the Registry Stored Query page and will not be reproduced here. Please see Registry Stored Query for the interpretation of the document metadata.

Association

The request contains one Association object linking the document and document metadata to a submission set defined in the RegistryPackage (see Submission Set).

The Association object thus conveys two parameter to link the objects:

  • sourceObject: The attribute value must match the id attribute of the submission set RegistryPackage.
  • targetObject: The attribute value must match the id attribute value of the document metadata ExtrinsicObject.

In addition the Association object conveys a status indicator, which must take the value Original (see snippet below).

Association element
277

Response Message

The provide and register service responds with a message indicating the success of the transaction. The outcome indicator is encoded in the Body element of the SOAP envelope as follows:

9
  <ns2:RegistryResponse xmlns=" !--namespace ommitted " status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>.

The raw version of a response message may be found here.

Transport Protocol

The system shall send the request messages to the repository service of the community using the MIME Multipart/Related binding as specified in the SOAP MTOM specification of the W3C.

The request in MTOM format may look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
POST /XDSDocumentRepositoryService HTTP/1.1
Host: 10.2.101.10:11076
Content-Type: multipart/related; boundary="MIMEBoundary_05b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149"; type="application/xop+xml"; start="<0.15b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149@apache.org>"; start-info="application/soap+xml"; action="urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-b"
Connection: Keep-Alive
Content-Length: 181931

--MIMEBoundary_05b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149
Content-Type: application/xop+xml; charset=utf-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.15b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149@apache.org>

<!-- message omittedd -->

--MIMEBoundary_05b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: <1.c5b39a33e8effeb94a97121c58c4b93b53d2935a13853149@apache.org>

<!-- binary document data omitted -->

--MIMEBoundary_05b39a33e8effeb90c1ccb1c58c4b93b5af2935a13853149--

The provide and register service sends the response message in the MIME Multipart/Related binding as specified in the SOAP MTOM specification of the W3C.

The response in MTOM format may look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
DefaultHttpResponse(chunked: false)
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: multipart/related; type="application/xop+xml"; boundary="uuid:2a1acced-0234-4a54-8dd3-b9f9b753169c"; start="<root.message@cxf.apache.org>"; start-info="application/soap+xml"
Date: Thu, 24 Sep 2020 15:43:11 GMT
Content-Length: 1136

--uuid:2a1acced-0234-4a54-8dd3-b9f9b753169c
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <root.message@cxf.apache.org>

<?xml version='1.0' encoding='utf-8'?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
 <soap:Header>
  <Action xmlns="http://www.w3.org/2005/08/addressing" soap:mustUnderstand="true">urn:ihe:iti:2007:ProvideAndRegisterDocumentSet-bResponse</Action>
  <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:3dbfa2b7-3cd6-46b3-b642-9569bb3b43fb</MessageID>
  <To xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/anonymous</To>
  <RelatesTo xmlns="http://www.w3.org/2005/08/addressing">d22ebb69-8368-4eb6-929b-b382f1b37c72</RelatesTo>
 </soap:Header>
 <soap:Body>
  <ns2:RegistryResponse
  xmlns="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"
  xmlns:ns2="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0"
  xmlns:ns3="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0"
  xmlns:ns4="urn:ihe:iti:xds-b:2007"
  status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>
 </soap:Body>
</soap:Envelope>
--uuid:2a1acced-0234-4a54-8dd3-b9f9b753169c--

Audit Log

Primary systems shall store syslog messages to the audit record repository of the community using TLS transport protocol. The audit message uses XML formatting as specified in RFC 3881 with restrictions specified in the IHE ITI TF and the Extension 1 to Annex5 in the ordinances of the Swiss electronic patient record (see Section 1.5 "Requirements on ATNA").

The following snippet shows a example audit message to be written by the primary system:

iti-41-log.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?xml version="1.0"?>
<AuditMessage>
 <EventIdentification EventActionCode="R" EventDateTime="2020-11-17T18:39:39+01:00" EventOutcomeIndicator="0">
  <EventID csd-code="110106" originalText="Export" codeSystemName="DCM"/>
  <EventTypeCode csd-code="ITI-41" originalText="Provide and Register Document Set-b" codeSystemName="IHE Transactions"/>
 </EventIdentification>
 <ActiveParticipant UserID="pma@gnt.com" UserName="JD&lt;pma@gnt.com&gt;"/>
 <ActiveParticipant UserID="2000000090108" UserName="Dr. med. John Doe" UserIsRequestor="true">
  <RoleIDCode csd-code="HCP" codeSystemName="2.16.756.5.30.1.127.3.10.6" originalText="Healthcare professional"/>
 </ActiveParticipant>
 <ActiveParticipant UserID="https://repositoryService.com" AlternativeUserID="1" UserIsRequestor="false" NetworkAccessPointID="172.18.0.49" NetworkAccessPointTypeCode="2">
  <RoleIDCode csd-code="110153" codeSystemName="DCM" originalText="Source Role ID"/>
 </ActiveParticipant>
 <ActiveParticipant UserID="https://primarySystem.com" AlternativeUserID="UNKNOWN" UserIsRequestor="true" NetworkAccessPointID="hcohcdemo01-app06-icwpxs01.net.swisscom-health.it" NetworkAccessPointTypeCode="1">
  <RoleIDCode csd-code="110152" codeSystemName="DCM" originalText="Destination Role ID"/>
 </ActiveParticipant>
 <AuditSourceIdentification code="1" AuditSourceID="connectathon"/>
 <ParticipantObjectIdentification ParticipantObjectID="752343^^^&amp;2.16.840.1.113883.3.37.4.1.1.2.1.1&amp;ISO" ParticipantObjectTypeCode="1" ParticipantObjectTypeCodeRole="1">
  <ParticipantObjectIDTypeCode csd-code="2" originalText="Patient Number" codeSystemName="RFC-3881"/>
 </ParticipantObjectIdentification>
 <ParticipantObjectIdentification ParticipantObjectID="urn:uuid:6b948daf-ab4a-4d51-a1a4-e9f4b2e05ff7" ParticipantObjectTypeCode="2" ParticipantObjectTypeCodeRole="20">
  <ParticipantObjectIDTypeCode csd-code="urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd" originalText="submission set classificationNode" codeSystemName="IHE XDS Metadata"/>
 </ParticipantObjectIdentification>
</AuditMessage>

The message is made of the following blocks:

  • EventIdentification: Element with event related information including the timestamp.
  • ActiveParticipant: Information related to the community repository which is the source of the documents.
  • ActiveParticipant: Information on the user as required by the IHE XUA profile.
  • ActiveParticipant: Element with information on the authenticated user initiating the request.
  • ActiveParticipant: Element with information on the primary system performing which is the destination of the documents.
  • ParticipantObjectIdentification: Element conveying the master patient ID (XAD-PID) in CX format (see PIX Feed).
  • ParticipantObjectIdentification: Element with request message related information.

TODO Update with gazelle example

Security Requirements

To ensure privacy the transaction must be secured using https with mutual authentication, with X.509 certificates (extended validation required) and client and server side certificate validation.

To enable authorization, the transaction must convey the XUA Assertion for authorization in the security header of the SOAP envelope. See Provide X-User Assertion for the implementation details.

Note

  • Some test environments dropped the mutual authentication or TLS for testing purposes. Please contact your test system provider on the details.
  • Some test environments may also drop authorization for testing purposes. Please contact your test system provider on the details.

Test Opportunity

The transaction can be tested with the test suite of the EPR reference environment, test systems of the EPR communities or the EPR Playground.

Last update: 2024-08-09