This specification of the Web service interface for consent administration describes the Web services that are provided to health professionals and citizens, respectively, who wish to perform administration (creation, modification, deletion) of consents.
A consent describes a relationship between:
a citizen,
(what) information about the citizen
(who) health professional persons or organizations in addition to their entry way to the information
For a detailed description of the data model for consents and the structure of consent elements, see [Data Model].
A negative consent means that the citizen has declined that retrieval or disclosure of sensitive data (what) can be accomplished by an identified target group (who).
A positive consent selectively allows that an identified target group (who) can retrieve sensitive data (what), despite one or more negative consents for the sensitive data. A positive consent can furthermore be used in external systems to allow identified target group to retrieve sensitive data that has been marked externally as private.
A consent is either active or inactive. An active consent can affect a health professional’s access to sensitive data about the citizen. An inactive consent has no impact, but is a record of a formerly active consent, that the citizen has nullified.
A consent can be attached with a validity period (when), that states a period for which a health professional’s access to the information may be restricted (on negative consent) or relaxed (on positive consent). The consent’s validity period concerns the time for desired retrieval of information only; it does not concern when the information was created or registered. Positive consents must be attached with a validity period, while negative consents only requires a stated start date.
A health professional’s access to sensitive data concerning a citizen is unaffected by a consent if the health professional is outside the consent’s field of action. This is the case if for instance a negative consent concerns another specific health professional.
The purpose of this section is to provide an overview of the definitions and document references used in this document.
Definition | Description |
NSI | National eHealth Authority |
NSP | National Service Platform (within health care) |
SHAK | Hospital Department Classification (Danish: Sygehusafdelingsklassifikation) |
SOR | National Health Organisation Register (Danish: Sundhedsvæsenets Organisationsregister). |
STS | Security Token Service |
Alias | Description |
DGWS 1.0 | Den Gode Webservice 1.0 |
DGWS 1.0.1 | Den Gode Webservice 1.0.1 |
HSUID-header | Healthcare Service User Identification Header (SSE/11734/IFS/0018) |
OIO-WSDL | Guideline for development and use of OIOWSDL, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/standarder-for-serviceorienteret-infrastruktur/standarder-for-webservices/filer-til-standarder-for-webservices/OIOWSDL_english.pdf |
OIO-NDR | OIO Namegivnings- og Designregler, OIO-NDR version 3.2, http://www.itst.dk/it-arkitektur-og-standarder/standardisering/datastandardisering/oioxml-udvikling/regler/ndr-3.2 |
Data Model | Consent Service Data Model (SSE/11734/DDD/0003) |
IDWS | OIO-IDWS 1.1 |
In the document, the concepts of authorization and authorized are used primarily in a security context, that is, in the sense that a person or a system is authorized to use a given resource. If the concepts are applied towards health professionals with Danish authorization listed in Danish Health Authority’s authorization register, it will be stated explicitly.
A system that uses Web service(s) described in this document is referred to as a user system. Note that there are particular responsibilities that the user and user system must fulfil, as described in section 1.6.
It is assumed that the reader understands the general use of SOAP-based Web services. For this reason, technical terms such as SOAP, WSDL etc. are not clarified. Knowing Den Gode Webservice (DGWS) 1.0.1 described in [DGWS 1.0] and [DGWS 1.0.1] will facilitate comprehension considerably.
Version | Date | Responsible | Description |
0.1 | 24.2.2012 | Systematic | Initial version. |
0.9 | 14.5.2012 | Systematic | Clarification and elaboration of Web service semantics (section 4). Clarification of attributes for user identification and explicit consent scenario. Specification of consent registration for foreign health professionals. |
0.91 | 16.5.2012 | Systematic | Clarification of how organization identification is based on SOR-code has been added to section 2.3 and 2.4. Redundant information removed from section 3.2.2. Clarification of how organization identification is based on SOR only has been corrected in section 5.5. |
1.0 | 29.6.2012 | Systematic | The user system responsibilities has been updated, SOAP-faults added, schemas updated, general improvements. Section 7 concerning WSDL added. |
1.1 | 28.11.2014 | Systematic | References to National Patient Index (NPI) removed. |
1.2 | 09.09.2016 | Systematic | Changed nsi:skscode to nsi:skskode and nsi:sorcode to nsi:sor to fit XML schema |
1.3 | 13.06.2018 | Systematic | Migrated to NSPOP SVN |
22.10.2018 | KIT | Document moved from Word to Confluence. Original document name was: IFS0013 Consent Administration Service Interface Description.docx | |
14.05.2020 | KIT | SDS-3883 Etablering af IDWS snitflade |
For some of the usage scenarios (and thus the Web service operations) described in this document, it is allowed for another person than the citizen itself to perform the action (referred to as performing the action on behalf of the citizen). In this case, it is the responsibility of the user system to ensure that the citizen has consented that the person can perform this action prior to performing it.
Similarly, it is allowed in certain usage scenarios that a health professional performs the action on behalf of the citizen. It is the responsibility of the user system to ensure that the citizen has consented that the health person can perform this action prior to performing it.
It is possible through the Web service to create two (or more) consents that are identical from the citizen’s point of view. For instance by SOR-codes that map to the same ward, by overlapping dates or simply completely identical consent objects.
The service does not check if identical consents are created and it is consequently the responsibility of the user system to ensure that no new consents identical to pre-existing are created.
The following section describes the usage scenarios that the Web service for consent administration supports.
A health professional is able to add positive and negative consent on behalf of the citizen to the citizen’s present consent registrations.
As the change entails an entry in the citizen’s Min-log, the citizen will be able to later learn this.
This usage scenario is supported by the operation ConsentAdd.
A citizen can retrieve a complete overview of the consents, that are registered for the citizen, whether they are registered by the citizen, a person on behalf of the citizen or by a health professional.
Another person than the citizen can, on behalf of the citizen, perform the activity. As the action entails an entry in the citizen’s Min-log, the citizen will later be able to learn of the action performed by the person.
This usage scenario is supported by the operation ConsentRegistrationsGet.
The result of the operation is a complete list of all active and inactive consent registrations for the citizen in question.
A citizen can register negative consent covering:
(what) Possibly everything in regard to (who) everybody or a specific (named) person provided by social security number.
Or (what) selected information, originating from organization provided by SOR-code – with or without subordinate organizations - created in a certain period in respect to (who) everybody.
(when) a validity period for the consent provided by start and end date, where end date is not a requirement.
Another person than the citizen can, on behalf of the citizen, perform the activity. As the action entails an entry in the citizen’s Min-log, the citizen will later be able to learn of the action performed by the person.
This usage scenario is supported by the operation ConsentAdd.
A citizen can register positive consent covering:
(what) Possibly everything in regard to (who) for a specific identified person provided by social security number or for an organization provided by SOR-code – with or without subordinate organization – or for foreign health professionals provided by positive marking.
Or (what) selected information originating from a specific organization provided by SOR-code – with or without subordinate organization - created in a certain period in respect to (who) either a specific named person provided by social security number or for a specific organization provided by SOR-code – with or without subordinate organization.
(when) a validity period for the consent provided by start and end time. The validity can at most cover one year.
The activity can be performed by a person other than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.
This usage scenario is supported by the operation ConsentAdd.
A citizen can change one or more positive or negative consent registrations.
The activity can be performed by another person than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.
This usage scenario is supported by the operation ConsentModify.
A citizen can nullify positive and negative consent registrations.
The activity can be performed by another person than the citizen, on behalf of the citizen. As the action entails an entry in the citizen’s Min-log, the citizen will be able to later learn of this person’s action.
This usage scenario is supported by the operation ConsentRevoke.
The template below is used to document the operations that are offered in the Consent Administration Web Service. The most important elements for input and output are described in section 5.
Name: <operation header> | |
---|---|
Description: | Description of the function’s purpose. |
Input: | Input parameters. |
Output: | Output parameters. |
Error handling: | Description of error handling; typically refers to the general description of error handling in 4.7. |
Roles: | Description of necessary roles. |
Prerequisites: | Description of prerequisites that must be met for the function to complete successfully. |
Name: ConsentRegistrationsGet | |
---|---|
Description: | Retrieves descriptions of all registrations of consents applicable to given citizen. |
Input: | ConsentRegistrationsGetRequest which consists of: PatientPersonCivilRegistrationIdentifier Identification of the citizen for which consent registrations are desired |
Output: | ConsentRegistrationsGetResponse which consists of: ConsentRegistrations Collection of all active and inactive consent registrations registered for citizen in question. |
Error handling: | See section 4.7. |
Roles: | Citizen, person (on behalf of citizen) |
Prerequisites: | Both user system and user must be authenticated and authorized as described in section 4.2.1. |
Name: ConsentAdd | |
---|---|
Description: | Adds active consent/active consents applicable to given citizen. |
Input: | ConsentAddRequest which consists of: ConsentAdds Collection of descriptions of registrations of consents, that are to be added. Note that the citizen is identified in ConsentAdds. |
Output: | Nothing |
Error handling: | See section 4.7. |
Roles: | Citizen, health professional, person (on behalf of citizen). |
Prerequisites: | Both user system and user must be authenticated and authorized as described in section 4.2.1. The operation is not idempotent and on repeated calls with identical parameters, multiple identical consents will be created (see section 1.6). |
Name: ConsentModify | |
---|---|
Description: | Updates consent(s) from the collection of consents applicable to given citizen. |
Input: | ConsentModifyRequest which consists of: ConsentModifications Collection of descriptions of consents, that are desired modified. Note that the citizen is identified in ConsentModification. |
Output: | Nothing |
Error handling: | See section 4.7. |
Roles: | Citizen, person (on behalf of the citizen) |
Prerequisites: | Both user system and user must be authenticated and authorized as described in section 4.2.1. |
Name: ConsentRevoke | |
---|---|
Description: | Revokes given consent(s) from the collection of consents applicable to the provided citizen. This takes place by inactivation of the revoked consents. |
Input: | PatientConsentRevokeRequest which consists of: ConsentRevocations Collection of descriptions of consents, that are to be revoked. Note that the citizen is identified in ConsentRevocation. |
Output: | Nothing |
Error handling: | See section 4.7. |
Roles: | Citizen |
Prerequisites: | Both user system and user must be authenticated and authorized as described in section 4.2.1. |
The Web service expects SOAP messages, where the SOAP header contains security header and Medcom header as required by DGWS 1.0.1, in addition to a Healthcare Service User Identification (HSUID) header.
Figure 1 SOAP message containing security header, Medcom header and HSUID header is used as message format.
The format of Security and Medcom headers are described in [DGWS 1.0] and [DGWS 1.0.1], while the format of the HSUID header is described in [HSUID-header].
When user of the service is a citizen, then the attributes in Table 1 from the HSUID-header are applied.
The element Attribute | Subelement AttributeValue | ||
---|---|---|---|
Name-attribute | NameFormat-attribute | - | |
nsi:UserType | nsi:Citizen | ||
nsi:ActingUserCivilRegistrationNumber | Citizen’s social security number | ||
nsi:SystemOwnerName | Name of system owner of the user system | ||
nsi:SystemName | Name of the user system | ||
nsi:SystemVersion | Version of the user system | ||
nsi:OrgResponsibleName | Name of organization responsible for operation of the user system |
Table 1 Attributes in HSUID-header applied for user who is citizen.
When the user of the service is a health professional, then the attributes in Table 2 from the HSUID-header are applied.
The element Attribute | Subelement AttributeValue | ||
---|---|---|---|
Name-attribute | NameFormat-attribute | - | |
nsi:UserType | nsi:HealthcareProfessional | ||
nsi:ActingUserCivilRegistrationNumber | The health professional’s social security number | ||
nsi:OrgUsingID | nsi:sor or nsi:skskode or nsi:ynumber | Identification of the organization that the health professional is affiliated with as user. The attribute must be present at least once and may occur twice. With two occurrences, the organization can be identified by SOR-code and for instance SHAK-code | |
nsi:ResponsibleUserCivilRegistrationNumber | Social security number of the health professional under whose responsibility the user acts. If this is the same person as the user, the same social security number is given | ||
nsi:ResponsibleUserAuthorizationCode | Authorization number listed in the National Board of Health authorization register for the health professional under whose responsibility the user acts. If the user is a health professional without authorization number listed in the National Board of Health authorization register and not working under the responsibility of designated health person, e.g., a paramedic with special competence, the value "-" is indicated | ||
nsi:SystemOwnerName | Name of the system owner of the user system | ||
nsi:SystemName | Name of the user system | ||
nsi:SystemVersion | Version of the user system | ||
nsi:OrgResponsibleName | Name of the organization responsible for operation of the user system. |
Table 2 Attributes in the HSUID-header applied for user who is a health professional.
The identification of the organization for which the user is associated, may be provided as a single value and a single format, such as SHAK-code:
<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:skskode"> <hsuid:AttributeValue>6620151</hsuid:AttributeValue> </hsuid:Attribute> |
Alternatively, the organization of which the user is affiliated can be specified by two values, e.g. as both SOR and SHAK-code:
<hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:sor"> <hsuid:AttributeValue>440081000016006</hsuid:AttributeValue> </hsuid:Attribute> <hsuid:Attribute Name="nsi:OrgUsingID" NameFormat="nsi:skskode"> <hsuid:AttributeValue>6620151</hsuid:AttributeValue> </hsuid:Attribute> |
Note that it is the consumer system's responsibility to ensure that there is consistency between the given ID across SOR, SHAK, and Healthcare Provider Number (Danish: ydernummer) classification systems.
The security of this Web service is based on the SOSI integration pattern in Den Gode Webservice (DGWS). Authentication is carried out by a trusted third party component on NSP (Security Token Service) and based on OCES digital certificates. As a rule, the service requires authentication with the STS component based on employee signature (MOCES). However, highly trusted systems - initially only Health journal - can during a transitional period gain access by level 3 based on company signature (VOCES).
Additional security aspects, including authorization, integrity, confidentiality, availability and privacy considerations are enforced to only some extent by the technical service. The aspects that are not currently handled by the technical service will be handled in the service agreement, as specified by the data-responsible authority (NSI), which consumers of the service must agree to.
When STS’ signature of the ID card has been validated successfully, then the consumer has been authenticated.
Authorization of consumer system is performed using a whitelist in the web service based on information in the system-part of the ID card.
When the user system is authenticated and authorized, the user is authenticated by the HSUID header attribute nsi: ActingUserCivilRegistrationNumber.
Whether the user is health professional or citizen is determined from the HSUID header attribute nsi: UserType.
Web service operation(s), where the user is health professional
The Web service authorizes all users who are health professionals to use its operations.
Web service operation(s), where the user is the citizen or a citizen, acting on behalf of another
The Web service authorize all users who are citizens to use its operations.
It is the user’s responsibility to ensure that the person is allowed to act on behalf of the citizen.
A request with ID card is rejected when it has been more than 24 hours since the beginning of the ID card validity period.
As required by DGWS 1.0.1, only HTTP-status codes 200 and 500 are used.
On HTTP status code 200 FlowStatus is always flow_finalized_succesfully.
Timeout on web service-operations is the same as default timeout on the NSP platform.
Each request is handled in its own session.
No check is performed whether MessageID in request has been received previously and no answer is guaranteed if a request with the same MessageID is received.
This deviates from DGWS 1.0.1 in regard to handling of retransmission.
If the request contains a flow ID, it is reused in possible forward calls to Min-log. Handling of flow ID complies with DGWS 1.0.1.
Digital signing of replies is not supported. On request for non-repudiation, a fault-error message is returned as described in [DGWS 1.0].
SOAP errors are returned with the components as described hereinafter. A structure has been chosen wherein both standard error codes as described in [DGWS 1.0] and service specific error codes can be returned.
<soap:Body> <soap:Fault> <faultcode>soap:Server</faultcode> <faultstring>Description of the error</faultstring> <detail> <FaultInfo xsi:type="ns2:dgwsInfo" xmlns="urn:dk:nsi:consent:admin:service:1" xmlns:ns2="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ns2:FaultCode>expired_idcard</ns2:FaultCode> </FaultInfo> </detail> </soap:Fault> </soap:Body> |
Code listing 1 Structure of SOAP-errors returned from the Web service operation. The example shows FaultCode used when the ID card has expired.
For all Web service operations described in section 3 will be used SOAP Fault with FaultCode-values as listed in Table 3, originating from DGWS 1.0.1.
FaultCode | Description |
---|---|
missing_required_header | One or more mandatory DGWS headers are missing in the enclosed message, e.g. ID card, which must always be provided. |
security_level_failed | Authentication or authorization error. Invalid choice of security level. |
invalid_idcard | Authentication or authorization error. Error in SOSI ID card. |
invalid_certificate | Authentication or authorization error. Certificate is not OCES or expired. |
expired_idcard | Authentication or authorization error. SOSI ID expired or too old for this Web service provider. |
not_authorized | User has insufficient rights to perform the Web service operation call. E.g., company registration number is not on whitelist. |
nonrepudiation_not_supported | Web service provider system cannot provide a digital signature on the reply. |
Table 3 Applied FaultCode-values originating from DGWS 1.0.1
Additionally, Web service specific FaultCode values as listed in Table 4 are used.
FaultCode | Description |
---|---|
consent_service.ConsentDatabase | An internal server error has occurred in connection with consent database communication |
consent_service.ConsentValidation | The consent contained invalid values or compulsory values were not provided |
consent_service.SORLookup | An internal server error has occurred in connection with lookup in the SOR-table |
consent_service.ServiceInvocation | The service was called with invalid parameters: The attached HSUID-header is invalid. Consents for more than one citizen has been attached A health professional attempts to retrieve, modify or delete consents |
consent_service.MinLogClient | A error occurred when trying to log this action in the citizen’s ’Min-log’ |
invalid_date_timezone | An attached date has invalid format, cf. DGWS 1.0.1. |
consent_service.UnknownError | An unknown server error resulted in failed call |
Table 4 Applied service-specific FaultCode values
In WSDL, that describes the Web service described in this document, these SOAP Fault status codes are not specified for every operation.
It is validated that:
Properly formatted HSUID header is included in the SOAP header, including the attributes that respectively may and must be present for a given user type, as described in section 4.1.1 and 4.1.2, are provided. Furthermore, it is validated that attribute values belong to established value sets and is not null or simply whitespaces
ID card in security header is valid and signed by STS and that the additional conditions described in section 4.2 are met
There following is not performed:
XML-schema validation
Validation that given social security numbers are valid
Validation that given authorization numbers are valid and found National Board of Health authorization register
Validation that a given ID for health professional’s organization is valid in provided classification system, nor that there is consistency between the ID when multiple ID and classification systems are provided.
Validation that a health care professional is affiliated with stated organization
Validation that the user is acting under responsibility of stated health professional
Consent administration service is based on the following standards:
SOAP version 1.1
Soap Fault version 1.1
WS-I Basic Profile 1.1
OIO naming and design rules
DGWS 1.0.1, with the exception of requirements regarding retransmission and control of reuse of message ID as described in section 4.5.1, and with the exception of structure used on errors as described in section 4.7.
This section provides a general description of the key elements in the XML schemas that together with WSDL define the Web service operations described in section 3.2. Where existing OIO-type is identified, it is provided in the parenthesis after the element name. Additionally, cardinality is provided when an element is not compulsory.
Element-name | Description |
CitizenCPR | The citizen’s social security number |
ConsentId | Unique identification of consent |
PositiveConsent | True if positive or negative |
What[0..1] | Description of which sensitive data the consent concerns. |
Who [0..1] | Description of which individual health professionals or health organizations the consent covers. |
ValidFrom | Validity period beginning of consent. This is only a date and not a timestamp. |
ValidTo [0..1] | Validity period end of consent. This is only a date and not a timestamp. |
Element-name | Description |
OrganizationIdentifier | Identification of specific health organization, possibly with subordinate organization, from which data originates |
IncludeSuborganizations | Whether data from subordinate departments for the stated organization, are also included in the consent |
ReferralStartDate [0..1] | Start date from when data is applicable. |
ReferralEndDate [0..1] | End date from when data is applicable. |
Element-name | Description |
HealthcareProfessionalIdentifier | Identification of a specific health professional by social security number |
Eller | |
OrganizationIdentifier | Identification of specific health organization, possibly having subordinate organization |
Eller | |
ForeignHealthcareProfessionals | Indicates with value true that the consent covers foreign health professionals. |
IncludeSuborganizations | Whether data for subordinate departments for the stated organization are also included in the consent. Only relevant if OrganizationIdentifier has been filled-in. |
Element-navn | Description |
ConsentItems | Collection of ConsentItem. |
Element-navn | Description |
ConsentRegistrations | Collection of ConsentItem. |
Element-navn | Description |
ConsentItems | Collection of ConsentItem |
Element-navn | Description |
ConsentRevocations | Collection of ConsentItem. |
For consent administration, the interface between the actor systems and consent verification is versioned.
The interface specification constitutes the contract that defines how the involved systems must act.
The interface specification consists of:
the technical specification of schema and service descriptions (documented as WSDL file, see section 7)
documentation of the semantic and functional meaning of data that is exchanged (documented in this document).
As part of the WSDL for ConsentAdministration are headers defined and versioned elsewhere. The body is specific for ConsentAdministration and follows the naming
”urn:dk:nsi:consentservices:administration:service:<version>”
where the version changes on redefinition of the ConsentAdministration interface.
WSDL for the service can be obtained by runtime WSDL-generation towards a deployed service. If the service in NSP test environment cannot be accessed with a view to runtime WSDL-generation, then a locally built and deployed service can be used.