Ir al contenido

API and Data Troubleshooting

Response protocols for mass extraction failures, OData network latency, and architectural constraints in Business Central.

0views

In our DevSecOps work ensuring the integrity of Data Pipelines, the integration between Business Central and Business Intelligence platforms can present bottlenecks and network impediments.

This document details the root causes of the most serious failures found and their definitive solutions based on the implemented architecture.

Incident 1: “A remote host caused a connection abort” (OData Timeout)

Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»

When attempting to update a historical dataset (e.g., more than 200,000 rows) from Power Query, Power BI Desktop, or via a Python script, the connection loads for several minutes and then suddenly aborts, returning the error: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).

This is a failure due to Resource Exhaustion in the NST (Navision Server Tier). It occurs when the target endpoint is not an optimized API (Query), but a standard page published as a Web Service (e.g., Page 38). When requesting thousands of rows to a web page, the Business Central server attempts to render visual components, execute triggers, and calculate complex subqueries (FlowFields) in the RAM for each row. When processing exceeds time limits (usually 10 or 15 minutes), the Azure load balancer cuts the HTTP connection for security reasons to prevent an ERP outage.

  1. Abandon Page-based Web Services: Remove any mass data consumption through page-type Web Services from the architecture.
  2. Developing Native APIs (Query): Migrating the request to an AL query object. By doing this, execution skips the interface layer and becomes a pure SQL statement, reducing response time from 15 minutes to less than 30 seconds.
  3. Pagination (External Scripts): If we use a language like Python for the ETL, we must ensure we respect and program the tracking of the @odata.nextLink token returned by the server, as Business Central imposes a maximum limit of rows per returned JSON page.

Incident 2: Inability to Create Subfolders in API Routes

Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»

During the development of a new API in AL, when attempting to create a logical hierarchy of departments by introducing a forward slash (/) in the API properties, the Visual Studio Code compiler throws a fatal error and blocks the generation of the .app file.

Faulty code example:

// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamiento
APIGroup = 'portelcore/departamentos/finanzas';

Microsoft Business Central's OData V4 generation engine has strictly hardcoded structural routes.

The server always and exclusively expects an immutable 3-tier model: {APIPublisher} / {APIGroup} / {APIVersion}

There is no technical capability or container-level permission to alter the HTTP orchestrator and add extra segments or “subfolders” to the Custom API URLs.

Adopt strict naming conventions (Naming Conventions).

Since it is not possible to create physical routes separated by /, we simulate the hierarchy using underscores (Snake_case) within the APIGroup or the APIPublisher.

  • Correct implementation (Logical Group):

    APIPublisher = 'portelcore';
    APIGroup = 'api_portelcore_finanzas_1';
    APIVersion = 'v1.0';

    OData Result: .../api/portelcore/api_portelcore_finanzas_1/v1.0/

  • Alternative implementation (Logical Publisher):

    APIPublisher = 'portelcore_finanzas';
    APIGroup = 'analitica';
    APIVersion = 'v1.0';

    OData Result: .../api/portelcore_finanzas/analitica/v1.0/

  • ✓ Performance: Total replacement of page-type services with objects Query API to avoid timeouts due to RAM overflow in the NST.
  • ✓ Routing Format: Strict compliance with the 3-level schema required by the AL compiler, employing Snake_Case for logical hierarchies.
  • ✓ Synchronization: Prior clearing of local client caches to force schema rediscovery after reconfiguration.