Business API Design Specification - Check Inattendance

A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic.

While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized.

This document provides an in-depth explanation of the architectural design of the checkInAttendance Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side.

Main Data Object and CRUD Operation

The checkInAttendance Business API is designed to handle a create operation on the AttendanceRecord data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow.

API Description

Allows a user to check in for an assigned shift. Enforces strict one-record-per-user/shift/day, automatically determines status (present/late). Records check-in timestamp; only permitted if user assigned to shift.

API Frontend Description By The Backend Architect

Rendered as employee’s check-in button for assigned shift. Shows feedback on result (on-time/late/error). Manager/admin may impersonate check-in (override role checks).

API Options

API Controllers

A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel.

REST Controller

The checkInAttendance Business API includes a REST controller that can be triggered via the following route:

/v1/check-in

By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the Parameters section.

MCP Tool

REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This checkInAttendance Business API will be registered as a tool on the MCP server within the service binding.

API Parameters

The checkInAttendance Business API has 9 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client.

Business API parameters can be:

Regular Parameters

Name Type Required Default Location Data Path
attendanceRecordId ID No - body attendanceRecordId
Description: This id paremeter is used to create the data object with a given specific id. Leave null for automatic id.
shiftId ID Yes `` body shiftId
Description: ID of the shift for check-in
userId ID Yes - body userId
Description: Referenced user (employee)
checkInTime Date Yes - body checkInTime
Description: User check-in timestamp (set on check-in)
checkOutTime Date No - body checkOutTime
Description: User check-out timestamp (set on check-out)
status Enum Yes - body status
Description: Attendance status: present, absent, late, leftEarly, pending (checked in, not yet out)
lateByMinutes Integer No - body lateByMinutes
Description: How many minutes late (if late)
absenceReason String No - body absenceReason
Description: Reason for absence (manager-provided, e.g., sick, leave)
managerNote Text No - body managerNote
Description: Manager/admin note (optional for manual absence management)

Parameter Transformations

Some parameters are post-processed using transform scripts after being read from the request but before validation or workflow execution. Only parameters with a transform script are listed below.

No parameters are transformed in this API.

AUTH Configuration

The authentication and authorization configuration defines the core access rules for the checkInAttendance Business API. These checks are applied after parameter validation and before executing the main business logic.

While these settings cover the most common scenarios, more fine-grained or conditional access control—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like PermissionCheckAction, MembershipCheckAction, or ObjectPermissionCheckAction.

Login Requirement

This API requires login (loginRequired = true). Requests from non-logged-in users will return a 401 Unauthorized error. Login is necessary but not sufficient, as additional role, permission, or other authorization checks may still apply.

Ownership Checks

Role and Permission Settings

Data Clause

Defines custom field-value assignments used to modify or augment the default payload for create and update operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings.

Custom Data Clause Override

{
    userId: runMScript(() => (this.session.userId), {"path":"services[3].businessLogic[0].dataClause.customData[0].value"}),
    checkInTime: runMScript(() => (new Date()), {"path":"services[3].businessLogic[0].dataClause.customData[1].value"}),
   
}

Actual Data Clause

The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager.

{
  id: this.attendanceRecordId,
  companyId: this.companyId,
  userId: runMScript(() => (this.session.userId), {"path":"services[3].businessLogic[0].dataClause.customData[0].value"}),
  shiftId: this.shiftId,
  checkInTime: runMScript(() => (new Date()), {"path":"services[3].businessLogic[0].dataClause.customData[1].value"}),
  checkOutTime: this.checkOutTime,
  status: this.status,
  lateByMinutes: this.lateByMinutes,
  absenceReason: this.absenceReason,
  managerNote: this.managerNote,
  isActive: true,
  _archivedAt: null,
}

Business Logic Workflow

[1] Step : startBusinessApi

Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution.

You can use the following settings to change some behavior of this step. apiOptions, restSettings, grpcSettings, kafkaSettings, sseSettings, cronSettings

[2] Step : readParameters

Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context.

You can use the following settings to change some behavior of this step. customParameters, redisParameters

[3] Action : fetchShift

Action Type: FetchObjectAction

Fetch shift object from scheduleManagement for validation (date, startTime, assigned users)

class Api {
  async fetchShift() {
    // Fetch Object on childObject shift

    const userQuery = {
      $and: [
        {
          id: runMScript(() => this.shiftId, {
            path: "services[3].businessLogic[0].actions.fetchObjectActions[0].matchValue",
          }),
        },
        { isActive: true },
      ],
    };
    const { convertUserQueryToElasticQuery } = require("common");
    const scriptQuery = convertUserQueryToElasticQuery(userQuery);

    const elasticIndex = new ElasticIndexer("shift");
    const data = await elasticIndex.getOne(scriptQuery);

    if (!data) {
      throw new NotFoundError("errMsg_FethcedObjectNotFound:shift");
    }

    return data
      ? {
          id: data["id"],
          shiftDate: data["shiftDate"],
          startTime: data["startTime"],
          endTime: data["endTime"],
          assignedUserIds: data["assignedUserIds"],
          assignedDepartmentIds: data["assignedDepartmentIds"],
          status: data["status"],
          departmentId: data["departmentId"],
        }
      : null;
  }
}

[4] Step : transposeParameters

Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing.

[5] Action : fetchExistingAttendance

Action Type: FetchObjectAction

Fetch any existing attendanceRecords for this user/shift where active (block duplicate check-ins)

class Api {
  async fetchExistingAttendance() {
    // Fetch Object on childObject attendanceRecord

    const userQuery = {
      $and: [
        runMScript(
          () => ({
            userId: this.session.userId,
            shiftId: this.shiftId,
            isActive: true,
          }),
          {
            path: "services[3].businessLogic[0].actions.fetchObjectActions[1].whereClause",
          },
        ),
        { isActive: true },
      ],
    };
    const { convertUserQueryToSequelizeQuery } = require("common");
    const scriptQuery = convertUserQueryToSequelizeQuery(userQuery);

    // get object from db
    const data = await getAttendanceRecordByQuery(scriptQuery);

    return data
      ? {
          id: data["id"],
          status: data["status"],
        }
      : null;
  }
}

[6] Step : checkParameters

Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails.

[7] Action : validateNoDuplicateAttendance

Action Type: ValidationAction

Prevent duplicate attendance for same user/shift.

class Api {
  async validateNoDuplicateAttendance() {
    let isValid;
    try {
      isValid = runMScript(() => !this.existingAttendance, {
        path: "services[3].businessLogic[0].actions.validationActions[0].validationScript",
      });
    } catch (err) {
      throw new HttpServerError(
        `Validation 'validateNoDuplicateAttendance' script failed: ${err.message}`,
        err,
      );
    }

    if (!isValid) {
      throw new BadRequestError(
        "Attendance already logged for this shift user",
      );
    }
    return isValid;
  }
}

[8] Step : checkBasicAuth

Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions.

You can use the following settings to change some behavior of this step. authOptions

[9] Step : buildDataClause

Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency.

You can use the following settings to change some behavior of this step. dataClause

[10] Action : calculateLateness

Action Type: FunctionCallAction

Determine late status (present/late) and lateness minutes.

class Api {
  async calculateLateness() {
    try {
      return runMScript(
        () => LIB.calculateLateness(this.shiftObj, this.dataClause.checkInTime),
        {
          path: "services[3].businessLogic[0].actions.functionCallActions[0].callScript",
        },
      );
    } catch (err) {
      console.error("Error in FunctionCallAction calculateLateness:", err);
      throw err;
    }
  }
}

[11] Action : setStatusAndLateBy

Action Type: AddToContextAction

Set status and lateByMinutes before creation based on latenessInfo.

class Api {
  async setStatusAndLateBy() {
    try {
      this["dataClause.status"] = runMScript(
        () => (this.latenessInfo.isLate ? "late" : "present"),
        {
          path: "services[3].businessLogic[0].actions.addToContextActions[0].context[0].contextValue",
        },
      );

      this["dataClause.lateByMinutes"] = runMScript(
        () => this.latenessInfo.lateByMinutes,
        {
          path: "services[3].businessLogic[0].actions.addToContextActions[0].context[1].contextValue",
        },
      );

      return true;
    } catch (error) {
      console.error("AddToContextAction error:", error);
      throw error;
    }
  }
}

[12] Step : mainCreateOperation

Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records.

[13] Action : publishAttendanceEvent

Action Type: PublishEventAction

Publish attendance event for notificationService if late or present.

class Api {
  async publishAttendanceEvent() {
    const message = {
      userId: this.session.userId,
      shiftId: this.shiftId,
      status: this.dataClause.status,
      lateByMinutes: this.dataClause.lateByMinutes,
      companyId: this.session.companyId,
    };

    // Publish event to the configured topic
    const _publisher = new ServicePublisher(
      "attendance.logged",
      message,
      this.session,
      this.requestId,
    );
    await _publisher.publish();
    return true;
  }
}

[14] Step : buildOutput

Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract.

[15] Step : sendResponse

Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state.

[16] Step : raiseApiEvent

Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step.

Rest Usage

Rest Client Parameters

Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources.

The checkInAttendance api has got 8 regular client parameters

Parameter Type Required Population
shiftId ID true request.body?.[“shiftId”]
userId ID true request.body?.[“userId”]
checkInTime Date true request.body?.[“checkInTime”]
checkOutTime Date false request.body?.[“checkOutTime”]
status Enum true request.body?.[“status”]
lateByMinutes Integer false request.body?.[“lateByMinutes”]
absenceReason String false request.body?.[“absenceReason”]
managerNote Text false request.body?.[“managerNote”]

REST Request

To access the api you can use the REST controller with the path POST /v1/check-in

  axios({
    method: 'POST',
    url: '/v1/check-in',
    data: {
            shiftId:"ID",  
            userId:"ID",  
            checkInTime:"Date",  
            checkOutTime:"Date",  
            status:"Enum",  
            lateByMinutes:"Integer",  
            absenceReason:"String",  
            managerNote:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. For error handling, refer to the “Error Response” section.

Following JSON represents the most comprehensive form of the attendanceRecord object in the respones. However, some properties may be omitted based on the object’s internal logic.

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "attendanceRecord",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"attendanceRecord": {
		"id": "ID",
		"userId": "ID",
		"shiftId": "ID",
		"checkInTime": "Date",
		"checkOutTime": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"lateByMinutes": "Integer",
		"absenceReason": "String",
		"managerNote": "Text",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}