GSMOperations: Agricultural Data and Transactions Service

GSMOperations is the core business-logic microservice of the GSM Application platform. It owns all operational agricultural data: herb product catalogs, employee and supplier registries, SKU definitions, product categories, and the full transaction lifecycle from creation through state transitions. It also hosts the integration execution engine that runs API rules configured in GSMApplication. Like every GSM microservice, it is fully multi-tenant — each request resolves to an isolated tenant database via the X-Company-Id header provided by the gateway. The service listens on port 8083 and is reached through the gateway at the /api/operations/** prefix.

Domain Entities

GSMOperations manages a rich agricultural domain. The key entity groups are:

Employee

Farm workers stored in db_ms.Employees. Fields: IdEmployee, FirstName, LastName, FullName, Location, ContactNumber, Email, IsActive.

Supplier

Input and produce suppliers stored in db_ms.Suppliers. Fields: IdSupplier (GUID), IdThirdSupplier, NameSupplier, CategorySupplier, Region, Country, Contact, IsActive.

MasterProduct (Herb)

The herb product catalog. Each record represents a cultivated herb variety and is the root reference for transactions and SKU definitions.

MasterVariety

Specific cultivar or variety within a master product, allowing fine-grained tracking of harvest attributes.

SKU Definition

Defines the SKU structure for a product including unit, weight, and packaging configuration.

TrxHeader

The root transaction record. Carries TrxPrefix, description, username, location, and a unique numeric IdTrxHeader.

TrxDetail / TrxProduct / TrxAttribute / TrxStates

Sub-records linked to a TrxHeader. Together they model the full structure of a harvest or productivity transaction.

Endpoints

Reference Data

`GET /api/v1/operations/parameters`

Returns the full list of global parameters configured for the tenant. Parameters control platform behavior such as default units, rounding rules, and feature flags.

Status	Condition
`200 OK`	Parameters returned.
`404 Not Found`	No parameters configured for the tenant.

`GET /api/v1/operations/master-products`

Returns the complete herb product catalog for the tenant.

Status	Condition
`200 OK`	Product list returned.
`404 Not Found`	No products configured.

`GET /api/v1/operations/filtered-employees`

Returns a filtered list of employees. Search criteria are provided in the request body.

searchCriteria

SearchEmployee | null

Optional filter object. When null or omitted the full active employee list is returned.

Employee records include: IdEmployee, FirstName, LastName, FullName, Location, ContactNumber, Email, IsActive.

`GET /api/v1/operations/filtered-suppliers`

Returns a filtered list of suppliers. Accepts an optional SearchSupplier body.

searchCriteria

SearchSupplier | null

Optional filter criteria. When null or omitted the full active supplier list is returned.

Supplier records include: IdSupplier, IdThirdSupplier, NameSupplier, CategorySupplier, Region, Country, Contact, IsActive.

`GET /api/v1/operations/categories`

Returns the product category definitions for the tenant. Used to populate category selectors in the UI and to group transactions in reports.

`GET /api/v1/operations/sku-definitions`

Returns the SKU structure definitions configured for the tenant. Each definition specifies how a unit of a product is packaged, weighed, and labeled.

Transaction Management

`POST /api/v1/operations/create-trx`

Creates a new harvest or productivity transaction. A transaction header is created along with its associated details, products, attributes, and initial state records in a single atomic operation.

trxPrefix

string

required

Short prefix code that classifies the transaction type. See the note below for prefix conventions.

descr

string

Human-readable description of the transaction.

username

string

required

Username of the employee recording the transaction.

location

string

Farm location or field identifier where the activity took place.

trxAttributes

TrxAttributesDTO[]

Key-value attribute list for extended transaction metadata (e.g. lot number, harvest batch).

trxProducts

TrxProductsDTO[]

Products involved in the transaction, each referencing a MasterProduct or variety.

trxStates

TrxStatesDTO

required

Initial workflow state record for the transaction.

trxDetails

TrxDetailsDTO[]

required

Line items for the transaction — quantity, unit, employee, supplier references, etc.

The TrxPrefix field drives downstream reporting and state-machine routing. Agree on prefix codes with your tenant configuration before creating transactions in production. A common example is PRDLBR for productivity-labor transactions, which records hours worked per employee against a specific herb variety.

`PATCH /api/v1/operations/{idTrxHeader}`

Partially updates an existing transaction’s details, products, attributes, or state. Only the supplied collections are updated; omitted collections are left unchanged.

idTrxHeader

long

required

The numeric primary key of the TrxHeader record to update.

trxAttributes

TrxAttributesDTO[]

Replacement attribute records. Supplying an empty array clears all attributes.

trxProducts

TrxProductsDTO[]

Replacement product lines.

trxStates

TrxStatesDTO | null

New state to apply to the transaction. null leaves the state unchanged.

trxDetails

TrxDetailsDTO[]

Replacement detail lines.

`POST /api/v1/operations/getTrx`

Searches and returns transactions matching the provided criteria. Accepts a SearchTrx body that can filter by prefix, date range, status, employee, supplier, or any combination thereof.

searchTrx

SearchTrx

required

Filter object specifying the transaction query criteria.

Integration Execution

`POST /api/v1/integrations/exec-api`

Executes an outbound HTTP call described by the GenericApiDTO payload. This endpoint is the runtime entry point for the integration engine: it builds the outbound HTTP request from the supplied target URL and operation, calls the configured endpoint, and returns the result.

UrlEndPoint

string

required

The full target URL that the integration engine will call.

Operation

string

required

The HTTP method to use when calling the target URL (e.g. GET, POST, PUT).

Headers

object | null

Optional dictionary of HTTP header key-value pairs to include in the outbound request.

Parameters

object | null

Optional dictionary of query string parameters to append to the target URL.

Body

object | null

Optional request body to send with the outbound HTTP call.

Status	Condition
`200 OK`	Rule executed and response returned.
`400 Bad Request`	`UrlEndPoint` or `Operation` is missing or the payload is malformed.
`401 Unauthorized`	Caller is not authenticated.
`403 Forbidden`	Caller does not have permission to execute this rule.
`404 Not Found`	The target endpoint could not be resolved or the requested resource was not found.
`409 Conflict`	Integration call succeeded but produced a conflict state.
`500 Internal Server Error`	Unexpected error during rule execution.

Transaction DTO Reference

TrxCreateDTO — full field list

public sealed class TrxCreateDTO
{
    public required string            TrxPrefix     { get; set; }
    public          string            Descr         { get; set; } = string.Empty;
    public required string            Username      { get; set; }
    public          string?           Location      { get; set; }
    public          List<TrxAttributesDTO> TrxAttributes { get; set; } = new();
    public          List<TrxProductsDTO>   TrxProducts   { get; set; } = new();
    public required TrxStatesDTO      TrxStates     { get; set; }
    public required List<TrxDetailsDTO>    TrxDetails    { get; set; }
}

TrxUpdateDTO — full field list

public sealed class TrxUpdateDTO
{
    public List<TrxAttributesDTO> TrxAttributes { get; set; } = new();
    public List<TrxProductsDTO>   TrxProducts   { get; set; } = new();
    public TrxStatesDTO?          TrxStates     { get; set; }
    public List<TrxDetailsDTO>    TrxDetails    { get; set; } = new();
}

Layer Structure

GSMOperations follows the same layered architecture as all other GSM microservices:

Layer	Responsibility
`GSMOperations.Api`	HTTP controllers, Swagger, middleware pipeline
`GSMOperations.Business`	Service implementations for all domain operations
`GSMOperations.Abstractions`	Interfaces for DI/DIP across layers
`GSMOperations.Entities`	DTOs, models, and search request objects
`GSMOperations.DataAccess`	EF Core entities (`Employee`, `Supplier`, etc.) and DbContexts
`GSMOperations.Infrastructure`	Repository implementations and external call handling
`GSMOperations.Tenant`	`TenantContext`, tenant middleware, header/claim resolution

Overview

Getting Started

Multi-Tenancy

Services

Frontend

Deployment

GSMOperations: Agricultural Data and Transactions Service

Domain Entities

Employee

Supplier

MasterProduct (Herb)

MasterVariety

Category

SKU Definition

TrxHeader

TrxDetail / TrxProduct / TrxAttribute / TrxStates

Endpoints

Reference Data

`GET /api/v1/operations/parameters`

`GET /api/v1/operations/master-products`

`GET /api/v1/operations/filtered-employees`

`GET /api/v1/operations/filtered-suppliers`

`GET /api/v1/operations/categories`

`GET /api/v1/operations/sku-definitions`

Transaction Management

`POST /api/v1/operations/create-trx`

`PATCH /api/v1/operations/{idTrxHeader}`

`POST /api/v1/operations/getTrx`

Integration Execution

`POST /api/v1/integrations/exec-api`

Transaction DTO Reference

Layer Structure

Build docs developers (and LLMs) love

Overview

Getting Started

Multi-Tenancy

Services

Frontend

Deployment

Documentation Index

​Domain Entities

Employee

Supplier

MasterProduct (Herb)

MasterVariety

Category

SKU Definition

TrxHeader

TrxDetail / TrxProduct / TrxAttribute / TrxStates

​Endpoints

​Reference Data

​GET /api/v1/operations/parameters

​GET /api/v1/operations/master-products

​GET /api/v1/operations/filtered-employees

​GET /api/v1/operations/filtered-suppliers

​GET /api/v1/operations/categories

​GET /api/v1/operations/sku-definitions

​Transaction Management

​POST /api/v1/operations/create-trx

​PATCH /api/v1/operations/{idTrxHeader}

​POST /api/v1/operations/getTrx

​Integration Execution

​POST /api/v1/integrations/exec-api

​Transaction DTO Reference

​Layer Structure

Build docs developers (and LLMs) love

Domain Entities

Endpoints

Reference Data

`GET /api/v1/operations/parameters`

`GET /api/v1/operations/master-products`

`GET /api/v1/operations/filtered-employees`

`GET /api/v1/operations/filtered-suppliers`

`GET /api/v1/operations/categories`

`GET /api/v1/operations/sku-definitions`

Transaction Management

`POST /api/v1/operations/create-trx`

`PATCH /api/v1/operations/{idTrxHeader}`

`POST /api/v1/operations/getTrx`

Integration Execution

`POST /api/v1/integrations/exec-api`

Transaction DTO Reference

Layer Structure