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: 12.0.0
Prerequisites
Before you proceed with the configuration, make sure the following pre-requisites are met.
Java 8
MongoDB instance
Required Service Dependencies - iFIXAdapter-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). Leaf The leaf level department does not have any children children’s info.
Child 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 parameter parameters - tenant Id, hierarchy level or department hierarchy id.
API List
Title | Link |
| https://www.getpostman.com/collections/b330dc3698bf009d2ef59891831cac4dad92a650 |
| https://www.getpostman.com/collections/b330dc3698bf009d2ef59891831cac4dad92a650 |
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 is 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.
API List
...
Title
...
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 |
| |
| https://www.getpostman.com/collections/b330dc3698bf009d2ef59891831cac4dad92a650 |
| https://www.getpostman.com/collections/b330dc3698bf009d2ef59891831cac4dad92a650 |
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.Make sure the Keycloak server is up and running And have been configured with the required client ID.
References and Notes
Title | Link |
|---|---|
Swagger Yaml | |
Postman collection | https://www.getpostman.com/collections/b330dc3698bf009d2ef59891831cac4dad92a650 |
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 about 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. Creation The creation of the Department Hierarchy follows a Top to Bottom approach.
Top The top or first label will be named as “Department”, with no parent (parent as null) in the create department hierarchy apiAPI. Once the hierarchy is created, in api API response will get a unique id and level as 0.
For the next subsequent create hierarchy api 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 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”.
...
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.
...
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 -
...
→ departmentId : This will be from Ifix Adapter Master Data Service.
→ code: For the first Department Entity, as per above data image, it is “7278”.
...
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
...