1. Introduction

The Employee Data Integration enables external applications to exchange employee information with uKnowva HRMS through secure REST APIs. It allows organizations to automate employee lifecycle operations such as creating new employee records, updating existing employee information, disabling user accounts, and retrieving employee master data, eliminating the need for manual data entry and reducing the risk of data inconsistencies.

The integration is designed to work seamlessly with enterprise applications such as HRMS, ERP, payroll, recruitment, and identity management systems. Employee information is transmitted in a predefined JSON format and processed securely by uKnowva HRMS. During processing, the incoming data is mapped to the corresponding employee master fields configured within the Administrator module, allowing organizations to integrate their existing systems without modifying their internal data structure.

This guide explains the overall integration workflow, the prerequisites for implementation, configuration requirements, payload mapping, sample requests, and recommended practices for successful integration. It is intended for implementation partners, developers, and system administrators responsible for integrating external applications with uKnowva HRMS.

For complete API specifications, including endpoint details, request parameters, response schemas, and error codes, refer to the User Management API Documentation.

2. Supported Operations

The Employee Data Integration supports the core user lifecycle operations required to keep employee information synchronised between an external application and uKnowva HRMS. Depending on the business event triggered in the source application, the integration can create new employee records, update existing employee details, disable user accounts, or retrieve employee master data.

Create Employee

The Create Employee operation is used during the onboarding process to add new employees to uKnowva HRMS. The external application sends employee details in a predefined JSON payload, which is authenticated and processed by the system. Based on the configured field mappings, the employee information is stored in the corresponding fields within uKnowva HRMS. Once the request is successfully processed, a new employee account is created and made available for further HR processes.

Update Employee

The Update Employee operation allows external applications to modify information for existing employees. This operation is commonly used when there are changes to an employee's personal details, contact information, reporting manager, designation, department, or other mapped fields. Only the fields included in the request payload are updated, ensuring that employee records remain accurate and up to date without requiring manual intervention.

Disable Employee

The Disable Employee operation is typically used during employee offboarding or when user access needs to be temporarily suspended. Instead of deleting employee information from the system, the integration disables the user account, preventing further access while preserving historical employee records for reporting, auditing, and compliance purposes.

Fetch Employee Master Data

The integration also supports retrieving employee master data from uKnowva HRMS. This operation enables external applications to access employee information maintained within the system for reporting, synchronisation, or downstream business processes. The retrieved data can be filtered based on configured criteria such as employee status, department, or designation, depending on the deployed report configuration.

3. Integration Workflow

The Employee Data Integration follows a secure request-response workflow that enables external applications to exchange employee information with uKnowva HRMS. Employee data is sent from the client application in a predefined JSON format and processed by the User Operations API. Before the data is stored, the request is authenticated, and the incoming fields are mapped to the corresponding employee master fields configured in the Administrator module. Once the requested operation is completed, the API returns a response indicating the outcome of the request.

Workflow Description

The integration process consists of the following steps:

Step 1: Employee data is generated

The external application prepares the employee information in the agreed JSON payload format whenever a user needs to be created, updated, or disabled.

Step 2: The request is authenticated

The application sends the request to the configured uKnowva API endpoint using the assigned Bearer Token to ensure that only authorized systems can access the API.

Step 3: Employee data is processed

After successful authentication, uKnowva validates the request and processes the employee information.

Step 4: Field mapping is applied

The incoming payload fields are mapped to the corresponding employee master fields configured in the Administrator module. This allows different applications to use their own field names while ensuring that the data is stored correctly in uKnowva HRMS.

Step 5: The requested operation is performed

Based on the request, uKnowva creates a new employee record, updates an existing employee, or disables a user account.

Step 6: Response is returned

Once processing is complete, the API returns a JSON response indicating whether the operation was successful or if any validation or processing errors occurred.

Note

The exact request payload and API endpoint may vary depending on the customer's implementation and configured field mappings. This guide focuses on the integration workflow, while the complete API specifications, request parameters, and response schemas are available in the User Management API Documentation.

Example Integration Scenario

A payroll system onboards a new employee and sends a JSON payload containing the employee's username, name, email, gender, date of birth, and designation. The request is authenticated using the configured API token. uKnowva validates the payload, maps the incoming fields to the employee master fields, creates the employee record, and returns a success response containing the newly created user information.

4. Prerequisites

Before integrating an external application with the uKnowva HRMS User Operations API, ensure that the necessary API access, authentication credentials, and system configurations are available. Completing these prerequisites helps establish secure communication between the client application and uKnowva HRMS while ensuring that employee data is processed accurately.

 

Before You Begin

Before initiating the integration, verify that:

• The API endpoint is accessible from the external application.

• A valid Bearer Token has been generated and shared with the integrating application.

• The required employee fields have been identified for integration.

• Field mappings have been configured in the Administrator module.

• The external application is capable of sending requests in JSON format over HTTPS.

Note: The exact payload structure may vary based on the external application. uKnowva HRMS supports configurable field mapping, allowing incoming fields to be mapped to the appropriate employee master fields without requiring changes to the source application's data structure.

5. Configuration

Before the integration can be used, the User Operations API must be configured to allow secure communication between the external application and uKnowva HRMS. This involves configuring the API endpoint, authenticating requests using a Bearer Token, and mapping the incoming employee data to the corresponding fields in uKnowva HRMS.

API Endpoint Configuration

The external application must be configured to send employee data to the User Operations API endpoint provided for your uKnowva HRMS instance. The endpoint acts as the communication channel through which employee data is exchanged between the client application and uKnowva HRMS.

Ensure that the application uses the endpoint corresponding to your environment (development, testing, or production) before initiating the integration.

Note: The endpoint URL is unique to each uKnowva HRMS instance.

API Authentication

All requests to the User Operations API are authenticated using a Bearer Token. The token verifies the identity of the calling application and ensures that only authorized systems can access the API.

The Bearer Token must be included in every API request. Requests with invalid or missing tokens are rejected and are not processed.

Note: Keep the API token secure and avoid exposing it in application logs or public repositories.

Administrator Field Mapping

The User Operations API supports configurable field mapping through the Administrator module. This allows incoming fields from the external application to be mapped to the corresponding employee master fields in uKnowva HRMS.

For example, if the external application sends a field named Role, it can be mapped to the Designation field in uKnowva HRMS. Similarly, fields such as dob, gender, or panAttach can be mapped to the appropriate employee fields without requiring changes to the client's payload structure.

Field mapping provides flexibility when integrating applications that use different naming conventions or custom employee fields.

Custom Field Support

In addition to standard employee fields, the integration can support custom fields configured within the uKnowva HRMS instance. These fields can be mapped in the same way as standard fields, allowing organizations to exchange additional employee information required for their business processes.

Any custom field mappings should be completed before the integration is tested or moved to production.

Configuration Checklist

Before proceeding with the integration, verify that:

• The correct User Operations API endpoint has been configured.

• A valid Bearer Token is available for authentication.

• Required employee fields have been mapped in the Administrator module.

• Any custom fields have been configured and mapped, if applicable.

• The integration has been tested using sample employee data.

6. Payload Mapping

The User Operations API accepts employee information in JSON format from the external application. During request processing, the incoming fields are mapped to the corresponding employee master fields configured in the uKnowva HRMS Administrator module.

This mapping enables organizations to integrate applications with different data structures without modifying their existing payload format. As long as the appropriate field mappings are configured, the API can process the incoming data and update the corresponding employee record in uKnowva HRMS.

Sample Payload

The following example illustrates a typical payload received from an external application:

{

    "dob": "1993-05-16",

    "Role": "",

    "name": "Divyesh",

    "zone": null,

    "block": 0,

    "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",

    "gender": "Male",

    "username": "divyesh",

    "panAttach": "https://storage.googleapis.com/example/pan.jpg"

}

Example Field Mapping

The following table shows how fields from the client payload can be mapped to employee master fields in uKnowva HRMS.

Note: The field mapping shown above is for illustration purposes. The actual mapping depends on your organization's employee master configuration and may vary from one implementation to another.

Mapping Guidelines

• Ensure that mandatory employee fields are mapped before testing the integration.

• Verify that the data type of each incoming field matches the corresponding field in uKnowva HRMS.

• If the external application uses custom field names, configure the appropriate mappings in the Administrator module before enabling the integration.

• Review and update field mappings whenever new employee attributes are introduced in either system.

7. Sample Requests

The following examples demonstrate the typical payloads used when integrating an external application with the uKnowva HRMS User Operations API. The exact fields included in each request may vary depending on your organization's field mapping configuration and business requirements.

Note: These examples are for reference only. Refer to the User Management API Documentation for the complete request parameters, endpoint details, and response schemas.

Create Employee

Use this request when onboarding a new employee into uKnowva HRMS.

{

   "username": "john.doe",

   "name": "John Doe",

   "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",

   "gender": "Male",

   "dob": "1995-08-15",

   "Role": "Software Engineer",

   "block": 0

}

Update Employee

Use this request to update an existing employee's information. Include only the fields that need to be modified, along with the employee identifier required by your implementation.

{
  "username": "john.doe",
  "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
  "Role": "Senior Software Engineer",
  "block": 0
}

Disable Employee

Use this request when an employee leaves the organization or their system access needs to be disabled.

{

   "delete": "true",
  "username": "john.doe"

}

Note: Depending on your implementation, the employee can be identified using the username, email address, or employee ID. Refer to the API documentation for the supported parameters.

Expected Outcome

After processing each request, the API returns a JSON response indicating whether the operation was successful or if any validation or processing errors occurred. Applications integrating with uKnowva HRMS should validate the response and handle success or failure scenarios appropriately.

Sample cURL Request

The following example demonstrates how to invoke the User Operations API using cURL. You can use this command to test the API before integrating it with your application.

curl --location 

'https://<your-instance>.uknowva.com/api.php/system/uknowva/updateUser' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer <your_api_token>' \

--data-raw '{

    "dob": "1993-05-16",

    "Role": "",

    "name": "Divyesh",

    "zone": null,

    "block": 0,

    "email": "This email address is being protected from spambots. You need JavaScript enabled to view it.",

    "gender": "Male",

    "username": "divyesh",

   "panAttach": 

 "https://storage.googleapis.com/ezeone/icanrefer/64f4bf83-4046-4628-acb5-bf4cccebbef 2.jpg"

}'

7. Troubleshooting & Best Practices

This section highlights common issues that may occur during integration and provides recommendations to help ensure a smooth and reliable implementation.

Best Practices

To ensure a secure and reliable integration, follow these recommendations:

• Use HTTPS for all API communications.

• Securely store and manage Bearer Tokens. Do not expose them in source code or public repositories.

• Configure and verify field mappings before testing the integration.

• Validate mandatory fields in the source application before sending API requests.

• Use a unique employee identifier, such as the username or employee ID, to avoid duplicate records.

• Test the integration in a non-production environment before deploying it to production.

• Refer to the User Management API Documentation for complete endpoint details, request parameters, and response schemas.

Conclusion

That’s it!

You’ve now successfully learned how to configure and implement the Employee Data Integration with uKnowva HRMS.

By following this guide, you can securely connect your external application with uKnowva HRMS, configure the required field mappings, and automate employee lifecycle operations such as user creation, profile updates, and user deactivation. 

 

If you have any questions or need additional support, feel free to contact us at This email address is being protected from spambots. You need JavaScript enabled to view it.