Purpose

This WS allows to create new medication program participant.

Specification

Link	API paragraph not found
Resource	/program_medications
Scope	program_medication:write
Components	Drugs and Program medications
Microservices	API paragraph not found
Protocol type	REST
Request type	POST
Sync/Async	Sync
Public/Private/Internal	Internal. NHS Admin

Logic

Create new program medication entity: store input into program_medications table (prm). Also, set:
1. medication_request_allowed = true
2. is_active = true
3. inserted_at, updated_at = user_id (from token)
4. inserted_at, updated_at = current date and time.

Key points

This is a graphQl method used in the Administration panel only.
Only authenticated and authorized NHS employee with an appropriate scope can create a Program medication.
Program medication can be created only for a medical program with type MEDICATION.

GraphQl Specification

createProgramMedication

"Creates a single `ProgramMedication`."
  createProgramMedication(
    input: CreateProgramMedicationInput!
  ): CreateProgramMedicationPayload

"""
Input for `createProgramMedication` mutation.
User must have a scope **program_medication:write**
"""
input CreateProgramMedicationInput {
  "Id of medication"
  medicationId: ID!
  "Medical program Identifier"
  medicalProgramId: ID!
  "Reimbursement information"
  reimbursement: CreateReimbursementInput!
  "Factory gate price for package of medications"
  wholesalePrice: Float
  "Consumer price for package of medications"
  consumerPrice: Float
  "Reimbuersement amount for recommended daily dosage of medication"
  reimbursementDailyDosage: Float
  "The estimatied amount which patient should pay for package of medications after reimbursement"
  estimatedPaymentAmount: Float
  "Start date of action for this entry"
  startDate: Date
  "End date for this entry"
  endDate: Date
  "General registry identifier"
  registryNumber: String
}

"""
Input for `Reimbursement` of `createProgramMedication` mutation.
"""
input CreateReimbursementInput {
  "Reimbursement type"
  type: ReimbursementType!
  "Reimbursement amount"
  reimbursementAmount: Float
  "Percentage of reimbursement."
  percentageDiscount: Float
}

"""
Return type for `createProgramMedication` mutation.
"""
type CreateProgramMedicationPayload {
  "Created `ProgramMedication`."
  programMedication: ProgramMedication
}

"""
Program Medication linkes medication and medical program.
In order to obtain details user must have a scope **program_medication:read**
"""
type ProgramMedication implements Node {
  "The ID of an object."
  id: ID!
  "Primary key identifier from the database."
  databaseId: UUID!
  "MedicalProgram."
  medicalProgram: MedicalProgram!
  "Medication"
  medication: Medication!
  "Reimbursement information."
  reimbursement: Reimbursement!
  "Factory gate price for package of medications"
  wholesalePrice: Float
  "Consumer price for package of medications"
  consumerPrice: Float
  "Reimbuersement amount for recommended daily dosage of medication"
  reimbursementDailyDosage: Float
  "The estimatied amount which patient should pay for package of medications after reimbursement"
  estimatedPaymentAmount: Float
  "Start date of action for this entry"
  startDate: Date
  "End date for this entry"
  endDate: Date
  "General registry identifier"
  registryNumber: String
  "Whether `ProgramMedication` is active or not?"
  isActive: Boolean!
  "Whether requesting medications allowed for the `ProgramMedication` or not?"
  medicationRequestAllowed: Boolean!
  "Date and time when record was inserted"
  insertedAt: DateTime!
  "Date and time when record was updated"
  updatedAt: DateTime!
}

Request structure*

See on Apiary

Request example

{
  "medication_id": "59781de0-2e64-4359-b716-bcc05a32c10f",
  "medical_program_id": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
  "reimbursement": {
    "type": "fixed",
    "reimbursement_amount": 450
  },
  "wholesale_price": "148.50",
  "consumer_price": "150.00",
  "daily_dosage": "200",
  "reimbursement_daily_dosage": "10.4858",
  "estimated_payment_amount": "34.50"
}

Authorize

Verify the validity of access token
- in case of error - 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 = 'program_medication:write')
- return 403 (“Your scope does not allow to access this resource. Missing allowances: program_medication:read”) in case of invalid scope(s).

Request to process the request using a token in the headers

Headers

Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9

Request data validation

Validate legal entity

Extract client_id from token.
Check client scopes in order to perform this action (scope = 'program_medication:write')
- in case of error - return 403 (“Your scope does not allow to access this resource. Missing allowances: program_medication:write”).

Validate request

Check medicalProgramId:
1. exists in DB
  1. in case of error - return 404 ('not_found')
2. has type = MEDICATION
  1. in case of error - return 409 ('MedicalProgram type should be MEDICATION')
3. is_active = true
  1. in case of error - return 409 ('Medical program is not active')
Check start_date < end_date
1. in case of error - return 422 ('must be earlier than the end date')
Validate reimbursement:
1. If reimbursement type = FIXED, than reimbursementAmount field required
2. If reimbursement type = PERCENTAGE, percentageDiscount field required
  1. in case of error - return 422 ('can't be blank')
If percentageDiscount submitted in the reimbursement structure:
1. Check it’s value in range from 0 to 100
  1. in case of error - return 422 ('expected the value to be <= 100')
Validate medicationId:
1. Check it is active and it’s type is BRAND
  1. in case of error - return 409 ('Medication is not active')
Validate compliance of INNM_DOSAGE.mr_blank_type of a BRAND to medicalProgram.mr_blank_type:
1. Check INNM_DOSAGE
  1. There is link of a BRAND to INNM_DOSAGE (in prm.ingredients table) and INNM_DOSAGE exists
    1. in case of error - return 404 ('INNM_DOSAGE of a BRAND not_found')
  2. is_active = true
    1. in case of error - return 409 ('INNM_DOSAGE of a BRAND is not active')
2. Check compliance of INNM_DOSAGE of a BRAND to medicalProgram
  1. if INNM_DOSAGE.mr_blank_type = medicalProgram.mr_blank_type
    (i.e prm.medications.mr_blank_type = prm.medical_programs.mr_blank_type)
    1. in case of error - return 422 ('Dosage form of selected Medication does not comply with mr_blank_type requirement of Medical Program')

Processing

API paragraph not found

Response structure

See on Apiary

Request example

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "medication": {
      "id": "09b2bffb-699a-43c0-bc9a-5066d9b9b5a8",
      "name": "Амідарон",
      "manufacturer": {
        "name": "ПАТ \"Київський вітамінний завод\"",
        "country": "UA"
      },
      "code_atc": [
        "М01АЕ01",
        "C01BD01"
      ],
      "form": "PILL",
      "container": {
        "numerator_unit": "PILL",
        "numerator_value": 1,
        "denumerator_unit": "PILL",
        "denumerator_value": 1
      },
      "package_qty": 30,
      "package_min_qty": 10,
      "daily_dosage": "12",
      "certificate": "UA/4514/01/01",
      "certificate_expired_at": "2021-02-09",
      "ingredients": [
        {
          "id": "1349a693-4db1-4a3f-9ac6-8c2f9e541982",
          "name": "Амідарон",
          "dosage": {
            "numerator_unit": "MG",
            "numerator_value": 200,
            "denumerator_unit": "PILL",
            "denumerator_value": 1
          },
          "is_primary": true
        }
      ],
      "is_active": true,
      "inserted_at": "2017-04-20T19:14:13Z",
      "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
      "updated_at": "2017-04-20T19:14:13Z",
      "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd",
      "drlz_sku_id": "0404466792737630283703997321"
    },
    "medical_program": {
      "id": "c7d52544-0bd4-4129-97b0-2d72633e0490",
      "name": "Доступні ліки",
      "medical_program_settings": {
        "care_plan_required": true,
        "employee_types_to_create_medication_request": [
          "SPECIALIST",
          "DOCTOR"
        ],
        "skip_mnn_in_treatment_period": true,
        "skip_employee_validation": true,
        "speciality_types_allowed": [
          "ENDOCRINOLOGY",
          "PEDIATRIC_NEUROLOGY"
        ],
        "conditions_icd10_am_allowed": [
          "A00.0",
          "A00.1"
        ],
        "conditions_icpc2_allowed": [
          "A01",
          "A02"
        ],
        "providing_conditions_allowed": [
          "INPATIENT",
          "OUTPATIENT"
        ],
        "medication_request_max_period_day": 90,
        "skip_medication_request_employee_declaration_verify": true,
        "skip_medication_request_legal_entity_declaration_verify": true,
        "multi_medication_dispense_allowed": true,
        "skip_medication_dispense_sign": true,
        "medication_request_notification_disabled": true,
        "skip_contract_provision_verify": true,
        "medication_dispense_period_day": 90
      },
      "medical_program_settings_text": "Some text",
      "is_active": true,
      "medication_dispense_allowed": true,
      "medication_dispense_allowed_text": "Some text",
      "medication_request_allowed": true,
      "medication_request_allowed_text": "Some text",
      "type": "MEDICATION",
      "funding_source": "NHS",
      "mr_blank_type": "F-1",
      "inserted_at": "2017-04-20T19:14:13Z",
      "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
      "updated_at": "2017-04-20T19:14:13Z",
      "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
    },
    "medication_request_allowed": true,
    "reimbursement": {
      "type": "fixed",
      "reimbursement_amount": 450
    },
    "wholesale_price": "148.50",
    "consumer_price": "150.00",
    "daily_dosage": "200",
    "reimbursement_daily_dosage": "10.4858",
    "estimated_payment_amount": "34.50",
    "is_active": true,
    "inserted_at": "2017-04-20T19:14:13Z",
    "inserted_by": "e1453f4c-1077-4e85-8c98-c13ffca0063e",
    "updated_at": "2017-04-20T19:14:13Z",
    "updated_by": "2922a240-63db-404e-b730-09222bfeb2dd"
  }
}

Request example

{
  "meta": {
    "code": "409",
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "error": {
    "type": "duplicate",
    "message": "Current medication is already the participant of this program"
  }
}

Request example

{
  "meta": {
    "code": "422",
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "error": {
    "type": "unverified",
    "message": "This program is inactive"
  }
}

HTTP status codes

HTTP status code	Message	What caused the error
200	Response
201
401	Invalid access token
403	Your scope does not allow to access this resource. Missing allowances: program_medication:read
404	Not found	medicalProgramId exists in DB check fails. INNM_DOSAGE of a BRAND not_found.
409	INNM_DOSAGE of a BRAND is not active. Medication is not active. Medical program is not active. MedicalProgram type should be MEDICATION.
422	must be earlier than the end date. can't be blank. expected the value to be <= 100. Dosage form of selected Medication does not comply with mr_blank_type requirement of Medical Program.

Create Program medication

Purpose

Specification

Logic

Key points

GraphQl Specification

Request structure*

Authorize

Headers

Request data validation

Validate legal entity

Validate request

Processing

Response structure

HTTP status codes