Manage Data APIs

Overview

The documentation details APIs for creating, searching, generating, and downloading data, including request/response structures, flows, and error handling.

Create Data

Endpoint

• Endpoint: /data/_create

• Method: POST

Request Structure

• Body Parameters:

  • RequestInfo: Object containing request information.

  • Resource Details: Object containing the details of the resource to be created or validated.

    • type: Type of resource (boundary, facility, user, boundaryWithTarget).

    • tenantId: Tenant identifier.

    • fileStoreId: File store identifier.

    • action: Action type (create or validate).

    • hierarchyType: Type of hierarchy.

    • campaignId: Campaign identifier.

    • additionalDetails: Additional details object (optional).

Response Structure

• Success Response:

  - ResponseInfo: Object containing response information.

  - ResourceDetails: Array containing the detail objects of the created or validated resource.

Flow

1. Client Initiates Request: The client sends a createData request to the Project Factory service.

2. Validation of Request: The Project Factory service validates the request schema and the provided resource details.

3. Processing the Request:

   • If action is 'create':

     • Enrich resource details, set status to "data-accepted", and persist in the database.

     • Further creation process happens in the background.

     • After successful creation, set the status to 'completed' and persist resource details in the database.

   • If action is 'validate':

     • Enrich resource details, set the status to "validation-started", and persist in the database.

     • Further creation process happens in the background.

     • If file data is invalid, set the status to 'invalid' and persist in the database.

     • After successful creation, set the status to 'completed' and persist resource details in the database.

   • Fail case: If validation or creation fails, set the status to 'failed' and persist in the database with the error cause in additional details.

4. Response: The Project Factory service sends the response back to the client containing the resource details and status.

Flow Diagram

Parsing Logic from sheet

The getSheetData function retrieves and processes data from an Excel sheet, validating the structure according to the configuration provided in createAndSearchConfig. The key part of this process is the parseArrayConfig.parseLogic configuration, which specifies how to parse and validate the columns in the sheet. Here's a detailed explanation of how the function works, including the parsing logic:

Parsing Logic Using parseArrayConfig.parseLogic

The parseArrayConfig.parseLogic configuration specifies how each column in the sheet should be processed. Here's how the parsing logic works:

parseLogic: [
    {
        sheetColumn: "A",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_CODE",
        resultantPath: "id",
        type: "string"
    },
    {
        sheetColumn: "B",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_NAME",
        resultantPath: "name",
        type: "string"
    },
    {
        sheetColumn: "C",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_TYPE",
        resultantPath: "usage",
        type: "string"
    },
    {
        sheetColumn: "D",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_STATUS",
        resultantPath: "isPermanent",
        type: "boolean",
        conversionCondition: {
            "Permanent": "true",
            "Temporary": ""
        }
    },
    {
        sheetColumn: "E",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_CAPACITY",
        resultantPath: "storageCapacity",
        type: "number"
    },
    {
        sheetColumn: "F",
        sheetColumnName: "HCM_ADMIN_CONSOLE_BOUNDARY_CODE_MANDATORY"
    }
]

Column Configuration

Each column configuration specifies:

• sheetColumn: The column letter in the sheet.

• sheetColumnName: The expected name of the column in the sheet.

• resultantPath: The path where the value will be stored in the resultant JSON.

• type: The expected type of the value (e.g., string, number, boolean).

• conversionCondition: Optional conditions for converting values.

Validating Column Names

During the validation step, the function checks that the first-row value matches the expected column name.

Processing Rows

When mapping the rows to JSON, the function uses the resultantPath to place the values in the correct location in the JSON object. It converts values according to the specified type and conversionCondition.

Example Conversion

For a column configuration with type: "boolean" and conversionCondition, the function would convert "Permanent" to true and "Temporary" to an empty string.

{
    "sheetColumn": "D",
    "sheetColumnName": "HCM_ADMIN_CONSOLE_FACILITY_STATUS",
    "resultantPath": "isPermanent",
    "type": "boolean",
    "conversionCondition": {
        "Permanent": "true",
        "Temporary": ""
    }
}

In summary, the getSheetData function retrieves and processes data from an Excel sheet, validating the structure and content according to the createAndSearchConfig configuration. The parseArrayConfig.parseLogic configuration specifies how each column should be validated and processed into the resultant JSON format.

Search Data API

Endpoint

• Endpoint: /data/_search

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• SearchCriteria: Object containing search criteria.

  • id: (Optional) ID of the resource.

  • tenantId: Tenant identifier.

  • type: (Optional) Type of the resource (boundary, facility, user, boundaryWithTarget).

  • status: (Optional) Status of the resource.

Response Body Structure

• ResponseInfo: Object containing response information.

• ResourceDetails: Array containing the details object of the searched resource.

Flow

1. Client Request: The client sends a POST request to /data/_search.

2. Request Content: Includes RequestInfo and SearchCriteria.

3. Validation: The server validates request structure and content.

4. Response Creation: The server creates a response with info and resource details.

5. Response Dispatch: Sends response back to client.

6. Error Handling: If errors occur, generate an error response and send it.

Flow Diagram

Generate Data API

Endpoint

• Endpoint: /data/_generate

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• Query Parameters:

  • type: Type of the resource for which data needs to be generated.

  • tenantId: Tenant identifier.

  • hierarchyType: Type of hierarchy.

  • forceUpdate: (Optional) Boolean indicating whether to force update existing data.

Response Structure

• ResponseInfo: Object containing response information.

• GeneratedResource: Array containing the details object of the generated resource.

Flow

1. Client Request: The client sends a POST request to /v1/data/_generate.

2. Request Validation: Aftern receiving the request, the server validates the request structure and parameters.

3. Generate Data Process:

   • Validation: The server validates the generated request.

   • Data Processing:

     • Fetch Data: Fetches existing data from the database.

     • Modify Data: Modify the retrieved data as necessary.

     • Generate New ID: Generates a new random ID and sets the file store ID to null.

     • Expire Old Data: Marks existing data status as expired.

     • Generate New Data: Generates new data based on the request parameters.

     • Update and Persist: Updates and persists the generated request along with the new data.

   • Force Update Logic:

     • If the forceUpdate parameter is set to true:

       • Search and Update: Searches for existing data of the specified type and updates the existing data information.

     • If the forceUpdate parameter is not provided or set to false:

       • Fetch Existing Data: Retrieves already persisted data from the database of the specified type.

4. Response Creation: After processing the request, the server creates a response containing the details of the generated resource.

5. Response Dispatch: The server sends the generated response back to the client.

6. Error Handling: If errors occur, generate an error response and send it.

Flow Diagram

Data to Sheet Parsing Logic

1. Fetch Required Columns from MDMS:

   • Use callMdmsData to get type schema columns in the correct order.

2. Define Headers:

   • MDMS schema required columns are headers and ensures column orders.

3. Localise Headers:

   • Use getLocalizedHeaders with localizationMap.

4. Localise Sheet Name:

   • Use getLocalizedName with localizationMap and generate a sheet.

Adding a New Column to the Generated Sheet

To add a new column to the Generated sheet, follow these steps:

1. Search Schema Details

   • Locate the type schema from the HCM-ADMIN-CONSOLE.adminSchema schema in the workbench.

2. Identify Column Type

   • Determine the column type based on the properties defined in the schema:

     • stringProperties for string-based columns.

     • numberProperties for numeric-based columns.

     • enumProperties for enumerated columns.

3. Define New Column

   • Add the new column to the schema under the appropriate properties section:

     • String Column: Include attributes such as name, type, maxLength, minLength, isUnique, isRequired, description, and orderNumber.

     • Number Column: Include attributes such as name, type, maximum, minimum, isRequired, description, orderNumber, and errorMessage.

     • Enum Column: Include attributes such as name, enum, isRequired, description, and orderNumber.

4. Ensure Column Uniqueness

   • Ensure that the isUnique property is correctly set for string columns to enforce uniqueness.

5. Column Visibility (Future Implementation)

   • Note that hideColumn and freezeColumn features will be implemented in the next version.

Sheet Data Validation:

This process is sufficient for validating the new column in the generated sheet.

Column Change Reflection in APIs

If there's a need to reflect the column in APIs, follow these additional steps:

1. Update createAndSearch.ts File

   • Modify the createAndSearch.ts file under the defined type parseLogic object.

   • Integrate the new column into the appropriate data structures used for API operations.

   • Example :

     • sheetColumn: A

     • sheetColumnName: HCM_ADMIN_CONSOLE_FACILITY_CODE

     • resultantPath: id

     • type: string

     • Mapping: Data from column A (HCM_ADMIN_CONSOLE_FACILITY_CODE) in the sheet will be mapped to id in the API data.

By following these steps, you can successfully add and validate a new column in the generated sheet and ensure its reflection in the associated APIs.

Template Properties

General Rules

• Locked Headers: The headers in the templates for each data type (user, facility, target) are locked and cannot be changed.

• Sheet Protection: Certain sheets within the templates will have specific locked areas to ensure data integrity.

• README Sheet: Each type of template includes a README sheet which is read-only and locked.

Target Template

• Editable Columns: You can only modify the 'Target' column. All other columns are locked and cannot be edited.

Facility Template

• Adding Rows: You are allowed to add new rows to create new facilities.

• Editable Columns: You can modify the "Boundary Code" and 'Usage' columns.

• Locked Sheets: The boundary data sheet within the facility template is locked and cannot be modified.

• Dropdown Columns: The following columns are dropdowns:

  • Facility Type

  • Facility Status

  • Facility Usage

• Facility Usage: Facility usage can be 'Active' or 'Inactive'. Active facilities are used in the campaign and require a boundary code to map.

User Template

• Adding Rows: You are allowed to add new rows.

• Locked Sheets: The boundary data sheet within the user template is locked and cannot be modified.

• Dropdown Columns: The following columns are dropdowns:

  • Role

  • Employment Type

Data for Dropdowns

• The data for the dropdown columns comes from the mdms (Master Data Management System) under the adminSchema master.

Download Data API

Endpoint

• Endpoint: /data/_download

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• Type: (Optional) Type of the resource being downloaded.

• TenantId: Tenant identifier.

• HierarchyType: Type of hierarchy.

• Id: (Optional) ID of the resource being downloaded.

• Filters: (Optional) Additional filters for the download request.

• campaignId : campaignId

Response Structure

• ResponseInfo: Object containing response information.

• ResourceDetails: Array containing the details object of the downloaded resource.

Flow

1. Client Request: The client sends a POST request to download data.

2. Request Validation: Upon receiving the request, the server validates the request structure and parameters.

3. Data Download Process:

   • Validation: Validate the download request.

   • Fetch Data: Fetch existing data of the specified type from the data host service.

   • Processing: Process the retrieved data as necessary.

4. Response Creation: After processing the request, the server creates a response containing the details of the latest resource, ensuring that only one result is fetched.

5. Response Dispatch: The server sends the generated response back to the client.

6. Error Handling: If errors occur during the process, an error response is generated and sent.

Flow Diagram

Handling Empty or Missing Downloaded Responses

If the downloaded response is empty or not searched with the provided ID, the system automatically starts regenerating a template of the same type. The generation process is triggered by the backend, not through the UI.