Package be.ehealth.business.mycarenetdomaincommons.domain

this package contains the domain objects to create a request to send to mycarenet as defined on their document Service_Catalogue_Commons mycarenet documentation site (password protected, ask access to mycarenet servicedesk) extract from document : 2 Introduction 2.1 Audience

This document is intended for analysts, architect and developers of all applications that interface with the NIP-PIN platform.

See:
Description

Class Summary

Actor
Attribute
Blob	will be mapped to mycarenet BlobType. contains the contents of the detail tag in a mycarenet message.
CareProvider	maps to the mycarenet CareProviderType.
CareReceiverId	maps to the mycarenet CareReceiverIdType.
CommonInput	Contains all data to be mapped to the mycarenet CommonInputType.
Identification	maps to the mycarenet IdType. cfr documentation from mycarenet : A legal entity is identified by a name (optional) and a unique number.
Identifier
InputReference	Value class for an input reference
McnPackageInfo	maps to the mycarenet PackageType.
Nihii	maps to the mycarenet NihiiType. cfr documentation from mycarenet : The NIHII consists of the quality (nurse, hospital, pharmacy, …) and the identification number.
Origin	contains the data to be mapped to the mycarenet OrigineType in CommonInputType. cfr documentation from mycarenet : The origin indicates where the message originates from and consists of: Package: What software package did send it.
Party	contains the data for a mycarenet PartyType. which is either a physcial persond and/or an organization. cfr documentation from mycarenet : This type is used to identify a legal entity.
Period	maps to the mycarenet PeriodType. cfr documentation from mycarenet : • Period: If the business request has a fixed period length, this can be omitted.
Reference
Routing	contains the data to be mapped to mycarenet RoutingType. cfr documentation from mycarenet : Routing is a type used besides common input and is added in version 2.3 of the interface.
Ssin	Value object representing a niss
Subject

Package be.ehealth.business.mycarenetdomaincommons.domain Description

this package contains the domain objects to create a request to send to mycarenet as defined on their document Service_Catalogue_Commons

mycarenet documentation site (password protected, ask access to mycarenet servicedesk)

extract from document :

2 Introduction

2.1 Audience

This document is intended for analysts, architect and developers of all applications that interface with the NIP-PIN platform. It includes both Package Providers and Relaying Parties.

2.2 Goal of the document

This document intends to describe the common elements of the various services of NIP-PIN. It doesn’t describe the communication (SSO/ESB or SSO-Only). It provides information about the design of common parts of the various services. This allows architects of client applications to align their own architecture.

This document is referenced from the service-specific descriptions (i.e. the various Service Catalogs).

2.3 Document License

[[TODO]]

3 Common for all Services

3.1 Basic Principal

All services will be business specific. This means single service will only provide the functionality for one business transaction. Also it means that the service will only require business information and not technical information.

In some case there might exist several technical variants of the same service (e.g. version, format…). Each variant will be a different method with a different namespace and/or root-element; there will never be a version number in message itself.

3.2 Service versioning

When a service evolves, a new operation is added with a new operation name, a new element-name and/or a new element-namespace. For each of the (existing) operations the lifecycle status will be re‑evaluated on an individual base.

For NIP-PIN versions are more than an evolution of the format of the same message. It also means different formats of the same information. For example, the insurability input/output are different for nurses and pharmacies. Therefore both will have their own version of the input en output message.

This results in 2 unique URL, both WSDL and service itself, for a single business service. These URL’s do not change due to updated while it is still possible for both client (you) and server (us) to determine which version you use.

3.3 Service lifecycle

A service and each of the operations have one of the following lifetime statuses.

· Maintained: is active and can be continued to be used

· Deprecated: is still active might disappear and/or is no longer maintained. It is advised to migrate to a maintained version of this service.

· Removed: is no longer defined in the WSDL and can no longer be used. It is still documented to facilitate the migration of clients.

· Archived: no longer defined in both WSDL and documentation.

A service or service operation can change at any moment, but will never be without a cause. Possible causes include changes in the business process, technology evolutions, changes in eHealth, …

3.4 Message Traceability

Message traceability is very important for NIP-PIN. We are capable of tracing the messages from care provider to insurance organization if you provide us with the required information. This information is different when you get a response or not.

3.4.1 With response

The following references should be provided:

· WS-Addressing message reference (if available for the service)

· Input reference

· Output reference (if provided)

· NIP-PIN reference

Both NIP-PIN and the insurance organizations can use this reference number to find information about the message. Depending on the message it can also be possible to track the message itself. The only additional information needed is the environment (URL) the message was sent too.

Although not 100% necessary it does speed up the process if you provide the Service Desk with the same information as is required for the case where there is no response.

3.4.2 Without response

A response means a business response while the generic fault is considered without response.

3.4.2.1 With event ID (eHealth ESB only)

With this event ID we can find the reference number and come in the same situation as with response.

3.4.2.2 Without event ID

Normally you will receive a response, even when there is an error, but in some exception cases this might be impossible. In this case it is important to provide as much information as possible. This information can include:

· Service

· Service operation

· Common Input data

· Date/Time

· Fault received (complete, not just message)

· …

3.5 Message Order

For Sync messages the message order is guaranteed for messages that are send sequentially: the next message is only send after the response of the previous message is received. The order of sync messages that are sent before the previous message is response of the previous message is received is undetermined.

For ASync messages the order isn’t guaranteed by default. Once an acknowledge is received, the processing is based on priority, load, message size, randomness and not on the order it is received.

Some Async services are an exception on the rule and keep the order with the during Async processing. The order is determined on the order of reception, but as with Sync the order is only guaranteed for sequentially sent messages. To avoid delay of messages, the order is only kept for messages of the same or related types that originate from the same entity and are for the same receiver. So messages of a different type, from a different hospital or to a different IO will not block each other.

3.6 Interoperability

The goal of the services is to be compatible with as many client types as possible. For this we tend to follow the WS-I Basic Profile.

3.7 Best Practices

The following best practices are followed.

3.7.1 eHealth SOA Naming conventions

Since this is a Belgian Health Care project we follow the eHealth defined SOA naming conventions. These follow the standard best practices.

3.7.2 Simple generated code

XSD, the schema language used by NIP-PIN for the web service message format, is very powerful. Although most frameworks are capable of handling any XSD schema it quickly results in generated code that is complex and difficult to use.

NIP-PIN makes sure that the XSD schemas it publishes are targeted for code generation and not so much for message validation. This means we avoid the usage of enums, abstract types, choices, attributes and mostly work with sequences and optional or required elements.

3.7.3 Avoid redundant input

All service interfaces are designed to avoid multiple occurrences of the same value. For example, it will not be necessary to provide the test flag multiple times.

This principal isn’t executed into the extreme. It is still possible that the same value must be provided 2 times (e.g. NIHII) when there are cases these are different. The common input provides the means of avoiding this, see “Message Variants”.

NIP-PIN will also not request information that it is required but can always deduct from other input. We do always require the information if the information can sometimes be deducted and sometimes not, even in the case where it can be deducted. This is to allow for consistency. This principal does not apply on optional information.

3.8 Common Input & Output

3.8.1 Goal

Although the interface is completely adapted to the business interface, there is still information that is required/provided with every business transaction. This is mainly because most business transactions NIP-PIN provides are between Care Providers and Insurance Organizations.

The common input and output only applies to information that is common for all NIP-PIN services. Information that is only applicable to some business transactions are not part of the common input and output.

3.8.2 Format and Usage

The common schema defines the common input and output. One specific version of the common schema is used by a business schema. The common schema has its own namespace and separate version number. A specific version of the business schema references a specific version of the common schema, which never changes. If a service requires a new version of the common schema, a new version of the business schema will be created for this.

3.8.3 Message Description

This section describes the schema of both the common input and common output.

3.8.3.1 Input

The common input is always the first child-element of the input-element and has the “CommonInputType”. This contains the information that applies to the all request records.

A common record input is always the ‘preceding-sibling’ or each record. A record is an individual request (or response). In some services may group several individual requests into a single request but most service operations only support a single individual request and then the common record input is right behind the common input.

3.8.3.1.1 Root Type: Common Input Type

The root type contains the info about the request, the origin and references. The request indicates the type of request, currently only debug or not. InputReference is a reference filled by the requester (the care provider). NIPReference is a reference filled by the NIP-PIN platform and should therefore never be filled in. These references are features of the message as a whole; a message may contain many records. These references are free text value (before v2.3 this was limited to 14 characters), they will be returned in the common record response. When omitted, the value will also be omitted from the response.

The origin indicates where the message originates from and consists of:

· Package: What software package did send it.

· SiteID (since v2.1): The ID of the site that makes the request. See service catalogue for the allowed values per sector.

· Care Provider: Who was the beneficiary of the request (this is optional in the XSD but should almost always be provided).

· Sender (since v2.2): Who was the creator of the request (in most case this isn’t required)

For those flows that have a flat file equivalent, this corresponds to the segment 100:

· 100: specific for CareNet, is replaced by the “To” of WS-Addressing

· 101: specific for CareNet, is replaced by the “From” of WS-Addressing

· 102: Not part of common input, replaced by “To” of WS-Addressing

· 103: Replaced by “Origin”-element (actual value in //CommonInput/Origin/CareProvider/Nihii/Value)

· 105/106: Not part of common input but of XAdES when relevant

· 107: InputReference, First char repeated in Request/IsTest

3.8.3.1.2 Routing

Routing is a type used besides common input and is added in version 2.3 of the interface. It allows NIP-PIN to determine the HIO in case it isn’t defined explicitly in the WS-Addressing “To” element.

The routing consists of the following elements:

· Care Receiver: the member of the HIO, it is to this HIO the message is routed too.

o SSIN: the national number of the care receiver, should always be present and can only be omitted in very rare case (e.g. new born).

o RegNrWithMut: the registration number of the care receiver, optional when the SSIN is provided. Must be combined with the mutuality since the number is only unique with a mutuality.

o Mutuality: the 3 digit code of the mutuality (e.g. 203, 100, …). Must be used with reg nr with mut, but can also be used with SSIN to override the mutuality the message should arrive.

· Reference Date: The date for which the membership should be resolve, this must be a date within the period of the business request. See the relevant service catalogue for the specific rule.

· Period: If the business request has a fixed period length, this can be omitted. In case the business request has a variable period it must be provided. See the relevant service catalogue for the specific rules.

3.8.3.1.3 Record Root Type: Record Common Input Type

The record root type consists of a reference (before version 2.2 this was limited to a maximum 14 numeric digits) that will be part of the response.

For those flows that have a flat file equivalent, this corresponds to the segment 200:

· 200: specific for Flat, XML is “typed” and therefore this value is redundant

· 201: Version is part of the namespace, offering an enforced version.

· 202:

o Test/Production: part of common input, only 1 field applies to all records.

o Sync/Async: not repeated for flexibility (e.g. send sync messages Async in case of temporally downtime).

· 203: Replaced by Fault, see below

· 204: Input Reference

· 205: Not applicable here

3.8.3.1.3.1 Package Type

A package is identified by its name (optional) and its license. The license is a username password that is distributed to package providers that are licensed to access NIP-PIN.

3.8.3.1.3.2 Party Type

This type is used to identify a legal entity. This is either: a physical person, an organization or a physical person at an organization.

A legal entity is identified by a name (optional) and a unique number. Currently this can be one of the following: SSIN (physical person only), NIHII (health institute only) or CBE (enterprise only).

3.8.3.1.3.3 Care Provider Type

A Care Provider is similar to a Party-Type with the extension of a NIHII. The NIHII indicates the beneficiary care provider as know by the INAMI/RIZIV. The physical person and organization elements provide extra information about this care provider.

3.8.3.1.4 NIHII Type

The NIHII consists of the quality (nurse, hospital, pharmacy, …) and the identification number. The different values for the quality are described in the referenced document: “MyCareNet Authentication Catalogue.docx”. See the section “Message variants” for more information about the id, ref and valueRef attributes.

3.8.3.2 Output

As for the input, there is a common output and a common record output. The common output if for the entire message and the common record output is just before every response record.

3.8.3.2.1 Common Output Type

The InputReference will be empty in the case of common output for Asynchrone.

The NIPReference is a reference generated by NIP-PIN to identify the response message as a whole; this reference is also known by the IO and is linked to the request (cfr NIPReference in CommonInputType). This reference will always be provided, except for some rare cases (e.g. the generation of the reference fails).

The OutputReference is a reference generated by the IO to identify the response as a whole; this reference is only known by the IO (NIP-PIN does not keep a trace of it). This reference is only returned when there was a response from the IO, otherwise this reference is omitted.

Before version 2.2, all these references where limited to a 14 character long alpha numeric value.

For those flows that have a flat file equivalent, this corresponds to the segment 100:

· 100: specific for CareNet, no replacement.

· 101: specific for CareNet, no replacement.

· 102: Not part of common output, when relevant must be part of the business (which allows multiple values)

· 103: Not part of common output, when relevant must be part of the business (which allows multiple values)

· 105/106: Not part of common input but of XAdES.

· 107: Output reference.

NIP-Reference is new because of the new architecture. Input Reference repeats the reference of the input, but isn’t always available.

3.8.3.2.2 Common Record Output Type

The InputReference on record level can either be provided by the client (via the record common input) or be generated by NIP-PIN when not provided in the input. Normally this reference is always returned, except in occasional situations (e.g. generation of reference failed).

The OutputReference on record level is always generated by the IO and can be used with the IO to track the response record. It will only be present when there was a response of the IO, otherwise it will be omitted.

This InputReference is omitted in the output when it wasn’t present in the input. The value can be anything and is only intended for client use, NIP-PIN nor the IO can use this to track a message.

For those flows that have a flat file equivalent, this corresponds to the segment 200:

· 200: specific for Flat, XML is “typed” and therefore this value is redundant

· 201: Version is part of the namespace, offering an enforced version.

· 202:

o Test/Production: part of common input, only 1 field applies to all records.

o Sync/Async: not repeated for flexibility (e.g. send sync messages Async in case of temporally downtime).

· 203: Replaced by Fault, see below

· 204: Input Reference

· 205: Output Reference

3.8.3.3 Fault

In case a service uses faults, it uses the same fault type (but not fault message). This fault type is adapted to handle all type of technical errors, but not necessary message faults.

The fault has the following structure:

· Fault Code: A human readable (no number) but computer friendly code of the type of fault.

· Fault Source: partner/part that detected the error, important to determine who can assist in the resolution of the error

· Message

o @Lang: the language of the message (generally “en”)

o (value): description of the fault type, should be combined with the detail description.

· Details: list of detail messages

The detail message consists of:

· Detail Code: a human readable code (not a number) of the error that was detected.

· Location: stack-trace extract, xpath or description of the location where the error occurred.

· Message

o @Language: The language of the detail message (generally “en”)

o (value): The detailed message.

3.8.3.4 Blob

This document introduces a new type: blob. This is used to transfer (large) binary objects. It has the following structure:

· (value): The binary data, first compressed via deflate and then base 64 encoded (compatible with MTOM/XOP).

· @ContentType (required): exactly like xmine:contentType, but in a different namespace to avoid conflicts with MTOM/XOP. It must define which type the content is, it must be values like “text/plain”, “text/xml”, “application/pdf”, …

· @ContentEncoding: a fixed value “deflate” to indicate that the content is compressed via deflates.

· @MessageName (required): The business name of the message, e.g. “FAC”.

· @HashValue: pre-calculated hash of the uncompressed and decoded content. Must not be provided by the care provider, always provided to the care provider.

· @Id: The ID of the blob for usage in the XAdES signature. It is an “NCName” instead of an “ID” in order to be able to have different blobs with the same (fixed) id without causing an XSD validation.