Purpose

This web service is designed to change contract request by nhs employee. NHS employee should enrich contract request with information about itself, sum and place of the contract request and could change status of contract request. 

Overview

• NHS employee with scopes 'contract_requests:update' can change contract request
• Contract request only in status 'NEW' could be changed. 
• NHS employee can change only several field of the contract request but not all of them

Specification

• apiary
• json_schema

Request

Validation

Validate token

• Verify the validity of access token
  • Return 401 in case validation fails
• token is not expired
  • in case error return 401 - "Token is expired"

Validate user

extract user_id from token

extract client_id from token

• Check if user is active
  • in case error return 403 - (user is not active)
• check nhs_legal_entity is active
  • in case error return 403 - (Client is not active)

Validate scopes

• Check user scopes in order to perform this action (scope = 'contract_requests:update')
  • Return 403 in case invalid scope(s) "Your scope does not allow to access this resource. Missing allowances: contract_requests:update"

Validate status

• Check contract_request.status=NEW
  • in case error return 422 - "Incorrect status of contract_request to modify it"

Validate changed fields

• Only next field could be changed by nhs employee
  • issue_city
    • Set issue_city = nhs_le.addresses.settlement_name, where address_type=REGISTRATION
  • nhs_base 
  • price
  • status (enum)
    • Approved
    • Declined
  • status_reason

Response

Generate human readable contract request number

If status is changed to APPROVED - generate human readable contract request number

• Use algorithm to generate contract request number
• contract request number structure XXXX-1234-5678-9012-345-C , where:
  • XXXX - series: numbers + only some letters (A, E, H, K, M, P, T, X)
  • 1234-5678-9012-345 - randomly generated numbers and letters A, E, H, K, M, P, T, X.
  •  C - checksum: Should be calculated using the Damn algorithm or Verhoeff algorithm

Validate uniqueness of human readable contract request number

• generate contract_request_number
• Search contract request number in contract_requests.contract_number
• if exists = go to 'generate contract request number'
• else save contract_request_number to contract_request

Generate Printout form 

If status is changed to APPROVED - generate printout form

Invoke MAN to render printuot form.

Request mapping:

curl --request POST \
     --header 'Accept: text/html' \
     --header 'Content-Type: application/json' \
     {:host}/templates/{:contract_printout_id}/actions/render

Set IL.contract_request.printout_content:

if status was changed (status = APPROVED, DECLINED or SIGNED) - add new status to event_manager