Auto-activation

What is auto-activation?

Auto-activation is a self-service process that a customer can perform in the ZorgDomein application to fully automatically activate a connector with an external application without the intervention of the vendor of the external application or ZorgDomein. Currently auto-activation only supports the following components: 

• SSO to ZorgDomein
• Send documents
• Receive documents. 

Why auto-activation?

With the introduction of the ZorgDomein interface in primary care, we want to enable a low threshold for paramedics to connect to ZorgDomein. Because the primary care market includes tens of thousands of healthcare suppliers, we want to ensure that the setup of a new customer’s connection is highly efficient. Through auto-activation we reduce the manual interactions between the vendor of the external application, the customer and ZorgDomein to a minimum.

Process

When establishing an interface between the XIS of the customer and ZorgDomein, a one-time activation process is required. Upon completion, ZorgDomein and the XIS have successfully agreed upon a unique identifier to distinguish the customer’s organization. This identifier will be included in all FHIR messages that ZorgDomein will send to the XIS after the process of auto-activation has been completed successfully. This way the XIS can identify the destination of incoming messages.

The process of auto-activation consists of a number of consecutive steps as displayed in the following diagram: 

Note: Auto-activation can also be performed by a ZorgDomein employee. In that case the verification code flow (steps 6-8 in the diagram) are omitted.

1. Customer provides unique code

The process of auto-activation is initiated in the form of an auto-activation dialog in ZorgDomein when a new customer signs up for a ZorgDomein interface with the customer’s XIS. In this dialog the customer has to provide a unique code that can identify the customer’s organization for the XIS (note: this must be a code that identifies an organization, not a person). This code may be a generic or local code, e.g. customer reference number, AGB-code, correspondence number. The value of the code must be known by both the customer and the XIS. When implementing the mechanism of auto-activation, the XIS supplier has to decide which code should be used, because their system has to be able to uniquely identify the customer using this code. The XIS supplier can choose one of the following code systems: 

2. ZorgDomein requests organization details

The customer code will be used by ZorgDomein to send a FHIR search request to the FHIR server of the XIS supplier. This request is used to query the FHIR server of the XIS supplier for additional organization data for the customer.

The pseudo FHIR search syntax for this request is: https://[FHIRServerUrl]/Organization?identifier=[system]|[code]

3. XIS provides organization details and organization identifier

The XIS supplier responds with a FHIR bundle based on the type ‘searchset’. This bundle includes a FHIR resource as specified in the profile ZD Organization Activation. This resource should contain as many data elements about the customer’s organization as known by the XIS, including a unique organization identifier. This identifier determines the destination of incomming messages in the customer’s XIS. Therefore, the identifier must have an invariable and unique value for the organization in the XIS. The XIS supplier has to decide which identifier will be used. The system URI of the identifier must have the value http://zorgdomein.nl/fhir/identifier/local.  

NB: The value of this organization identifier will in most cases be different from the code that is entered by the customer in step 1! 

4. ZorgDomein presents organization details to customer

After ZorgDomein has received the organization details from the XIS, ZorgDomein will present the organization details in the auto-activation dialog in ZorgDomein. 

5. Customer validates organization details

The customer can check the presented organization details in ZorgDomein and has to confirm that these data corresponds to their organization. If there is a mismatch, the customer is advised to contact the ZorgDomein servicedesk.

Upon confirmation, ZorgDomein will store the organization identifier. At this point, the organization is known at both ZorgDomein and the XIS supplier by the same identifier. From now on, the organization identifier will be included in all FHIR messages. The identifier is contained in the ZD Destination extension in the ZD Document profile. This extension will refer to a PractitionerRole resource. The PractitionerRole resource refers to an Organization resource which may include multiple identifiers. The unique organization identifier can be recognized by the ZD Preferred Identifier extension. This way the XIS supplier can link all received FHIR messages to the right organization and process them accordingly.

6. ZorgDomein sends verification code

Once the organization identifier has been exchanged, the connection has been established from a technical perspective. The next step is to  test and verify the newly setup connection. This step is performed by the customer. ZorgDomein will send a ZD Activation Verfication containing a ZD Verification Code extension to the customer’s XIS. The ZD Verification Code extension contains a verification code that is used to verify the established connection.

7. XIS presents verfication code to customer

After the verification code has been extracted from the document thas has been received  by the XIS, the  XIS should present this verification code is presented to the customer. The XIS is free to choose how the code is presented to the customer. It can be a notification in the user interface of the XIS, an e-mail, sms or any other message, as long as the XIS can assure that only the intended user has access to the code. 

8. Customer enters verification code in ZorgDomein

To verify and finalize the auto-activation process the customer must enter this verification code, as presented by the XIS, in ZorgDomein. After verification, auto-activation has been completed and the customer will receive messages from ZorgDomein which are automatically processed in the customer’s XIS.