# **WORKFORCEOS** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 7 - EmployeeProfile Service** This document is a part of a REST API guide for the workforceos project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of employeeProfile ## Service Access EmployeeProfile service management is handled through service specific base urls. EmployeeProfile service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the employeeProfile service, the base URLs are: * **Preview:** `https://workforceos.prw.mindbricks.com/employeeprofile-api` * **Staging:** `https://workforceos-stage.mindbricks.co/employeeprofile-api` * **Production:** `https://workforceos.mindbricks.co/employeeprofile-api` ### Tenant URL Prefix and Header Forwarding Tenant context is resolved by frontend routing strategy: - preview/test: URL prefix `/{tenantCodename}` (example: `/babil/products`) - production: tenant subdomain (example: `babil.appname...`) Then backend API calls must always claim target tenant with header: ```js headers["mbx-company-codename"] = tenantCodenameFromUrl; ``` URL prefix/subdomain is frontend-only tenant selection. Use header forwarding for all tenant-scoped calls to `employeeProfile` service. ## Scope **EmployeeProfile Service Description** Manages extended employee profile data, employment/tax details, and employee-related documents/certifications for each company. Extends user identities with HR, department, and compliance info. Allows managers and admins to review employee profiles and documents.. EmployeeProfile service provides apis and business logic for following data objects in workforceos application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`employeeProfile` Data Object**: Extended business-centric employee profile with employment, compensation, department, and management fields associated to an auth user. Enables company to track staff employment metadata, department, position, and assigned manager for full HR oversight. **`employeeDocument` Data Object**: Document or certification attached to an employee profile. E.g., work permit, certification, or contract files. ## EmployeeProfile Service Frontend Description By The Backend Architect AI UX note: This microservice manages business-specific employee details beyond core user identity. For managers and admins, provide filtered views sortable by department, status, and position, with access to employee documents and notes. For employees, provide a secure, editable view of their own profile (with limits on updatable fields). Document detail views should show expiration and allow uploads (via file picker). Employee/manager selectors must use full names, roles, and departments for human-readable reference. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## EmployeeProfile Data Object Extended business-centric employee profile with employment, compensation, department, and management fields associated to an auth user. Enables company to track staff employment metadata, department, position, and assigned manager for full HR oversight. ### EmployeeProfile Data Object Frontend Description By The Backend Architect AI UX note: Profile pages expose all fields except salary/notes to the employee (notes are manager/admin only). Department/position fields are read-only for employees. Employment start is always visible. Manager/admin users see all fields for company staff, with filtering by department/position/status. ### EmployeeProfile Data Object Properties EmployeeProfile data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `userId` | ID | false | Yes | No | Reference to the auth user for this employee profile. | | `employmentStartDate` | Date | false | Yes | No | Employee's official employment start date. | | `position` | String | false | Yes | No | Employee's job title or position | | `contractType` | Enum | false | Yes | No | Type of employment contract for this employee. | | `salary` | Double | false | No | No | Employee's salary for reporting (managers/admins only). | | `departmentId` | ID | false | No | No | Reference to the department (userGroup) this employee belongs to. | | `managerId` | ID | false | No | No | ID of the assigned manager or supervisor (userId from auth:user). | | `notes` | Text | false | No | Yes | Manager/admin internal notes (not visible to employees). | | `companyId` | ID | false | Yes | No | An ID value to represent the tenant id of the company | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **contractType**: [permanent, temporary, contract] ### Relation Properties `userId` `departmentId` `managerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a sibling object, meaning that the relation is a many-to-one or one-to-one relationship from this object to the target. Required: Yes - **departmentId**: ID Relation to `userGroup`.id The target object is a sibling object, meaning that the relation is a many-to-one or one-to-one relationship from this object to the target. Required: No - **managerId**: ID Relation to `user`.id The target object is a sibling object, meaning that the relation is a many-to-one or one-to-one relationship from this object to the target. Required: No ### Filter Properties `userId` `employmentStartDate` `position` `contractType` `departmentId` `managerId` `companyId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` - **employmentStartDate**: Date has a filter named `employmentStartDate` - **position**: String has a filter named `position` - **contractType**: Enum has a filter named `contractType` - **departmentId**: ID has a filter named `departmentId` - **managerId**: ID has a filter named `managerId` - **companyId**: ID has a filter named `companyId` ## EmployeeDocument Data Object Document or certification attached to an employee profile. E.g., work permit, certification, or contract files. ### EmployeeDocument Data Object Frontend Description By The Backend Architect AI UX note: Document upload is via file selector, storing the URL as documentUrl. The list and detail view show document type, validity/expiration if set, and allow download/view (if permitted). New documents can be added by managers/admins; employees can see their own docs only. Document list is ordered by validUntil desc, with expired docs visually flagged. ### EmployeeDocument Data Object Properties EmployeeDocument data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Secret | Description | |----------|------|---------|----------|--------|-------------| | `employeeProfileId` | ID | false | Yes | No | Reference to the related employeeProfile record. | | `documentType` | String | false | Yes | No | Type of document (e.g., ID, contract, certification). | | `documentUrl` | String | false | Yes | Yes | URL to the file storage location or bucket for this document. | | `validUntil` | Date | false | No | No | Expiration date of document, if applicable. Used for tracking compliance/renewal. | | `companyId` | ID | false | Yes | No | An ID value to represent the tenant id of the company | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `employeeProfileId` `documentType` `validUntil` `companyId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **employeeProfileId**: ID has a filter named `employeeProfileId` - **documentType**: String has a filter named `documentType` - **validUntil**: Date has a filter named `validUntil` - **companyId**: ID has a filter named `companyId` ## Default CRUD APIs For each data object, the backend architect may designate **default APIs** for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (`isDefaultApi`), the frontend generator auto-discovers the most general API for each operation. ### EmployeeProfile Default APIs **Display Label Property:** `position` — Use this property as the human-readable label when displaying records of this data object (e.g., in dropdowns, references). | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createEmployeeProfile` | `/v1/employeeprofiles` | Yes | | Update | `updateEmployeeProfile` | `/v1/employeeprofiles/:employeeProfileId` | Yes | | Delete | `deleteEmployeeProfile` | `/v1/employeeprofiles/:employeeProfileId` | Auto | | Get | `getEmployeeProfile` | `/v1/employeeprofiles/:employeeProfileId` | Yes | | List | `listEmployeeProfiles` | `/v1/employeeprofiles` | Yes | ### EmployeeDocument Default APIs **Display Label Property:** `documentType` — Use this property as the human-readable label when displaying records of this data object (e.g., in dropdowns, references). | Operation | API Name | Route | Explicitly Set | |-----------|----------|-------|----------------| | Create | `createEmployeeDocument` | `/v1/employeedocuments` | Yes | | Update | `updateEmployeeDocument` | `/v1/employeedocuments/:employeeDocumentId` | Yes | | Delete | `deleteEmployeeDocument` | `/v1/employeedocuments/:employeeDocumentId` | Auto | | Get | `getEmployeeDocument` | `/v1/employeedocuments/:employeeDocumentId` | Yes | | List | `listEmployeeDocuments` | `/v1/employeedocuments` | Yes | When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API's body parameters. For relation fields, render a dropdown loaded from the related object's list API using the display label property. ## Secret Field Management Some data objects in the `employeeProfile` service contain **secret properties** — sensitive values like API keys, QR codes, or tokens that must be handled with care. ### How Secret Fields Work 1. **In API Responses**: Secret fields are returned with their actual values in normal REST API responses (the user's own token authorizes access). The frontend should mask these values by default and only reveal them on user action (e.g., clicking an "eye" toggle button). 2. **In MCP/AI Responses**: Secret fields are automatically masked with `***` in MCP tool responses. The AI model **never sees** the actual values. Each record that contains masked fields includes a `__proxyCode` — a temporary authorization token. 3. **Revealing Secrets via MCP**: When a user asks the AI to show a secret field, the AI uses the `showSecretFieldInFrontEnd` MCP tool with: - `proxyCode` — from the GET/LIST response (proves user authorization) - `fieldName` — the secret property to reveal - `renderType` — `"asText"`, `"asBarcode"`, or `"asQrCode"` The AI decides the `renderType` based on the user's request (e.g., "show me the QR code" → `asQrCode`). If the user doesn't specify a format, the AI should ask the user how they'd like to see it before calling the tool. 4. **Frontend Rendering**: The tool returns a `__frontendAction` with `type: "secret"` that the chat UI renders as a `SecretActionCard`. This card displays the actual value as text (with copy button), barcode, or QR code, and auto-hides after a timeout for security. ### Secret Properties by Data Object **EmployeeProfile**: `notes` **EmployeeDocument**: `documentUrl` ### Frontend Implementation Guidelines - **Data tables / detail views**: Mask secret fields with `***` or `••••••` by default. Show an eye toggle button that reveals the value on click. - **Forms**: Use password-type inputs for secret fields. Allow the user to toggle visibility. - **Chat UI**: The `SecretActionCard` component handles rendering when the AI reveals a secret via `showSecretFieldInFrontEnd`. - **Security**: Never log secret values in the browser console. Consider auto-hiding revealed values after a timeout. ### MCP Tool: showSecretFieldInFrontEnd ``` Tool Name: showSecretFieldInFrontEnd Parameters: - proxyCode (string, required): The __proxyCode from a previous GET/LIST response - fieldName (string, required): One of: notes, documentUrl - renderType (enum, required): "asText" | "asBarcode" | "asQrCode" Response: __frontendAction with type "secret" containing the actual value ``` ## API Reference ### `Create Employeeprofile` API **[Default create API]** — This is the designated default `create` API for the `employeeProfile` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Creates a new employee profile for a user in the company. **Rest Route** The `createEmployeeProfile` API REST controller can be triggered via the following route: `/v1/employeeprofiles` **Rest Request Parameters** The `createEmployeeProfile` api has got 8 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.body?.["userId"] | | employmentStartDate | Date | true | request.body?.["employmentStartDate"] | | position | String | true | request.body?.["position"] | | contractType | Enum | true | request.body?.["contractType"] | | salary | Double | false | request.body?.["salary"] | | departmentId | ID | false | request.body?.["departmentId"] | | managerId | ID | false | request.body?.["managerId"] | | notes | Text | false | request.body?.["notes"] | **userId** : Reference to the auth user for this employee profile. **employmentStartDate** : Employee's official employment start date. **position** : Employee's job title or position **contractType** : Type of employment contract for this employee. **salary** : Employee's salary for reporting (managers/admins only). **departmentId** : Reference to the department (userGroup) this employee belongs to. **managerId** : ID of the assigned manager or supervisor (userId from auth:user). **notes** : Manager/admin internal notes (not visible to employees). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/employeeprofiles** ```js axios({ method: 'POST', url: '/v1/employeeprofiles', data: { userId:"ID", employmentStartDate:"Date", position:"String", contractType:"Enum", salary:"Double", departmentId:"ID", managerId:"ID", notes:"Text", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeProfile", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "employeeProfile": { "id": "ID", "userId": "ID", "employmentStartDate": "Date", "position": "String", "contractType": "Enum", "contractType_idx": "Integer", "salary": "Double", "departmentId": "ID", "managerId": "ID", "notes": "Text", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Employeeprofile` API **[Default update API]** — This is the designated default `update` API for the `employeeProfile` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update the employee profile for a given user. Employees can only update their own profile; admins/managers can update any profile in the same company. **Rest Route** The `updateEmployeeProfile` API REST controller can be triggered via the following route: `/v1/employeeprofiles/:employeeProfileId` **Rest Request Parameters** The `updateEmployeeProfile` api has got 8 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeProfileId | ID | true | request.params?.["employeeProfileId"] | | employmentStartDate | Date | false | request.body?.["employmentStartDate"] | | position | String | false | request.body?.["position"] | | contractType | Enum | false | request.body?.["contractType"] | | salary | Double | false | request.body?.["salary"] | | departmentId | ID | false | request.body?.["departmentId"] | | managerId | ID | false | request.body?.["managerId"] | | notes | Text | false | request.body?.["notes"] | **employeeProfileId** : This id paremeter is used to select the required data object that will be updated **employmentStartDate** : Employee's official employment start date. **position** : Employee's job title or position **contractType** : Type of employment contract for this employee. **salary** : Employee's salary for reporting (managers/admins only). **departmentId** : Reference to the department (userGroup) this employee belongs to. **managerId** : ID of the assigned manager or supervisor (userId from auth:user). **notes** : Manager/admin internal notes (not visible to employees). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/employeeprofiles/:employeeProfileId** ```js axios({ method: 'PATCH', url: `/v1/employeeprofiles/${employeeProfileId}`, data: { employmentStartDate:"Date", position:"String", contractType:"Enum", salary:"Double", departmentId:"ID", managerId:"ID", notes:"Text", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeProfile", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "employeeProfile": { "id": "ID", "userId": "ID", "employmentStartDate": "Date", "position": "String", "contractType": "Enum", "contractType_idx": "Integer", "salary": "Double", "departmentId": "ID", "managerId": "ID", "notes": "Text", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Employeeprofile` API **[Default get API]** — This is the designated default `get` API for the `employeeProfile` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get detailed employee profile info, with enriched user, department, and manager references. Employees may view their own record; admins/managers can view any profile in company. **Rest Route** The `getEmployeeProfile` API REST controller can be triggered via the following route: `/v1/employeeprofiles/:employeeProfileId` **Rest Request Parameters** The `getEmployeeProfile` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeProfileId | ID | true | request.params?.["employeeProfileId"] | **employeeProfileId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/employeeprofiles/:employeeProfileId** ```js axios({ method: 'GET', url: `/v1/employeeprofiles/${employeeProfileId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeProfile", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "employeeProfile": { "id": "ID", "userId": "ID", "employmentStartDate": "Date", "position": "String", "contractType": "Enum", "contractType_idx": "Integer", "salary": "Double", "departmentId": "ID", "managerId": "ID", "notes": "Text", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "user": { "email": "String", "fullname": "String", "avatar": "String" }, "manager": { "email": "String", "fullname": "String", "avatar": "String" } } } ``` ### `List Employeeprofiles` API **[Default list API]** — This is the designated default `list` API for the `employeeProfile` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all employee profiles for a company, filterable by department, position, contract type, and manager. **Rest Route** The `listEmployeeProfiles` API REST controller can be triggered via the following route: `/v1/employeeprofiles` **Rest Request Parameters** **Filter Parameters** The `listEmployeeProfiles` api supports 4 optional filter parameters for filtering list results: **userId** (`ID`): Reference to the auth user for this employee profile. - Single: `?userId=` - Multiple: `?userId=&userId=` - Null: `?userId=null` **employmentStartDate** (`Date`): Employee's official employment start date. - Single date: `?employmentStartDate=2024-01-15` - Multiple dates: `?employmentStartDate=2024-01-15&employmentStartDate=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?employmentStartDate=null` **departmentId** (`ID`): Reference to the department (userGroup) this employee belongs to. - Single: `?departmentId=` - Multiple: `?departmentId=&departmentId=` - Null: `?departmentId=null` **managerId** (`ID`): ID of the assigned manager or supervisor (userId from auth:user). - Single: `?managerId=` - Multiple: `?managerId=&managerId=` - Null: `?managerId=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/employeeprofiles** ```js axios({ method: 'GET', url: '/v1/employeeprofiles', data: { }, params: { // Filter parameters (see Filter Parameters section above) // userId: '' // Filter by userId // employmentStartDate: '' // Filter by employmentStartDate // departmentId: '' // Filter by departmentId // managerId: '' // Filter by managerId } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeProfiles", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "employeeProfiles": [ { "id": "ID", "userId": "ID", "employmentStartDate": "Date", "position": "String", "contractType": "Enum", "contractType_idx": "Integer", "salary": "Double", "departmentId": "ID", "managerId": "ID", "notes": "Text", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "user": [ { "email": "String", "fullname": "String", "avatar": "String" }, {}, {} ], "department": [ null, null, null ], "manager": [ { "email": "String", "fullname": "String", "avatar": "String" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Employeedocument` API **[Default create API]** — This is the designated default `create` API for the `employeeDocument` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Create a new document entry for an employee profile. **Rest Route** The `createEmployeeDocument` API REST controller can be triggered via the following route: `/v1/employeedocuments` **Rest Request Parameters** The `createEmployeeDocument` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeProfileId | ID | true | request.body?.["employeeProfileId"] | | documentType | String | true | request.body?.["documentType"] | | documentUrl | String | true | request.body?.["documentUrl"] | | validUntil | Date | false | request.body?.["validUntil"] | **employeeProfileId** : Reference to the related employeeProfile record. **documentType** : Type of document (e.g., ID, contract, certification). **documentUrl** : URL to the file storage location or bucket for this document. **validUntil** : Expiration date of document, if applicable. Used for tracking compliance/renewal. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/employeedocuments** ```js axios({ method: 'POST', url: '/v1/employeedocuments', data: { employeeProfileId:"ID", documentType:"String", documentUrl:"String", validUntil:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeDocument", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "employeeDocument": { "id": "ID", "employeeProfileId": "ID", "documentType": "String", "documentUrl": "String", "validUntil": "Date", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Employeedocument` API **[Default update API]** — This is the designated default `update` API for the `employeeDocument` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Update a specific employee document (e.g., to update expiration date or replace file reference). **Rest Route** The `updateEmployeeDocument` API REST controller can be triggered via the following route: `/v1/employeedocuments/:employeeDocumentId` **Rest Request Parameters** The `updateEmployeeDocument` api has got 4 regular request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeDocumentId | ID | true | request.params?.["employeeDocumentId"] | | documentType | String | false | request.body?.["documentType"] | | documentUrl | String | false | request.body?.["documentUrl"] | | validUntil | Date | false | request.body?.["validUntil"] | **employeeDocumentId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of document (e.g., ID, contract, certification). **documentUrl** : URL to the file storage location or bucket for this document. **validUntil** : Expiration date of document, if applicable. Used for tracking compliance/renewal. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/employeedocuments/:employeeDocumentId** ```js axios({ method: 'PATCH', url: `/v1/employeedocuments/${employeeDocumentId}`, data: { documentType:"String", documentUrl:"String", validUntil:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeDocument", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "employeeDocument": { "id": "ID", "employeeProfileId": "ID", "documentType": "String", "documentUrl": "String", "validUntil": "Date", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Employeedocument` API **[Default get API]** — This is the designated default `get` API for the `employeeDocument` data object. Frontend generators and AI agents should use this API for standard CRUD operations. Get a specific employee document by ID, with enriched employeeProfile info. **Rest Route** The `getEmployeeDocument` API REST controller can be triggered via the following route: `/v1/employeedocuments/:employeeDocumentId` **Rest Request Parameters** The `getEmployeeDocument` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeDocumentId | ID | true | request.params?.["employeeDocumentId"] | **employeeDocumentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/employeedocuments/:employeeDocumentId** ```js axios({ method: 'GET', url: `/v1/employeedocuments/${employeeDocumentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeDocument", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "employeeDocument": { "id": "ID", "employeeProfileId": "ID", "documentType": "String", "documentUrl": "String", "validUntil": "Date", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "employeeProfile": { "userId": "ID", "position": "String", "contractType": "Enum", "contractType_idx": "Integer" } } } ``` ### `List Employeedocuments` API **[Default list API]** — This is the designated default `list` API for the `employeeDocument` data object. Frontend generators and AI agents should use this API for standard CRUD operations. List all documents for employee profiles (optionally filtered by type, validity, or profile). **Rest Route** The `listEmployeeDocuments` API REST controller can be triggered via the following route: `/v1/employeedocuments` **Rest Request Parameters** **Filter Parameters** The `listEmployeeDocuments` api supports 2 optional filter parameters for filtering list results: **employeeProfileId** (`ID`): Reference to the related employeeProfile record. - Single: `?employeeProfileId=` - Multiple: `?employeeProfileId=&employeeProfileId=` - Null: `?employeeProfileId=null` **validUntil** (`Date`): Expiration date of document, if applicable. Used for tracking compliance/renewal. - Single date: `?validUntil=2024-01-15` - Multiple dates: `?validUntil=2024-01-15&validUntil=2024-01-20` - Special: `$today`, `$ltoday`, `$week`, `$lweek`, `$month`, `$leq-`, `$lin-` - Null: `?validUntil=null` **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/employeedocuments** ```js axios({ method: 'GET', url: '/v1/employeedocuments', data: { }, params: { // Filter parameters (see Filter Parameters section above) // employeeProfileId: '' // Filter by employeeProfileId // validUntil: '' // Filter by validUntil } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeDocuments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "employeeDocuments": [ { "id": "ID", "employeeProfileId": "ID", "documentType": "String", "documentUrl": "String", "validUntil": "Date", "companyId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "employeeProfile": { "userId": "ID", "position": "String", "contractType": "Enum", "contractType_idx": "Integer" } }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Employeeprofile` API **Rest Route** The `deleteEmployeeProfile` API REST controller can be triggered via the following route: `/v1/employeeprofiles/:employeeProfileId` **Rest Request Parameters** The `deleteEmployeeProfile` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeProfileId | ID | true | request.params?.["employeeProfileId"] | **employeeProfileId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/employeeprofiles/:employeeProfileId** ```js axios({ method: 'DELETE', url: `/v1/employeeprofiles/${employeeProfileId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeProfile", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "employeeProfile": { "id": "ID", "userId": "ID", "employmentStartDate": "Date", "position": "String", "contractType": "Enum", "contractType_idx": "Integer", "salary": "Double", "departmentId": "ID", "managerId": "ID", "notes": "Text", "companyId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Employeedocument` API **Rest Route** The `deleteEmployeeDocument` API REST controller can be triggered via the following route: `/v1/employeedocuments/:employeeDocumentId` **Rest Request Parameters** The `deleteEmployeeDocument` api has got 1 regular request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | employeeDocumentId | ID | true | request.params?.["employeeDocumentId"] | **employeeDocumentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/employeedocuments/:employeeDocumentId** ```js axios({ method: 'DELETE', url: `/v1/employeedocuments/${employeeDocumentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "employeeDocument", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "employeeDocument": { "id": "ID", "employeeProfileId": "ID", "documentType": "String", "documentUrl": "String", "validUntil": "Date", "companyId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.**