The Admin Service is a Node.js-based API designed for administrative tasks, with a particular focus on report and condition management. It utilizes the Fastify framework to deliver a high-performance and low-overhead API interface. This document offers an in-depth examination of the API, covering setup requirements, a comprehensive overview of the application, and detailed route documentation.
Before you start using the Admin API, ensure that you have the following items:
-
Node.js: Version 20.x or higher.
- Download from Node.js Official Website.
- Verify installation using
node -v
andnpm -v
.
-
NPM: A package manager for Node.js packages.
- NPM is installed with Node.js.
-
Git: Version control system for cloning the repository.
- Download from Git Official Website.
-
Database: Arango database setup.
- Ensure the database is running and accessible from your Node.js environment.
-
Environment Variables: Set up environment variables required by the application, such as database connection strings. Typically stored in a
.env
file.
-
Clone the Repository:
git clone https://github.com/@frmscoe/admin-service.git cd admin-service
-
Install Dependencies:
npm install
-
Configure Environment Variables:
- Create a
.env
file in the root directory and add necessary configuration values
- Create a
-
Run the Server:
npm start
-
Access the API:
- The server runs on
http://localhost:3000
by default. You can access the API via your browser or any HTTP client like Postman.
- The server runs on
This endpoint retrieves a report by the specified message ID (msgid
). The message ID is provided as a query parameter.
sequenceDiagram
participant Client as Client<br>System
participant ADMIN as Admin-Service
participant DB as ArangoDB
Client ->> ADMIN: 1. Fetch evaluationResult
ADMIN->> DB: 2. Fetch evaluationResult
DB->> ADMIN: 3. {evaluationResult} data
ADMIN->> Client: 4. {evaluationResult} data
/v1/admin/reports/getreportbymsgid
GET
Parameter | Type | Required | Description |
---|---|---|---|
msgid |
String | Yes | The message ID to get the report for. |
No specific headers required apart from standard authentication headers if needed.
GET /v1/admin/reports/getreportbymsgid?msgid=1234567890 HTTP/1.1
-
Status 400 Bad Request: When
msgid
is missing or invalid.{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "querystring must have required property 'msgid'" }
-
Status 204 Not Found: When no report is found for the given
msgid
.{ "statusCode": 204, }
-
Status 500 Internal Server Error: For server-side errors.
{ "status": "error", "message": "Internal server error occurred." }
Both endpoints are responsible for storing conditions related to their specific accounts or entities. They are expected to store condition edges within the in-memory system and have different methods assigned to each endpoint: GET, POST, and PUT.
GET endpoints are used to retrieve data already stored by a POST request. You can use the SyncCache parameter to either sync active conditions or not. PUT endpoints are responsible for updating the expiry date of a specified condition.
sequenceDiagram
participant clientsystem as Client System
participant tmsapi as Admin API
participant cache as Cache
participant db as Database
clientsystem->>tmsapi: setCondition()
tmsapi->>db: setCondition()
db->>tmsapi: writeOK(recordId)
tmsapi->>cache: setCondition()
cache->>tmsapi: writeOK()
tmsapi->>clientsystem: writeOK(recordId)
/v1/admin/event-flow-control/entity
POST, GET, PUT
/v1/admin/event-flow-control/account
POST, GET, PUT
Some endpoints share properties except for ntty and acct. These properties are specific to each endpoint and indicate the governing condition
Parameter | Type | Required | Description |
---|---|---|---|
evtTp |
Array | Yes | Event types |
condTp |
String | Yes | Condition type. |
prsptv |
String | Yes | Perspective of the condition. |
incptnDtTm |
String | Yes | Inception date. |
xprtnDtTm |
String | Yes | Expiration date. |
condRsn |
String | Yes | Reason code. |
forceCret |
Boolean | Yes | Flag indicating whether the entity should be created if it does not exist. |
usr |
String | Yes | User that triggered the operation. |
Parameter | Type | Required | Description |
---|---|---|---|
ntty |
Object | Yes | The entity object that the condition is governed by. |
Parameter | Type | Required | Description |
---|---|---|---|
acct |
Object | Yes | The account object that the condition is governed by. |
Parameter | Type | Required | Description |
---|---|---|---|
id |
String | Yes | Entity identifier |
schmenm |
String | Yes | Scheme name of the entity |
synccache |
String | No | Accepts all , active , default or no |
Parameter | Type | Required | Description |
---|---|---|---|
id |
String | Yes | Entity ID. |
schmenm |
String | Yes | Scheme name of the account |
agt |
String | Yes | proprietary agent identifier |
synccache |
String | No | Accepts all , active , default or no |
Parameter | Type | Required | Description |
---|---|---|---|
id |
String | Yes | Entity identifier |
schmenm |
String | Yes | Scheme name of the entity |
condId |
String | Yes | Condition identifier |
Body | Type | Required | Description |
---|---|---|---|
xprtnDtTm |
String | No | New timedate of the condition |
Parameter | Type | Required | Description |
---|---|---|---|
id |
String | Yes | Entity ID. |
schmenm |
String | Yes | Scheme name of the account |
agt |
String | Yes | proprietary agent identifier |
condId |
String | Yes | Condition identifier |
Body | Type | Required | Description |
---|---|---|---|
xprtnDtTm |
String | No | New timedate of the condition |
Important
Ensure your query parameters are encoded as some properties can contain special characters. An id
of +12344567890
would need to be encoded as +
is a special character.
Possible values for some fields mention in the table above
- evtTp : [
'pacs.008.001.10'
,'pacs.002.001.12'
,'pain.001.001.11'
,'pain.013.001.09'
or'all'
] - condTp :
non-overridable-block
oroverride
oroverridable-block
- prsptv :
both
orcreditor
ordebtor
ntty object for : URL 1
{
"id": "string",
"schmeNm": {
"prtry": "string"
}
}
acct object for : URL 2
{
"id": "string",
"schmeNm": {
"prtry": "string"
},
"agt": {
"finInstnId": {
"clrSysMmbId": {
"mmbId": "string"
}
}
}
}
No specific headers required for both endpoints.
POST /v1/admin/event-flow-control/entity HTTP/1.1
-
Status 400 Bad Request: When
prsptv
is missing or invalid.{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "body must have required property 'prsptv'" }
-
Status 500 Not Found: When account was not found in the database and forceCret was set to false
{ "statusCode": 500, "message": "Error: account was not found and we could not create one because forceCret is set to false" }
-
Status 500 Internal Server Error: For server-side errors.
{ "status": "error", "message": "Internal server error occurred." }
POST /v1/admin/event-flow-control/account HTTP/1.1
-
Status 400 Bad Request: When
condTp
is missing or invalid.{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "body must have required property 'condTp'" }
-
Status 500 Not Found: When expiration date is before inception date.
{ "statusCode": 500, "message": "Error: Expiration date must be after inception date." }
-
Status 500 Internal Server Error: For server-side errors.
{ "status": "error", "message": "Internal server error occurred." }
PUT /v1/admin/event-flow-control/cache HTTP/1.1
- Status 204 No Content: Cache has been updated