getById() — Entity Service

General Description

The getById operation retrieves a single entity by its unique identifier.

Detailed Description

This operation allows you to fetch a specific entity record from the database using its unique ID. It returns the complete entity with all its properties as defined in the entity definition. This is the most direct way to retrieve a specific entity when you know its ID.

Input Parameters

Parameter	Type	Required	Description
definitionType	string	Yes*	Name or id of the entity definition.
id	string	Yes	ID of the entity to retrieve.
token	string	No	Authentication token for the request. The MCP/CLI runtime injects the verified session token when it invokes this operation; direct service callers must provide or configure credentials.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Response

Success Response

{
    "success": true,
    "entity": {
        "id": "string",
        "title": "string",
        "createDate": "string",
        "lastUpdateDate": "string",
        // All other properties of the entity
        "property1": "value1",
        "property2": "value2"
    }
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Get Customer by ID through the MCP tool

const result = await getById({
  definitionType: "Customer",
  id: "customer-id-123",
  token: "your-auth-token"
});

if (result.success) {
  const customer = result.entity;
  console.log("Customer:", customer.title);
  console.log("Email:", customer.email);
  console.log("Created:", customer.createDate);
} else {
  console.error("Error:", result.error);
}

The MCP/CLI wrapper accepts this object shape and injects the verified session token when the caller does not provide one.

Get Customer by ID through GsbEntityService

const customer = await entityService.getById(
  "customer-def-456",
  "customer-id-123",
  "your-auth-token",
  "tenant1"
);

if (customer) console.log("Customer:", customer.title);

The direct service method is positional: definitionType, id, token, then tenantCode. It returns the entity or null, rather than the MCP wrapper response envelope.

Get Entity with Optional Parameters through the MCP tool

const result = await getById({
  definitionType: "Product",
  id: "product-id-789",
  token: "your-auth-token",
  tenantCode: "tenant1"
});

if (result.success) {
  const product = result.entity;
  console.log("Product:", product.title);
  console.log("Price:", product.price);
  console.log("In Stock:", product.inStock ? "Yes" : "No");
} else {
  console.error("Error:", result.error);
}

Additional Information

• The getById operation is used to retrieve a single entity by its unique identifier.
• The operation returns all properties of the entity as defined in the entity definition.
• If the entity does not exist, the operation will return an error with message "Entity not found".
• For retrieving multiple entities or filtering by criteria, use the query operation instead.
• For retrieving an entity with its related entities based on cascade references, use the getCopy operation.
• Access permissions are enforced based on the provided token.
• The operation does not follow references to other entities; it only returns the requested entity.
• If you need to retrieve related entities, you'll need to make separate getById calls or use a query with includes.