RC_(GraphQL) Update Confidant person relationship (DRACS 2.0)

1 Purpose
2 Key points
- 2.1 Status transitions
3 Specification
4 Authorize
5 Validate legal entity
6 Validate request
7 Service logic

Purpose

This WS is designed to allow NHS employee with assigned appropriate scopes to update confidant person relationships details.

Key points

This is a graphQl query method used in Administration panel only.
Only authenticated and authorized NHS employee with appropriate scope can update confidant person relationships details.
Only confidant person relationship verification details and document details with type BIRTH_CERTIFICATE can be updated now.

Status transitions

Allowed confidant person relationship verification status transitions for method:

from verification_status = NOT_VERIFIED and verification_reason = AUTO to verification_status = IN_REVIEW and verification_reason = MANUAL
from any verification_status to verification_status=VERIFICATION_NEEDED and verification_reason=ONLINE_TRIGGERED
from verification_status = IN_REVIEW and verification_reason = MANUAL to verification_status = NOT_VERIFIED and verification_reason = MANUAL with required verification_comment
from verification_status = IN_REVIEW and verification_reason = MANUAL to verification_status = VERIFIED and verification_reason = MANUAL with required dracs_birth_act_id

Specification

  "Update confidant person relationship for a single `Confidant person relationship` using its globally unique ID."
  updateConfidantPersonRelationship(
    input: UpdateConfidantPersonRelationshipInput!
  ): UpdateConfidantPersonRelationshipPayload

"""
Input for `updateConfidantPersonRelationship` mutation.
"""
input UpdateConfidantPersonRelationshipInput {
  "Primary key identifier from MPI.confidant_person_relationships"
  confidantPersonRelationshipId: UUID!
  "DRACS birth act unique identifier."
  dracsBirthActId: UUID
  "Confidant person relationship verification status"
  verificationStatus: ConfidantPersonRelationshipVerificationStatus
  "Confidant person relationship verification reason"
  verificationReason: ConfidantPersonRelationshipVerificationReason
  "Description about confidant person verification status"
  verificationComment: String
  "Confidant person relationship documents"
  documentsRelationship: [ConfidantPersonRelationshipDocuments]
}

"""
Return type for `updateConfidantPersonRelationship` mutation.
"""
type UpdateConfidantPersonRelationshipPayload {
  "Confidant person relationship of a Person"
  confidantPersonRelationship: ConfidantPersonRelationship
}

"""
Confidant person relationship verification status
"""
enum ConfidantPersonRelationshipVerificationStatus {
  NOT_VERIFIED
  IN_REVIEW
  NOT_VERIFIED
}

"""
Confidant person relationship verification reason
"""
enum ConfidantPersonRelationshipVerificationReason {
  AUTO
  MANUAL
}

"""
The documents of person who is responsible for the patient.
"""
input ConfidantPersonRelationshipDocuments {
  "Type of document. The value should be present in the `DOCUMENT_RELATIONSHIP_TYPE` dictionary."
  documentType: String!
  "Number of the document."
  documentNumber: String!
  "Authority which issued the document."
  issuedBy: String
  "The date when document was issued."
  issuedAt: String
}

Authorize

Verify the validity of access token
- Return (401, 'Invalid access token') in case of validation fails
Verify that token is not expired
- in case of error - return (401, 'Invalid access token')
Check user scopes in order to perform this action (scope = 'confidant_person_relationship_admin:write')
- Return (403, 'Your scope does not allow to access this resource. Missing allowances: confidant_person_relationship_admin:write') in case of invalid scope(s)

Validate legal entity

Extract client_id from token.
Check legal entity status (status = ACTIVE)
- In case of error - return 409 ('client_id refers to legal entity that is not active')
Check client type (type = NHS)
- In case of error - return 403 ('You don't have permission to access this resource')

Validate request

Check that at least one of field combination is submitted: verificationStatus and verificationReason or documentsRelationship
- in case of error - return 422 ('Verification details or document relationships must be submitted')

Field confidantPersonRelationshipId, required

Check it is submitted
- in case of error - return 422 ('required property <name/creation_reason> was not present')
Check that confidant person relationship exists in mpi.confidant_person_relationships table and is active (active_to > now() or is null)
- in case of error - return 404 ('Such relationship doesn't exist')
Check if person from confidant person relationship is active: person.status = 'active' and person.is_active = true
- in case of error - return 422 ('Person from confidant person relationship isn't active')

Field verificationStatus, optional

Check value is allowed according to schema.
- in case of error - return 422 ('value is not allowed in enum')
Check status transition allowed according to list.
- in case of error - return 422 ('Can\'t update verification status from <old status value> to <new status value>')

Field verificationReason, optional

Check value is allowed according to schema.
- in case of error - return 422 ('value is not allowed in enum')
Check status transition allowed according to list.
- in case of error - return 422 ('Can\'t update verification status from <old status value> with <old verification reason> verification reason to <new status value> with <new verification reason> verification reason')

Field verificationComment, required at specific case

if verification_status = NOT_VERIFIED and verification_reason = MANUAL
- in case of error - return 422 ('verification status comment is required')

Field documentType, optional

Check it is submitted
- in case of error - return 422 ('required property <name/creation_reason> was not present')
Check that BIRTH_CERTIFICATE value is submitted
- in case of error - return 422 ('Only BIRTH_CERTIFICATE document type is allowed')
Check that confidant person relationship has BIRTH_CERTIFICATE document type
- in case of error - return 422 ('Confidant person relationship does not have document with type birth certificate')

Field dracsBirthActId, required at specific case

Check dracsBirthActId is submitted only in case if verification_status = VERIFIED and verification_reason = MANUAL.

Check if dracsBirhtActId field is not empty
- in case of error - return 422 ('DRACS birth act is required')
Check if dracsBirthActId exists in mimir db, dracs_birth_acts table
1. in case of error - return 422 ('DRACS birth act with such ID is not found')

Service logic

Update confidant person relationship based on submitted data:
1. if verificationStatus, verificationReason and verificationComment submitted, set fields in confidant_person_relationship table (mpi database):
  1. verification_status = $.verification_status
  2. verification_comment = $.verification_comment
  3. verification_reason = $.verification_reason
  4. unverified_at = now() (if $.verification_status <> NOT_VERIFIED)
  5. dracs_birth_synced_at = null (if $.verification_status = VERIFICATION_NEEDED and $.verification_reason = ONLINE_TRIGGERED)
  6. dracs_birth_act_id = $.dracs_birth_act_id
  7. updated_by = user_id (from token)
  8. updated_at = current timestamp
2. if documentsRelationship submitted, set fields in confidant_person_relationship_documents table (mpi database) for document type = BIRTH_CERTIFICATE and confidant_person_relationship_id = $.confidantPersonRelationshipId:
  1. number = $.documentNumber
  2. issued_at = $.issuedAt (if exists in request, else skip update)
  3. issued_by = $.issuedBy (if exists in request, else skip update)
  4. updated_by = user_id (from token)
  5. updated_at = current timestamp
In case if $.verification_status = VERIFIED - check existence of confidant person relationships verification candidates (where confidant_person_relationship_id == $.confidant_person_relationship_id and entity_type = ‘dracs_birth_act’ and status = ‘NEW’) in person_relationship_verification_candidates table (mpi database), if found - update them, set values:
1. status = CONFIRMED
2. updated_at = current timestamp
Render a response according to specification.