ЕСОЗ - публічна документація

Human readable requisition number

Owned by Olena Yermolenko
Last updated: Jul 07, 2023 by Serhii Boldin (SoE eHealth)
2 min read

Overview

Requisition number - A shared identifier common to all service requests that were authorized more or less simultaneously by a single author, representing the composite or group identifier. All services requests that were created as a part of a single encounter will have the same requisition number.

Requirements

  1. Must be the same for all entities (service requests) related to the single encounter

  2. Must be unique among all encounters

  3. Not a sequence - so no-one can generate new Requisition based on knowledge of the existing one

  4. Must be easy to read and pass a number to other person via any channel: orally, phone, sms

  5. Must contain only numbers and some letters that looks the same in Cyrillic and Latin alphabet and can be entered via the phone keypad: A, B, C, E, H, I, K, M, O, P, T, X

Solution

Requisition number has the following structure

0123-4567-89AB-CEIK - 4 blocks that contains 4 characters with total length 16 characters

Implement a hashing function with episode of care encounter ID and salt as an argument

  1. Salt is empty by default

  2. Get a digest (hex) of hashing on episode encounter ID (it is proposed to use 8 bytes digest size)

  3. Convert digest into required character set

  4. Format result

This example shows how to get requisition 

from hashlib import blake2b key = b'random' digs = '0123456789ABCEHIKMOPTX' def format_string(x, n=4): x = x.zfill(16) return '-'.join([x[i:i+n] for i in range(0, len(x), n)]) def int2base(x, base=len(digs)): if x < 0: sign = -1 elif x == 0: return digs[0] else: sign = 1 x *= sign digits = [] while x: digits.append(digs[int(x % base)]) x = int(x / base) if sign < 0: digits.append('-') digits.reverse() return ''.join(digits) def hex2base(x, base=len(digs)): return int2base(int(x, 16)) def get_requisition(message): h = blake2b(key=key, digest_size=8) h.update(bytes(message, 'utf-8')) return format_string(hex2base(h.hexdigest()))

Output:

01EM-TC40-CAXX-E2HE 00EB-EB34-BMX7-9COA 00HE-KKM9-BT16-0T8T 0223-T16C-PKX1-P6TA 01KO-2O85-K2T7-C8HP 01I8-K828-8440-0T8E 02I0-8BCM-H383-T825 02CX-K1AM-8E84-9TTO 01BM-78KH-TTMP-MHK2 00C1-T2A2-X8AK-XBKA 02X1-A744-IOOE-ET2B 007C-H1C4-BEAP-3C45 02M9-9XT7-KA79-5600 0112-B2M1-H58H-66A2 011E-MX7H-M027-X60A 01B4-HC53-062X-P2KM 00E8-3C96-T18A-2P6O

The proposed solution means that after new requisition number was generated we should check that it is unique in the DB.

If it is not unique - generate salt and and generate new requisition number with episode of care ID + salt

Repeat this until we get unique requisition number. Save salt to DB in order to generate the same requisition number for the same episode of care encounter.

Data model

Proposed storage structure

Attribute

Type

Nullable

Description

Attribute

Type

Nullable

Description

entity_id

uuid

N



requisition

string

N



entity_type

string

N

Enum:

  • episode of care encounter

Open questions

  1. Read existing requisition from DB or generate anyway based on episode and salt

ЕСОЗ - публічна документація