C_12531_Anlage

Änderungen in I_Information_Service_Accounts.yaml

Die Operationen für einen Merge orientieren sich an den Operationen für eine Relocation, sind von diesen aber unabhängig, Sie setzen in erster Linie auf anderen Ausgangszuständen auf und bedingen selbst keine Statusänderung des Aktenkontos. Die Verwendung einer Vorgangsidentifikation und die Möglichkeiten der Fehler-, bzw Erfolgsmeldung sind analog. 

(Swagger-Ansicht informativ)

Merge (merge provider)

Merge (merger)

Änderung in OpenApi

  /information/api/v1/accounts/mergepackagegeneration:
    get:
      parameters:
        - $ref: '#/components/parameters/insurantid'
        - $ref: '#/components/parameters/x-requestid'
      tags:
        - Merge (merge provider)
      operationId: startMerge
      summary: (startMerge) Initiate merge package preparation for download
      description: |
       Starts a new health record merge process and initiates the preparation of a merge package
       of an existing health record addressed by _insurantid_. A _requestId_ for process reference is returned.
       The 'Merge Provider' and the 'Merge' side responsible actors shall negotiate the merge proccess in advance
       and set the health record on merge provider side to state INACCESSIBLE with sole reason 'ready for merge' as
       preparation for the merge process.
       **Client**  
       A client shall use this operation when a health record of an insurant hosted by another health
       record system shall be integrated into the local (hosted by client) health record of the insurant.
       A client shall monitor the started process and react on incidents received via _postMergePackageDeliveryIncident_.
       A client shall also monitor the notification about a prepared merge package for download via _putDownloadUrlForMergePackage_.
       If no url is available after a suitable waiting period, a request for url propagation shall be issued using
       _urlNotReceived_ via _postMergePackageIncident_.
       **Provider**  
       Creates a _requestId_ to identify the merge process among the following operations. The addressed
       health record shall exist and have the state INACCESSIBLE with sole reason 'ready for merge' for
       package preparation.  
       
       The provider shall add a resource identified by _requestId_ (as just created) in provider's
       _Information Service Account_ path _/accounts/v1/mergepackagegeneration/{requestid}_
       to enable reception of notifications about this particular request.      
       
       The health record merge package generation shall be initialized by passing the _requestId_ and _insurantId_
       to the responsible actor (insurance company associated to provider) by proprietary means.
       The reponsible actor thereafter is in charge to:
       - accept the merge request and trigger merge package generation using operation _startPackageCreationForMerge_
       (I_Health_Record_Relocation_Service) or
       - reject the merge request and terminate the process using _postMergePackageDeliveryIncident_ with
       _mergeAborted_ incident (this interface).

       | Conditions | Status code | Error code | Remarks |
       |------------|-------------|------------|---------|
       | Successful operation | 200 |||
       | Request does not match schema | 400 | malformedRequest ||
       | No mutual TLS channel used | 403 | accessDenied ||
       | Health record does not exist (UNKNOWN) or is in state INITIALIZED | 404 | noHealthRecord | |
       | Health record is not in state INACCESSIBLE with sole reason 'ready for merge' | 409 | statusMismatch |
       also if state is INACCESSIBLE with another or additional reason than 'prepared for a merge' |
       | Any other error | 500 | internalError ||
       </br>
       | Postconditions                        | Remarks |
       |---------------------------------------|---------|
       | Merge package preparation is internally requested ||
       | A resource with id _requestId_ is available via path ||
      responses:
        '200':
          description: Ok.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/xrequestid'
          content:
            application/json:
              examples:
                A new request:
                  value:
                    requestId: '2d4706b4-c29d-4ff6-b827-e06e6d9e2c0b'
              schema:
                type: object
                properties:
                  requestId:
                    $ref: '#/components/schemas/RequestIdType'
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '409':
          $ref: '#/components/responses/Error409Conflict'
        '500':
          $ref: '#/components/responses/Error500InternalError'
  /information/api/v1/accounts/mergepackagegeneration/{requestid}:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/x-requestid'
      - $ref: '#/components/parameters/requestid'
    delete:
      tags:
        - Merge (merge provider)
      operationId: finalizeMerge
      summary: (finalizeMerge) confirms the completion of a merge session
      description: |
       Finalizes the merge process and requests deletion of an existing merge package.
       **Client**  
       The client (merger) shall always invoke this operation after a successful download
       of a merge package and integration of reveived data via
       _startPackageImport_ (I_Health_Record_Relocation_Service).
       A merge session is complete once the client has received a success confirmation  
       as response ('204')
       A client shall invalidate _requestId_ and delete the merge package received.
       **Provider**  
       The merge package shall be deleted and the associated download url and the used
       _requestId_ shall no longer be valid.
       
       The information about successful completion of the merge session
       shall be passed to the responsible actor (insurance company associated to provider) by
       proprietary means for possible subsequent actions (e.g. the subsequent complete deletion of the health record).
       | Conditions | Status code | Error code | Remarks |
       |------------|-------------|------------|---------|
       | Successful operation | 204 |||
       | Request does not match schema | 400 | malformedRequest ||
       | No mutual TLS channel used | 403 | accessDenied ||
       | Request unknown (_requestid_ ) | 404 | noResource | no ongoing merge request for this id known |
       | Any other error | 500 | internalError ||
       </br>
       | Postconditions                        | Remarks |
       |---------------------------------------|---------|
       | Merge package and requestId deleted ||
      responses:
        '204':
          description: Ok. Export package and requestId deleted
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '500':
          $ref: '#/components/responses/Error500InternalError'
    post:
      tags:
        - Merge (merge provider)
      operationId: postMergePackageIncident
      summary: (postMergePackageIncident) Notify merge package provider about problems
      description: |
       Notify the merge provider about problems receiving or merging the merge package.</br>
       **Client**:</br>
       A client shall always invoke this operation when merge package download
       or data merging was not successful, not possible or no longer required, i.e. in all cases where
       a once started merge process can not be succesfully completed at all.
       A client shall invalidate _requestId_ and delete the merge package (if yet downloaded).
       
       **Provider**:</br>
       The information shall be passed to the responsible actors (insurance company associated to provider)
       by proprietary means to allow subsequent actions.
       Incidents shall cause the following behaviour:
       - mergeAborted:
         - The merge process is no longer required or can not be completed for any reason on client side (merger).
         The merge process is terminated early by the client, the merge package shall be deleted and the _requestId_ of the process
         shall be invalidated. The process can not be resumed - if transfer for merge is still required, a whole
         new process shall be initialitized by the client.
       - importFailed:
         - The download of a prepared merge package was not possible, not complete or not decryptable or does not match _insurantId_.
        The merge package provider shall solve the problem - possibly after consultations about the cause -and prepare a corrected
        package version. The client (merger) shall be notified about the new package via _putDownloadUrlForMergePackage_.
        If correction is too time consuming or not applicable, the request may be aborted by the merge provider.
        The client (merger) shall be notified about this case
        by a _mergeAborted_ incident via_postPackageDeliveryIncident_ operation call.
       - packageCorrupt:
         - The package content was not understood, of wrong structure or malformed. A corrected package
        shall be deployed as for incident _importFailed_.
       - urlNotReceived
         - The merge package download-url has not been received yet.
         The download-url shall be posted as soon as possible or transfer shall be aborted,
         including notification by a _postPackageDeliveryIncident_ operation call.
       | Conditions | Status code | Error code | Remarks |
       |------------|-------------|------------|---------|
       | Successful operation | 204 |||
       | Request does not match schema | 400 | malformedRequest ||
       | No mutual TLS channel used | 403 | accessDenied ||
       | Request unknown (_requestid_ ) | 404 | noResource | no ongoing merge request for this id known |
       | Any other error | 500 | internalError ||
       </br>
       | Postconditions                        | Remarks |
       |---------------------------------------|---------|
       | Incident delivered internally||

      requestBody:
        required: true
        content:
          application/json:
            examples:
              Download failed:
                value:
                  'importFailed'
              Package corrupt:
                value:
                  'packageCorrupt'
            schema:
              description: |
               An incident about reception and integration of a merge package:
                - 'mergeAborted' : merge process aborted (request will possibly be restarted after clarification)
                - 'importFailed' : download not possible (no content, not complete, decryption error)
                - 'packageCorrupt' : package not processable (corrupt or content structure unknown)
                - 'urlNotReceived' : url not received
              type: string
              enum:
                - 'mergeAborted'
                - 'importFailed'
                - 'packageCorrupt'
                - 'urlNotReceived'
      responses:
        '204':
          description: Ok.
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '500':
          $ref: '#/components/responses/Error500InternalError'

  /information/api/v1/accounts/mergepackagedelivery/{requestid}:
    parameters:
      - $ref: '#/components/parameters/insurantid'
      - $ref: '#/components/parameters/x-requestid'
      - $ref: '#/components/parameters/requestid'
    put:
      tags:
        - Merge (merger)
      operationId: putDownloadUrlForMergePackage
      summary: (putDownloadUrlForMergePackage) Provide url to prepared merge package for download
      description: |
       Provide url to prepared merge package for download.
       **Client**:</br>
       A client shall invoke this operation when a merge package is available and has valid
       download url (i.e. package is ready for instant download).
       **Provider**:</br>
       The received _download-url_ and the associated _requestId_ shall be passed to the
       responsible actor (insurance company associated to provider) by proprietary means.
       The reponsible actor is thereafter in charge to initialize the data merge itself and call _startPackageMergeImport_
       of I_Health_Record_Relocation_Service for download and merge.
       | Conditions | Status code | Error code | Remarks |
       |------------|-------------|------------|---------|
       | Successful operation | 204 |||
       | Request does not match schema | 400 | malformedRequest ||
       | No mutual TLS channel used | 403 | accessDenied ||
       | Request unknown (_requestId_ ) | 404 | noResource | no ongoing merge request for this id known |
       | Any other error | 500 | internalError ||
       </br>
       | Postconditions                        | Remarks |
       |---------------------------------------|---------|
       | Export package download is internally requested ||
      requestBody:
        required: true
        content:
          application/json:
            examples:
              Download ready:
                value:
                  downloadurl: 'http://example.com'
            schema:
              type: object
              properties:
                downloadurl:
                  $ref: '#/components/schemas/UrlType'
      responses:
        '204':
          description: Ok.
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '500':
          $ref: '#/components/responses/Error500InternalError'
    post:
      tags:
        - Merge (merger)
      operationId: postMergePackageDeliveryIncident
      summary: (postMergePackageDeliveryIncident) Notify merge package requestor about problems
      description: |
       Notify a merge package requestor about problems preparing the merge package.</br>
       **Client**:</br>
       A client (merge provider) shall always invoke this operation when merge package provision is not possible,
       shall be revoked or is significantly delayed or success notification is pending too long, i.e a client either initiates the
       termination of the merge process due to client side problems or request the completion or even abortion
       carried out by the provider (the _merger_ side).
       A client sending a _mergeAborted_ incident shall invalidate _requestId_, _download-url_ and delete the merge package
       on client side.
       
       **Provider**:</br>
       The information shall be passed to the responsible actor (insurance company associated to provider)
       by proprietary means to allow suitable actions of the actor.
       Incidents shall cause the following behaviour:
        - noMergeConfirmation
          - The notification about a successful merge of content or about incidents has not been received yet.
          Request will be terminated after a suitable waiting period.
        - mergeAborted:
          - Merge package can not or no longer be provided.
          Request shall be terminated, _requestId_ shall be invalidated and a merge package shall be deleted (if any).
 
       
       | Conditions | Status code | Error code | Remarks |
       |------------|-------------|------------|---------|
       | Successful operation | 204 |||
       | Request does not match schema | 400 | malformedRequest ||
       | No mutual TLS channel used | 403 | accessDenied ||
       | Request unknown (_requestid_ ) | 404 | noResource | no ongoing relocation request for this id known |
       | Any other error | 500 | internalError ||
       </br>
       | Postconditions                        | Remarks |
       |---------------------------------------|---------|
       | Incident delivered internally ||
       | Request aborted | mergeAborted only |
      requestBody:
        required: true
        content:
          application/json:
            examples:
              Export package generation waiting for bugfix:
                value:
                  'noMergeConfirmation'
            schema:
              description: |
               An incident about request of a merge package:
                - 'noMergeConfirmation' : waiting for merge confirmation.
                - 'mergeAborted' : can not provide merge package or merge aborted. Retry of request recommended
              type: string
              enum:
                - 'noMergeConfirmation'
                - 'mergeAborted'
      responses:
        '204':
          description: Ok.
        '400':
          $ref: '#/components/responses/Error400BadRequest'
        '403':
          $ref: '#/components/responses/Error403Forbidden'
        '404':
          $ref: "#/components/responses/Error404NotFound"
        '500':
          $ref: '#/components/responses/Error500InternalError'