Overview
Indexer service runs as a separate service, This service is designed to perform all the indexing tasks of the digit platform. The service reads records posted on specific kafka topics and picks the corresponding index configuration from the yaml file provided by the respective module.Objective of Indexer service are listed as below.
To provide a one stop framework for indexing the data to elasticsearch.
To create provision for indexing live data, reindexing from one index to the other and indexing legacy data from the datastore.
Pre-requisites
Before you proceed with the configuration, make sure the following pre-requisites are met -
Prior Knowledge of Java/J2EE.
Prior Knowledge of SpringBoot.
Prior Knowledge of Elasticsearch.
Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.
Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.
Key Functionalities
Performs three major tasks namely: LiveIndex, Reindex and LegacyIndex.
LiveIndex: Task of indexing the live transaction data on the platform. This keeps the es data in sync with the db.
Reindex: Task of indexing data from one index to the other. ES already provides this feature, indexer does the same but with data transformation.
LegacyIndex: Task of indexing legacy data from the tables to ES.
Provides flexibility to index the entire object, a part of the object or an entirely different custom object all using one input json from modules.
Provides features for customizing index json by field mapping, field masking, data enrichment through external APIs and data denormalization using MDMS.
One stop shop for all the es index requirements with easy-to-write and easy-to-maintain configuration files.
Designed as a consumer to save API overhead. The consumer configs are written from scratch to have complete control over the consumer behaviour.
Deployment Details
Step 1: Write configuration as per your requirement. Structure of the config file is explained later in the same doc.
Step 2: Check-in the config file to a remote location preferably github, currently we check the files into this folder https://github.com/egovernments/configs/tree/DEV/egov-indexer -for dev
Step 3: Provide the absolute path of the checked-in file to DevOps, to add it to the file-read path of egov-indexer. The file will be added to egov-indexer's environment manifest file for it to be read at start-up of the application.
Step 4: Run the egov-indexer app, Since it is a consumer, it starts listening to the configured topics and indexes the data.
Interaction Diagram:
...
Configuration Details
As mentioned above, indexer uses a config file per module to store all the configurations pertaining to that module. Indexer reads multiple such files at start-up to support indexing for all the configured modules. The file contains following keys:
a. serviceName: uses a config file per module to store all the configurations pertaining to that module. Indexer reads multiple such files at start-up to support indexing for all the configured modules. In config we define source and, destination elastic search index name, custom mappings for data transformation and mappings for data enrichment. Below in the sample configuration for indexing TL application creation data into elastic search.
| Code Block |
|---|
ServiceMaps:
serviceName: Trade License
version: 1.0.0
mappings:
- topic: save-tl-tradelicense
configKey: INDEX
indexes:
- name: tlindex-v1
type: licenses
id: $.id, $.tenantId
isBulk: true
timeStampField: $.auditDetails.createdTime
jsonPath: $.Licenses
customJsonMapping:
indexMapping: {"Data":{"tradelicense":{},"ward":{},"tenantData":{}, "history":{}}}
fieldMapping:
- inJsonPath: $
outJsonPath: $.Data.tradelicense
externalUriMapping:
- path: http://egov-location.egov:8080/egov-location/location/v11/boundarys/_search
queryParam: hierarchyTypeCode=REVENUE,boundaryType=locality,codes=$.tradeLicenseDetail.address.locality.code,tenantId=$.tenantId
apiRequest: {"RequestInfo":{"apiId":"org.egov.pt","ver":"1.0","ts":1502890899493,"action":"asd","did":"4354648646","key":"xyz","msgId":"654654","requesterId":"61","authToken":"d9994555-7656-4a67-ab3a-a952a0d4dfc8","userInfo":{"id":1,"uuid":"1fec8102-0e02-4d0a-b283-cd80d5dab067","type":"EMPLOYEE","tenantId":"pb.amritsar","roles":[{"name":"Employee","code":"EMPLOYEE","tenantId":"pb.amritsar"}]}}}
uriResponseMapping:
- inJsonPath: $.TenantBoundary[0].boundary[0]
outJsonPath: $.Data.ward
- path: http://egov-workflow-v2.egov:8080/egov-workflow-v2/egov-wf/process/_search
queryParam: businessIds=$.applicationNumber,history=true,tenantId=$.tenantId
apiRequest: {"RequestInfo":{"apiId":"org.egov.pt","ver":"1.0","ts":1502890899493,"action":"asd","did":"4354648646","key":"xyz","msgId":"654654","requesterId":"61","authToken":"d9994555-7656-4a67-ab3a-a952a0d4dfc8","userInfo":{"id":1,"uuid":"1fec8102-0e02-4d0a-b283-cd80d5dab067","type":"EMPLOYEE","tenantId":"pb.amritsar","roles":[{"name":"Employee","code":"EMPLOYEE","tenantId":"pb.amritsar"}]}}}
uriResponseMapping:
- inJsonPath: $.ProcessInstances
outJsonPath: $.Data.history
mdmsMapping:
- path: http://egov-mdms-service.egov:8080/egov-mdms-service/v1/_search
moduleName: tenant
masterName: tenants
tenantId: pb
filter: "[?(@.code == $tenant)]"
filterMapping:
- variable: $tenant
valueJsonpath: $.tenantId
uriResponseMapping:
- inJsonPath: $.MdmsRes.tenant.tenants
outJsonPath: $.Data.tenantData |
The configuration file contains following keys:-
Variable Name | Description |
|---|---|
serviceName | Name of the module to which this configuration belongs. |
...
summary |
...
Summary of the module. |
...
version |
...
Version of the configuration. |
...
mappings |
...
List of definitions within the module. Every definition corresponds to one index requirement. Which means, every object received onto the kafka queue can be used to create multiple indexes, each of these indexes will need configuration, all such configurations belonging to one topic forms one entry in the mappings list. The keys listed henceforth together form one definition and multiple such definitions are part of this mappings key. |
...
topic |
...
Topic on which the data is to be received to activate this particular configuration. |
...
configKey |
...
Key to identify to what type of job is this config for. values: INDEX, REINDEX, LEGACYINDEX. INDEX: LiveIndex, REINDEX: Reindex, LEGACYINDEX: LegacyIndex. |
...
indexes |
...
Key to configure multiple index configurations for the data received on the particular topic. Multiple indexes based on different requirement can be created using the same object |
...
. |
...
name |
...
Index name on the elasticsearch. (Index will be created if it doesn't exist with this name.) | |
type |
...
Document type within that index to which the index json has to go. (Elasticsearch uses the structure of index/type/docId to locate any file within index/type with id = docId) | |
id |
...
Takes comma separated JsonPaths. The JSONPath is applied on the record received on the queue, the values hence obtained are appended and used as id for the record. | |
isBulk |
...
Boolean key to identify whether the JSON received on the Queue is from a Bulk API. In simple words, whether the JSON contains a list at the top level. | |
jsonPath |
...
Key to be used in case of indexing a part of the input JSON and in case of indexing a custom json where the values for custom json are to be fetched from this part of the input. | |
timeStampField |
...
JSONPath of the field in the input which can be used to obtain the timestamp of the input. | |
fieldsToBeMasked |
...
A list of JSONPaths of the fields of the input to be masked in the index. | |
customJsonMapping |
...
Key to be used while building an entirely different object using the input JSON on the queue |
...
...
indexMapping |
...
A skeleton/mapping of the JSON that is to be indexed. Note that, this JSON must always contain a key called "Data" at the top-level and the custom mapping begins within this key. This is only a convention to smoothen dashboarding on Kibana when data from multiple indexes have to be fetched for a single dashboard. |
...
fieldMapping |
...
Contains a list of configurations. Each configuration contains keys to identify the field of the input JSON that has to be mapped to the fields of the index json which is mentioned in the key 'indexMapping' in the config. |
...
inJsonPath |
...
JSONPath of the field from the input. | |
outJsonPath |
...
JSONPath of the field of the index json. |
...
externalUriMapping | Contains a list of configurations. Each configuration contains keys to identify the field of the input JSON that are to be enriched using APIs from the external services. The confiugration for those APIs also is a part of this. |
...
...
path |
...
URI of the API to be used. (it should be POST/_search API.) |
queryParam |
...
Configuration of the query params to be used for the API call. It is a comma seperated key-value pair, where key is the parameter name as per the API contract and value is the JSONPath of the field to be equated against this paramter. | |
apiRequest |
...
Request Body of the API. (Since we only use _search APIs, it should be only RequestInfo.) | |
uriResponseMapping |
...
Contains a list of configuration. Each configuration contains two keys: One is a JSONPath to identify the field from response, Second is also a JSONPath to map the response field to a field of the index json mentioned in the key 'indexMapping'. |
i) inJsonPath: JSONPath to identify the field from response
ii) outJsonPath: JSONPath to map the response field to a field of the index json
...
mdmsMapping | Contains a list of configurations. Each configuration contains keys to identify the field of the input JSON that are to be denormalized using APIs from the mdms service. The confiugration for those mdms APIs also is a part of this. |
...
path |
...
URI of the API to be used. (it should be POST/_search API.) | |
moduleName |
...
Module Name from MDMS. | |
masterName |
...
Master Name from MDMS. | |
tenantId |
...
Tenant id to be used. | |
filter |
...
Filter to be applied on the data to be fetched. | |
filterMapping |
...
Maps the field of input json to variables in the filter |
...
variable |
...
Variable in the filter |
...
valueJsonpath |
...
JSONPath of the input to be mapped to the variable |
...
uriResponseMapping: AS EXPLAINED ABOVE.
API Details
a) POST /{key}/_index
...
. |
...
b) POST /_reindex
This is used to migrate data from one index to another index
c) POST /_legacyindex
This is to run LegacyIndex job to index data from DB. In the request body the URL of the service which would be called by indexer service to pick data, must be mentioned.
Note: In legacy indexing and for collection-service record LiveIndex kafka-connect is used to do part of pushing record to elastic search. For more details please refer to document mentioned in document list.
Reference Docs
Doc Links
Title | Link |
Using kafka-connect in egov-indexer reindexing jobs to push records to elastic search | |
API Swagger Documentation |