...

Table of Contents

...

This WS is designed to create new medication (post).

APIary

create-medication

Input parameters (filters)

name
start_at
route
container_dosage info
package_qty
package_min_qty
code_ATX
manufacturer_name_country info
certificate
expired_certificate_date
ingridients info
- innm_id
- dosage info
- is_active_substance

Authorize

Verify the validity of access token
Check user scope (scope = 'medication:write') in order to perform this action
1. In case error - generate 401 response

Validate request (JSON schema)

Validate request using JSON schema (link !!! TBD)

Validate Innm

Check unique by `innm_identifier`.
1. if found - return 409 error (message: "Duplicate innm identifier!")

Validate Dosage & Container dosage

Purpose validation: Denum unit from Dosage must be is equal Denum unit from Container dosage. See examples: Medications model

Check exist any Denum unit from Dosage ($.ingridients[].dosage.denumerator_unit) with Denum unit Container dosage ($.container_dosage.denumerator_unit).
if invalid - return 422 error (message: "Denum unit from Dosage ingridients must be is equal Denum unit from Container dosage medication!")

...

Table of Contents

minLevel	1
maxLevel	3

Purpose

This WS is designed to create new medication.

Specification

Page Properties

Link	API paragraph not found
Resource	/medications
Scope	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

Logic

This method is used to create Medications. Fields descriptions are listed in request Example view.

Request structure

See on Apiary

Example:

Expand

title	Request example

Code Block

{
  "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,
  "certificate": "UA/4514/01/01",
  "certificate_expired_at": "2021-02-09",
  "daily_dosage": "12",
  "ingredients": [
    {
      "id": "1349a693-4db1-4a3f-9ac6-8c2f9e541982",
      "dosage": {
        "numerator_unit": "MG",
        "numerator_value": 200,
        "denumerator_unit": "PILL",
        "denumerator_value": 1
      },
      "is_primary": true
    }
  ]
}

Authorize

Verify the validity of access token
Check user scope (scope = 'medication:write') in order to perform this action
1. In case error - generate 401 response

Request to process the request using a token in the headers

Headers

Наприклад:

Content-Type:application/json
Authorization:Bearer c2778f3064753ea70de870a53795f5c9

Request data validation

Validate FK

Purpose validation: Check on existing Substance/Innm in ingredients

Check exist `Medications` by $.ingredients[].id.
1. if invalid - return 422 error (message: "INNM in ingredients is not found!")

Validate status & type ingredients

Purpose validation: Id's in ingredients must be active

Invoke GetInnmByID($.ingredients[].id). Check exist any innm.is_active=FALSE.
1. if exists - return 422 error (message: "INNM in ingredients must be active!")

Purpose validation: Ingredients for TYPE=BRAND must be TYPE=INNM_DOSAGE

Check exists Ingredients with type=BRAND.
1. if exists - return 422 error (message: "Only INNM_DOSAGE can be ingredients!")

Validate status ingredients.is_primary

Purpose validation: in ingredients only one item must be is primary (TRUE)

Calculate count() where is_primary=TRUE in ingredients. Check count()>=1.
1. if invalid - return 422 error (message: "One of ingredients must be is primary!")

Validate Equal Dosage & Container

Purpose validation: Denumerator unit from Ingredients.dosage must be equal Numerator unit from Container.

Check exist any ($.ingredients[].dosage.denumerator_unit != $.container.numerator_unit).
1. if invalid - return 422 error (message: "Denumerator unit from Dosage ingredients must be equal Numerator unit from Container medication!")

Validate multiplicity

Purpose validation: Package_qty for container_dosage must have multiplicity package_min_qty. Result (Mod or % operator) must = 0 .

MEDICATION - Validate multiplicity (Mod == 0) $.package_qty Mod $.package_min_qty == 0
if result NOT 0 - return 409 error (message: "Only a multiplicity package quantity for the minimum package quantity medication!")

Validate atc code

Validate value according to regex ^[abcdghjlmnprsvABCDGHJLMNPRSV]{1}[0-9]{2}[a-zA-Z]{2}[0-9]{2}$
1. in case of error return ('Invalid code')
Check that all elements in array of atc_code are different
1. in case of error return 422 error (message `atc codes are duplicated`)

Validate request

Validate request using features.

Expand

Code Block

Feature: Create medication

  Scenario Outline: Successful creation
    Given my scope is "medication:write"
    And my client type is "NHS"
    And my consumer ID is "1ad3c0e6-e2fc-2d3c-a15c-5101874165a7"
    And the following INNM dosages exist:
      | databaseId        |
      | <innmDosageId>  |
    When I create medication with attributes:
      | name   | atcCodes   | certificate   | certificateExpiredAt   | container   | dailyDosage   | form   | ingredients   | manufacturer   | packageMinQty   | packageQty   |
      | <name> | <atcCodes> | <certificate> | <certificateExpiredAt> | <container> | <dailyDosage> | <form> | <ingredients> | <manufacturer> | <packageMinQty> | <packageQty> |
    Then no errors should be returned
    And request id should be returned
    And I should receive requested item
    And the name of the requested item should be <name>

    Examples:
      | name      | innmDosageId                           | atcCodes               | certificate | certificateExpiredAt | container                                                                                           | dailyDosage | form                           | ingredients                                                                                                                                                                                      | manufacturer                        | packageMinQty | packageQty |
      | "Ниферон" | "01c9b8ae-fe41-4390-8f3c-4744f5b13717" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 50}   | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}]   | {"name": "Bayer", "country": "GER"} | 1             | 5          |
      | "Ниферон" | "01c9b8ae-fe41-4390-8f3c-4744f5b13717" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 0.5, "denumerator_unit": "ML", "denumerator_value": 50} | 0.01        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 0.5, "denumerator_unit": "ML", "denumerator_value": 50}, "is_primary": true}] | {"name": "Bayer", "country": "GER"}  | 1             | 5          |

  Scenario: Create with incorrect scope
    Given my scope is "medication:read"
    And my consumer ID is "04796283-74b8-4632-9f7f-9e227ae9426e"
    When I create medication with attributes:
      | name      | atcCodes               | certificate | certificateExpiredAt | container                                                                                         | dailyDosage | form                           | ingredients                                                                                                                                                                                    | manufacturer                        | packageMinQty | packageQty |
      | "Ниферон" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 50} | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}] | {"name": "Bayer", "country": "GER"} | 1             | 5          |
    Then the "FORBIDDEN" error should be returned
    And request id should be returned
    And I should not receive requested item

  Scenario: Create with incorrect client
    Given my scope is "medication:write"
    And my client type is "MSP"
    And my consumer ID is "089c0204-a191-4537-ab92-56dca268443c"
    When I create medication with attributes:
      | name      | atcCodes               | certificate | certificateExpiredAt | container                                                                                         | dailyDosage | form                           | ingredients                                                                                                                                                                                    | manufacturer                        | packageMinQty | packageQty |
      | "Ниферон" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 50} | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}] | {"name": "Bayer", "country": "GER"} | 1             | 5          |
    Then the "FORBIDDEN" error should be returned
    And request id should be returned
    And I should not receive requested item

  Scenario Outline: Create with invalid params
    Given my scope is "medication:write"
    And my client type is "NHS"
    And my consumer ID is "94e4301f-2d28-4403-b59f-b5865e9ca26f"
    When I create medication with attributes:
      | name   | atcCodes   | certificate   | certificateExpiredAt   | container   | dailyDosage   | form   | ingredients   | manufacturer   | packageMinQty   | packageQty   |
      | <name> | <atcCodes> | <certificate> | <certificateExpiredAt> | <container> | <dailyDosage> | <form> | <ingredients> | <manufacturer> | <packageMinQty> | <packageQty> |
    Then the "UNPROCESSABLE_ENTITY" error should be returned
    And request id should be returned
    And I should not receive requested item

    Examples:
      | name      | innmDosageId                           | atcCodes               | certificate | certificateExpiredAt | container                                                                                          | dailyDosage | form                           | ingredients                                                                                                                                                                                    | manufacturer                        | packageMinQty | packageQty |
      | "Ниферон" | "01c9b8ae-fe41-4390-8f3c-4744f5b13717" | ["INVALID"]            | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 50}  | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}] | {"name": "Bayer", "country": "GER"} | 1             | 5          |
      | "Ниферон" | "01c9b8ae-fe41-4390-8f3c-4744f5b13717" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 50}  | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}] | {"name": "Bayer", "country": "GER"} | 1             | 5          |
      | "Ниферон" | "01c9b8ae-fe41-4390-8f3c-4744f5b13717" | ["C08CA01", "C08CA02"] | "100-fA-11" | "2019-12-12"         | {"numerator_unit": "ML", "numerator_value": 1, "denumerator_unit": "MKG", "denumerator_value": 50} | 0.02        | "AEROSOL_FOR_INHALATION_DOSED" | [{"innmDosageId": "01c9b8ae-fe41-4390-8f3c-4744f5b13717", "dosage": {"numerator_unit": "DOSE", "numerator_value": 1, "denumerator_unit": "ML", "denumerator_value": 100}, "is_primary": true}] | {"name": "Bayer", "country": "GER"} | 1             | 5          |

Processing

Info
Saving innm dosage and medication occurs in one table - prm.medications. They are separated by the parameter type - innm_dosage and brand. Therefore, some fields may not be filled in when creating an innm dosage or medication. For example, max_daily_dosage is filled for innm dosage, but not filled for medication, etc.

Create new record in Medications
Fill data

Destination	Source
id
name	$.name
TYPE	MEDICATION
is_active	TRUE
form	$.form
ingredients	$.ingredients
container	$.container
package_qty	$.package_qty
package_min_qty	$.package_min_qty
code_atc	$.code_atc
manufacturer	$.manufacturer
certificate	$.certificate
expired_certificate_at	$.expired_certificate_at
inserted_at	:timestamp
inserted_by	user_id
updated_at	:timestamp
updated_by	user_id
daily_dosage	number

Create new Ingredients

Create new record in Ingredients from $.ingredients
Fill data

Destination	Source
id
dosage	$.ingredients.dosage
parent_id	medication_id
innm_child_id	NULL
medication_child_id	$.ingredients.innm_dosage_id
is_primary	$.ingredients.is_primary
inserted_at	:timestamp
inserted_by	user_id
updated_at	:timestamp
updated_by	user_id

Response structure

See on Apiary

Example:

Expand

title	Response example

Code Block

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "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"
  }
}

Expand

title	Response example

Code Block

{
  "meta": {
    "code": "422",
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "error": {
    "type": "unverified",
    "message": "Denumerator unit from Dosage ingredients must be is equal Numerator unit from Container medication!"
  }
}

HTTP status codes

Page Properties

HTTP status code	Message	What caused the error
201
422

Versions Compared

Old Version 5

New Version Current

Key

APIary

Input parameters (filters)

Authorize

Validate request (JSON schema)

Validate Innm

Validate Dosage & Container dosage

Purpose

Specification

Logic

Request structure

Authorize

Headers

Request data validation

Validate FK

Validate status & type ingredients

Validate status ingredients.is_primary

Validate Equal Dosage & Container

Validate multiplicity

Validate atc code

Validate request

Processing

Create new Ingredients

Response structure

HTTP status codes

Page Comparison

Versions Compared

Old Version 5

New Version Current

Key

APIary

Input parameters (filters)

Authorize

Validate request (JSON schema)

Validate Innm

Validate Dosage & Container dosage

Purpose

Specification

Logic

Request structure

Authorize

Headers

Request data validation

Validate FK

Validate status & type ingredients

Validate status ingredients.is_primary

Validate Equal Dosage & Container

Validate multiplicity

Validate atc code

Validate request

Processing

Create new Ingredients

Response structure

HTTP status codes