devsofttech_hms_ci4/docs/CSNOTK_API_REFERENCE.md

CSNOtk v9.0 API Reference & Integration Guide

Status: Finalized from Java source code analysis (v9.0 from C-DAC)
Date: May 12, 2026
Context: CSNOtk SearchController, CompositeDescription DTO analysis

---

1. REST API Endpoints

Base URL Format

http://localhost:8080/csnoserv/rest/

Main Search Endpoints

/search/suggest - Suggest/Search Terms

• Method: GET
• Primary endpoint for diagnosis search
• Returns: Array of CompositeDescription objects

Query Parameters:

GET /search/suggest?term=headache&state=active&semantictag=all&acceptability=all&returnlimit=20

Parameter	Type	Default	Description
term	string	REQUIRED	Search text/query
state	string	both	active / inactive / both
semantictag	string	all	all / disorder / finding / procedure / etc. (combined with ++)
acceptability	string	all	preferred / preferredexcludingfsn / synonyms / acceptable / all
returnlimit	int	-1	Max results. -1 = all, e.g., 20, 50
refsetid	string	null	Optional refset filter
parentid	string	null	Optional parent concept ID (may conflict with refsetid)
excludeparentconcept	boolean	false	If true, excludes descriptions from parent ID
callback	string	null	JSONP callback for cross-domain requests

Response Status Codes:

• 200 OK – Success, returns JSON array
• 400 Bad Request – Invalid parameter (e.g., invalid semantic tag, state, acceptability)
• 500 Internal Server Error – Server error, check logs

---

/lookup - Lookup by Concept ID

• Method: GET
• Returns: CompositeDescription for a specific concept

Example:

GET /search/lookup?conceptid=25064002&semantictag=all&acceptability=all

---

/validate/id - Validate Concept ID

• Method: GET
• Returns: Boolean or status indicating if concept exists

Example:

GET /search/validate/id?id=25064002

Response:

{
  "valueBoolean": true
}

or

{
  "valid": true
}

---

/map - SNOMED CT to ICD-10 Mapping

• Method: GET
• Optional: Only if ICD-10 map refset is configured

---

2. Response Object: CompositeDescription

JSON Structure Example

[
  {
    "id": "900000000003001",
    "conceptId": "25064002",
    "term": "Headache",
    "typeId": "900000000000003001",
    "activeStatus": 1,
    "languageCode": "en",
    "caseSignificanceId": "900000000000017005",
    "hierarchy": "disorder",
    "isPreferredTerm": "true",
    "conceptState": "active",
    "conceptFsn": "Headache (disorder)",
    "definitionStatus": "FULLY_DEFINED",
    "moduleId": "900000000000207008",
    "effectiveTime": "2020-01-31",
    "refSetLangMember": {
      "id": "...",
      "refsetId": "..."
    }
  }
]

Field Definitions

Field	Type	Description
id	string	Description ID (SNOMED CT identifier)
conceptId	string	Concept ID (primary SNOMED code)
term	string	Description text/term
typeId	string	Description type ID (FSN or Synonym)
activeStatus	int	1 = active, 0 = inactive
languageCode	string	Language code (e.g., en)
caseSignificanceId	string	Case significance ID
hierarchy	string	Semantic tag (e.g., disorder, finding, procedure)
isPreferredTerm	string	"true" or "false" – Preferred terminology flag
conceptState	string	active or inactive
conceptFsn	string	Fully Specified Name (e.g., "Headache (disorder)") – Use for display
definitionStatus	string	FULLY_DEFINED or PRIMITIVE
moduleId	string	Module identifier
effectiveTime	string	Date of last update (YYYY-MM-DD)
refSetLangMember	object	Language/region refset (e.g., US vs UK)

Key Fields for HMS Integration:

1. conceptId – Store in snomed_concept table (primary key for diagnosis)
2. term – Display in OPD prescription autocomplete
3. conceptFsn – Use for full display (includes hierarchy, e.g., "Headache (disorder)")
4. hierarchy – Semantic tag for filtering/categorization
5. isPreferredTerm – Sort preferred terms first in UI
6. activeStatus – Skip inactive concepts (status check)

---

3. PHP Integration: CsnotkTerminologyService

Configuration (.env)

snomed.csnotk.enabled=true
snomed.csnotk.baseUrl=http://localhost:8080/csnoserv
snomed.csnotk.timeoutSec=10

Usage in OPD_Prescription Controller

use App\Libraries\CsnotkTerminologyService;

// In provisional_diagnosis_search() method:
$service = new CsnotkTerminologyService();

if ($service->isEnabled()) {
    $csnotkResults = $service->searchDiagnosis($query, 20);
    // Returns: [ ['concept_id' => '25064002', 'term' => 'Headache', ...], ... ]
}

Expected Service Response Format

[
    [
        'concept_id' => '25064002',
        'term' => 'Headache',
        'hierarchy' => 'disorder',
        'is_preferred' => 1,
        'source' => 'csnotk'
    ],
    ...
]

---

4. Testing & Validation

Live Service Test URL

http://localhost:8080/csnoserv/

(Configure SNOMED CT files via web UI on initial setup)

Test Search Query (via curl)

curl -X GET "http://localhost:8080/csnoserv/rest/search/suggest?term=headache&state=active&semantictag=all&acceptability=all&returnlimit=20"

Expected Response

[
  {
    "id": "900000000003001",
    "conceptId": "25064002",
    "term": "Headache",
    "hierarchy": "disorder",
    "isPreferredTerm": "true",
    "conceptFsn": "Headache (disorder)",
    "activeStatus": 1
  }
]

---

5. Deployment Checklist

• Deploy csnoserv.war to Tomcat webapps folder
• Configure JVM memory: -Xms50% -Xmx80% of available RAM
• Start Tomcat
• Access http://localhost:8080/csnoserv/
• Provide SNOMED CT RF2 snapshot folder path on configuration page
• Wait for indexing (may take 5-30 min depending on file size)
• Test /rest/search/suggest?term=test&returnlimit=5
• Update HMS .env with CSNOServ base URL
• Test OPD diagnosis autocomplete

---

6. Semantic Tags Reference

Common SNOMED CT semantic tags:

• disorder – Diseases and conditions
• finding – Clinical findings
• procedure – Procedures
• event – Clinical events
• organism – Biological organisms
• substance – Chemical substances
• physical object – Physical items
• specimen – Specimen types
• body structure – Anatomical structures

Use in query: /search/suggest?semantictag=disorder++finding (combined with ++)

---

7. Error Handling

Scenario	HTTP Status	Response
Invalid term parameter	400	Bad request
Invalid semantic tag	400	Bad request with error message
Database not initialized	500	Server error (check CSNOServ logs)
Timeout (no response)	timeout	(Network error)

Fallback Strategy:
If CSNOtk is unavailable or timeout, OPD_Prescription controller falls back to local SNOMED database query (snomed_description table).

---

8. Version Information

• CSNOtk Suite Version: 9.0
• REST API Version: Compatible with CSNOServ.war v9.0
• Java Version Required: OpenJRE 11 or later
• Tomcat Version Tested: 10.0, 10.1
• SNOMED CT RF2 Release: International Release or National Extensions supported

---

9. Additional Resources

• CSNOServ README: d:\Workplace\HMS_CI4_OLD\CDAC\CSNOServ_v9.0\README.md
• CSNOLib Documentation: d:\Workplace\HMS_CI4_OLD\CDAC\CSNOLib_v9.0\README.md
• Java Source Code: [d:\Workplace\HMS_CI4_OLD\CDAC\CSNOtk-Source-Code-v9.0](../CDAC/CSNOtk-Source-Code-v9.0/)
• C-DAC Official: https://cdac.in/