Department Entity Service v2.0
and Overview
The Department Entity service manages the department and its hierarchies metadata. It deals with department entity and department hierarchy only.
Department Hierarchy store only hierarchies definition like metadata for department level and department entity stores actual department data with its ancestry information.
Version History
Current Version: 2.0.0
Prerequisites
Before you proceed with the configuration, make sure the following pre-requisites are met.
Java 8
MongoDB instance
Required Service Dependencies - Adapter-Master-Data-Service
Features
Department Hierarchy
It defines the hierarchy definition for the department.
department id: It is the ID of the department from the department master
level: It defines the depth of hierarchy of department-level
parent: It provides details about department hierarchy parent (UUID)
Level value evaluation
Root level department hierarchy will not contain any parent value and the level value will be zero
When parent id is having any value then we search parent in department hierarchy record for hierarchy level evaluation
Get level value from parent department hierarchy and increment current department hierarchy level value by one
Department Entity
It contains department entity information along with its hierarchy level and also attaches master department information (department id - UUID). It keeps all child level information lists at every department node (department record). The leaf level department does not have any children’s info.
ChiThe child list contains the department entity ID list, which makes the current department entity parent of all children list (department ID list). This is how it maintains the department entity level.
Hierarchy Level approach
Define the hierarchy level using the top to bottom because it has the parent's references. For department entity, create using the bottom-to-top approach. The leaf department entity does not have any child reference. When the department entity goes higher (parent) only then does it defines child reference in its child list.
Department Hierarchy Request action
Create Department Hierarchy:
We pass the current hierarchy level and its parent details along with master department and tenant information. It stores data as meta-information about hierarchy level for department entity data processing, it will be working as a reference meta index which will tell about hierarchy level information.Search Department Hierarchy:
It just provides a preview of department hierarchies by providing request parameters - tenant Id, hierarchy level or department hierarchy id.
API List
Title | Link |
| |
|
Department Entity Request action
Create Department Entity:
It passes tenant Id, master department id, hierarchy level, and its cand children list with department entity name and code. Tenant, hierarchy level and the master department are root info about the department entity. If the department entity does not contain any child, that means it is a leaf department entity it can only seek for its parent.Search Department Entity:
It can make search requests based on any department entity attribute but can't skip tenant information, it returns the whole department entity details along with its child information. It finds all ancestry information of the current department entity.Update Department Entity:
Update the existing department entity by searching based on department entity id and tenant id.
Mandatory Fields to update department entity "id" and "tenant id".
We can update any attribute in the department entity except “id” itself.
updatable attribute list: tenantId, departmentId, code, name, hierarchy level and children.It does a few validations before updating the department entity.
departmentId and children can not be updated without a hierarchy level.
hierarchy level value should be valid for departmentId and children. If the value got mismatched then it will throw an appropriate error message.
It checks in the system before doing an update, that department entity id is available or not. If exist then it'll update else throw a meaningful error message.
API List
Title | Link |
| |
| |
|
Interaction Diagram
Environment
There will not be any environment variables required specific to the environment (migration).
Configurations and Setup
Update all the DB and URI configuration in the dev.yaml, qa.yaml, prod.yaml file.
References and Notes
Department Hierarchy API With Example
Department Hierarchy defines the definition(Meta- Data) for actual department entity creation.
In the above image, the first row contains the definition of the data that is there in the second row. Ideally, we are considering the first row as Meta-Data of subsequent row data.
Department Hierarchy Create API - creates the hierarchy based on the Meta-Data. The creation of the Department Hierarchy follows a Top to Bottom approach.
The top or first label will be named as “Department”, with no parent (parent as null) in the create department hierarchy API. Once the hierarchy is created, in API response will get a unique id and level as 0.
For the next subsequent create hierarchy API request, will pass the label as “Zone", with a parent as the previous request unique id. This request will also return the response with a new unique id and with level as 1(you can refer to the hierarchy level evaluation section).
Similarly, for the next hierarchy, create will pass labels as “Circle”, “Division”,... and corresponding previous unique id as a parent.
For this example , we will stop the hierarchy creation till labeled as “GPWSC”.
For reference, the Top label (named as “Department”) request & response will look like :
Request :
{
"requestHeader": {
"ts": 1627193067,
"version": "0.1.0",
"msgId": "ek9d96e8-3b6b-4e36-9503-0f14a01af74n",
"userInfo": {
"uuid": "e4fd96e8-3b6b-4e36-9503-0f14a01af39d"
}
},
"departmentHierarchyLevel": {
"tenantId": "pb",
"departmentId": "3d9ef18a-361a-40cf-b142-dd6f998e1ad2",
"label": "Department",
"parent":null
}
}
Response :
{
"responseHeader": {
"ts": 1627193067,
"correlationId": "78b734f5-640e-40f6-8df0-97e32a94a14d",
"msgId": "ek9d96e8-3b6b-4e36-9503-0f14a01af74n",
"status": "successful",
"signature": "",
"version": "0.1.0"
},
"departmentHierarchyLevel": [
{
"id": "67865682-54af-467c-8fb5-326c2cac8f61",
"tenantId": "pb",
"departmentId": "3d9ef18a-361a-40cf-b142-dd6f998e1ad2",
"label": "Department",
"parent": null,
"level": 0,
"auditDetails": {
"createdBy": "ba28ebe8-ed9c-4cdb-9328-b8e227eb0342",
"lastModifiedBy": "ba28ebe8-ed9c-4cdb-9328-b8e227eb0342",
"createdTime": 1638804889251,
"lastModifiedTime": 1638804889251
}
}
]
}
For label “Zone”
Request :
{
"requestHeader": {
"ts": 1627193067,
"version": "0.1.0",
"msgId": "ek9d96e8-3b6b-4e36-9503-0f14a01af74n",
"userInfo": {
"uuid": "e4fd96e8-3b6b-4e36-9503-0f14a01af39d"
}
},
"departmentHierarchyLevel": {
"tenantId": "pb",
"departmentId": "3d9ef18a-361a-40cf-b142-dd6f998e1ad2",
"label": "Zone",
"parent":"67865682-54af-467c-8fb5-326c2cac8f61"
}
}
Response :
And so on ...
Note : Below are the observations from above example :
Tenant Id and Department Id will be from Ifix Master Data Service and Adapter Master Data Service respectively. That we need to create before creating the Department Hierarchy.
In Request, tenant Id and Department Id will be the same for one hierarchy (from “Department” to “GPWSC”).
After successful creation of the Department hierarchy from “Department” to “GPWSC”, There will be a total of 7 hierarchy levels from 0 to 6 “for this particular department”. Other new departments will have to define their own hierarchy.
Department Entity API With Example
Department Entity creates the entity based on defined definition in Department Hierarchy.
In the above image, the second row contains the actual Department Entities. Department Entity Create API - follows Bottom to Up approach.
In the above example data, the very first Department Entity will be created for “BARUWAL” with code “7278”. Below are the Steps to create Department Entity :
The first Department Entity will be created for “BARUWAL” (Since, the Department Hierarchy has been defined from “Department” to “GPWSC”. Please refer Department-Hierarchy-API-With-Example.)
The details that need to be passed in Department Entity Create API is -
→ tenantId : This will be from Ifix Master Data Service.
→ departmentId : This will be from Adapter Master Data Service.
→ code: For the first Department Entity, as per above data image, it is “7278”.
→ name : For the first Department Entity, as per above data image, it is “BARUWAL”.
→ hierarchyLevel : For the first Department Entity, as per above data image and defined Department Hierarchy, It will be “6”.(Bottom to Up)
→ children : For the first Department Entity, as per above data image, it will be an empty set.
3. For next Department Entity Creation - repeat the step 2 by making sure for subsequent request has - next Department Entity - Code, name, hierarchyLevel (this will decrement by one for every next Department entity), children (this will contain all or at least one previously created Department Entity Id(s) ).
For reference, the Bottom to Up request & response of Department Entity Create API will look like :
Request :[For Department Entity at Bottom - “BARUWAL”]
Response :
Subsequent Request : [For Department Entity - “Kiratpur Sahib”]
Response :
And so on for the next Department Entity(ies) ...
Note : Below are the observation from above example :
Tenant Id and Department Id will be created before creating the Department Entity hence before Department Hierarchy Create. Tenant Id and Department Id will be the same in all hierarchy levels for a Single Department Hierarchy and corresponding Department Entity(ies).
In the children attribute , we can pass a set of previous Department Entity Ids (or at least one or empty in case of Bottom level Department Entity).
Update Existing Children List
When we have to update the existing children list of Department Entity then update the existing children list using mongodb command like below
Find the parent department entity where the new children need to be added. We should know which is the parent Department Entity beforehand. For the same, Do search by name and hierarchy level and find the corresponding parent department entity’s id (UUID).
Append the department entity id at the end of the parent department entity children's list that we got from step 1. And count the length of the parent department entity children’s list (it is 0 based indexing ) that we are calling as ‘n’ here (it could be any integer number as per the children’s list size ) and then set it as
"children.n": "<picked_from_step_1_query_department_entity_id>"
e.g. :