Why API Templates Don't Work on Business Central Custom API Pages

 If you've ever tried to set up an API template for a custom API page in Business Central and wondered why nothing seems to apply, you're not alone. The Microsoft documentation mentions that API templates only work with a specific list of standard pages, but it doesn't really explain why. That's what this post is about.

What Are API Templates?

API templates let you pre-populate fields on new records created via a POST call to a BC API. The idea is simple: when someone creates a record through the API and doesn't supply every field, the template fills in the blanks.

 

You set them up in API Setup page, pick a Table/Page ID and a Template Code from your Configuration Templates, and optionally add conditions. Done or so you'd think.

 

The catch is in the docs:

 

API templates can only be set up with the following API pages: contacts, countriesRegions, currencies, customers, employees, itemCategories, paymentMethods, paymentTerms, shipmentMethods, unitsOfMeasure, and vendors.

 

 

API Pages That Support Templates (Out of the Box)
contacts
countriesRegions
currencies
customers
employees
itemCategories
paymentMethods
paymentTerms
shipmentMethods
unitsOfMeasure
vendors

Why Only Those Pages?

Microsoft's docs don't explain the reason, but the answer is in the code.

 

Every one of those supported pages calls a specific function in the OnInsertRecord trigger:

 

GraphMgtGeneralTools.ProcessNewRecordFromAPI(CustomerRecordRef, TempFieldSet, CurrentDateTime());

 

This is the function that actually looks up your API Setup configuration and applies the template values. Without it, the framework has no hook to do anything. The template gets ignored completely.

 

Here's the full OnInsertRecord from the standard Customer API page so you can see exactly how it's wired up:

 

trigger OnInsertRecord(BelowxRec: Boolean): Boolean

var

Customer: Record Customer;

CustomerRecordRef: RecordRef;

begin

if Rec.Name = '' then

Error(NotProvidedCustomerNameErr);

Customer.SetRange("No.", Rec."No.");

if not Customer.IsEmpty() then

Rec.Insert();

Rec.Insert(true);

CustomerRecordRef.GetTable(Rec);

GraphMgtGeneralTools.ProcessNewRecordFromAPI(CustomerRecordRef, TempFieldSet, CurrentDateTime());

CustomerRecordRef.SetTable(Rec);

Rec.Modify(true);

SetCalculatedFields();

exit(false);

end;

 

The key steps are:

1.    Insert the record first (so it exists in the DB)

2.    Get a RecordRef from it

3.    Call ProcessNewRecordFromAPI, this is where the template lookup happens

4.    Set the record back from the RecordRef so updated values come through

5.    Modify the record to save everything

 

Custom API pages and the Resource API page don't have this plumbing, so templates never apply.

Seeing the Problem in Action

Let's prove this with the Resource API page. First, create a simple Configuration Template for Resources, say, one that sets a default Base Unit of Measure to HOUR.

 

Go to API Setup, add a new line, pick the Resource table or API page, and assign your template. Looks fine.

Now build Custom API Page from Scratch

page 50200 "My Custom Resource API"

{

PageType = API;

APIPublisher = 'mohana';

APIGroup = 'ap';

APIVersion = 'v2.0';

EntityName = 'resource';

EntitySetName = 'resources';

SourceTable = Resource;

ODataKeyFields = SystemId;

InsertAllowed = true;

DeleteAllowed = false;

ModifyAllowed = true;

layout

{

area(Content)

{

repeater(Group)

{

field(id; Rec.SystemId) { }

field(number; Rec."No.") { }

field(displayName; Rec.Name) { }

field(baseUnitOfMeasure; Rec."Base Unit of Measure") { }

field(type; Rec.Type) { }

}

}

}

}

 

Now POST a new resource via the API without specifying Base Unit of Measure:

 

POST /api/v2.0/companies({id})/resources

{

"number": "RES-TEST-01",

"displayName": "Test Resource"

}

 

Check the record that gets created. The Base Unit of Measure field is empty. The template did nothing.

That's because the Resource API page's OnInsertRecord has no ProcessNewRecordFromAPI code.

The Fix: Add the Missing code

page 50200 "My Custom Resource API"

{

PageType = API;

APIPublisher = 'mohana';

APIGroup = 'ap';

APIVersion = 'v2.0';

EntityName = 'resource';

EntitySetName = 'resources';

SourceTable = Resource;

ODataKeyFields = SystemId;

InsertAllowed = true;

DeleteAllowed = false;

ModifyAllowed = true;

layout

{

area(Content)

{

repeater(Group)

{

field(id; Rec.SystemId) { }

field(number; Rec."No.") { }

field(displayName; Rec.Name) { }

field(baseUnitOfMeasure; Rec."Base Unit of Measure") { }

field(type; Rec.Type) { }

}

}

}

var

GraphMgtGeneralTools: Codeunit "Graph Mgt - General Tools";

TempFieldSet: Record 2000000041 temporary;

trigger OnInsertRecord(BelowxRec: Boolean): Boolean

var

ResourceRecordRef: RecordRef;

begin

if Rec.Name = '' then

Error('Resource display name is required.');

Rec.Insert(true);

ResourceRecordRef.GetTable(Rec);

GraphMgtGeneralTools.ProcessNewRecordFromAPI(

ResourceRecordRef, TempFieldSet, CurrentDateTime());

ResourceRecordRef.SetTable(Rec);

Rec.Modify(true);

exit(false);

end;

}

 

With the extension published, run the same POST call again:

 

POST /api/v2.0/companies({id})/resources

{

"number": "RES-TEST-02",

"displayName": "Test Resource 2"

}

 

This time, open the resource record. You'll see Base Unit of Measure is populated with HOUR from the template, even though you didn't pass it in the POST body.

 

The template is working exactly as it should. The only difference is the three lines of code that hook into the template engine.

The TempFieldSet Variable

TempFieldSet is a temporary record based on the Field system table (table 2000000041). The ProcessNewRecordFromAPI function uses it to track which fields were explicitly set in the API call (as opposed to defaulted). This is how it knows which fields to leave alone and which to fill in from the template.

 

BC does not populate TempFieldSet automatically. You have to register each field manually by calling RegisterFieldSet from the OnValidate trigger of every field on your API page. If you skip this, ProcessNewRecordFromAPI has no record of which fields the caller actually sent, and it will treat all of them as update, meaning the template could overwrite values the API caller explicitly passed in.

 

Here's the pattern you need on every field:

 

field(type; Rec."Contact Type")

{

Caption = 'Type';

trigger OnValidate()

begin

RegisterFieldSet(Rec.FieldNo("Contact Type"));

end;

}

 

And the RegisterFieldSet procedure itself:

 

local procedure RegisterFieldSet(FieldNo: Integer)

begin

if TempFieldSet.Get(Database::Customer, FieldNo) then

exit;

TempFieldSet.Init();

TempFieldSet.TableNo := Database::Customer;

TempFieldSet.Validate("No.", FieldNo);

TempFieldSet.Insert(true);

end;

 

The Get check at the top prevents duplicate entries if the same field gets validated more than once. Every field you expose on the API page needs its own OnValidate trigger calling this procedure. If you miss a field, the template will overwrite whatever the caller sent for that field.

What If You Pass a Value That's Also in the Template?

The API caller always wins. ProcessNewRecordFromAPI only applies a template value if that field is not already in TempFieldSet. Since every field you explicitly send in the POST body gets tracked there, the function simply skips those fields when applying the template.

 

So if your template sets Type to Machine but your POST includes "type": "Person", the record gets Machine without TempFieldSet.

If your template sets Type to Machine but your POST includes "type": "Person", the record gets Person with TempFieldSet.

The template value is ignored for that field.

This matches what the Microsoft docs say about template ordering too:

 

Field values defined in the template are only applied to fields that have not already had a value defined, either explicitly in the API, or in a previously applied template in the order.

 

The same rule applies when you have multiple templates stacked in API Setup with different order numbers. The first template to set a field wins, and any later templates skip it.

 

Priority	Source	Wins over
1 (highest)	Explicit API value	Everything
2	Earlier template (lower Order #)	Later templates
3 (lowest)	Later template (higher Order #)	Nothing

Testing Your MCP Connection with Real Business Central Questions and Best Practices (BLOG 4 OF 4)

 Validating Your BC MCP Setup with Real-World Queries

Introduction

Your BcMCPProxy is built, Claude Desktop is configured, and the BC MCP Server is live. Now let’s put it all to the test.

In this final post, we go beyond simple data lookups. The real power of connecting an AI agent to Business Central is not just reading records. It is asking business questions in plain English and getting visual, actionable answers. We will walk through two scenarios that demonstrate exactly that, followed by best practices for working with AI agents.

Scenario 1: Project Budget vs. Actual Analysis

This is where things get interesting. Instead of opening BC, navigating to project ledger entries, exporting to Excel, and building a chart manually, you just ask.

Prompt

"I want to see budget vs actual for all Projects

 with a nice graphic view"

What Happens Behind the Scenes

Claude does not just make one API call. It thinks through the problem and executes multiple steps:

1.    Claude identifies that it needs project data with budget and actual figures. It calls the BC MCP Server to read the Project API page.

2.    It retrieves budget amounts and actual costs for all projects. If the data spans multiple API pages (project tasks, project planning lines, project ledger entries), Claude calls each one as needed.

3.    Claude then generates an interactive chart, typically a grouped bar chart, comparing budget vs. actual for each project side by side.

4.    The chart is rendered as a visual artifact directly inside Claude Desktop. No Excel export. No copy-paste. Just ask and see.

✅ Setup Note For this scenario, I created a custom API page in Business Central that exposes the Job Planning Lines table with all the relevant budget and actual fields. The standard BC APIs do not include project planning data out of the box, so a custom API page was needed to give the agent access to this information. This is a common pattern: if the data you want is not available through standard APIs, build a custom API page, add it to your MCP configuration, and the agent can use it immediately.

Why This Matters

Think about how long this takes the traditional way. Open BC, navigate to the right page, apply filters, export to Excel, format the data, build a pivot chart, adjust colors and labels. That is 15 to 30 minutes of work, depending on how many projects you have.

With MCP, you type one sentence and get a visual answer in seconds. The agent handles all the API calls, data shaping, and visualization for you.

Expected result: A bar chart showing budget vs. actual cost for every project in your BC environment along with total budget, actual cost, remaining budget and budget utilization.

✅ Pro Tip You can refine the prompt to focus on specific projects or add more detail. For example: "Show me budget vs actual for projects J00010 and J00030 with a breakdown by project task." The more specific your prompt, the more targeted the output.

 

✅ Prompt Refinement If the initial chart does not look quite right, just tell Claude what to change. "Make it a horizontal bar chart instead" or "Add percentage variance labels" or "Only show projects that are over budget." The agent iterates on the visualization without you touching any code.

Scenario 2: Available Inventory Overview

Inventory visibility is one of those things that everyone needs but nobody wants to build reports for. Let’s skip the report.

Prompt

"Show me available inventory in a nice chart"

What Happens Behind the Scenes

1.    Claude calls the BC MCP Server to read the Item API page and retrieves all items with their inventory quantities.

2.    It filters for items that actually have inventory on hand (skipping zero-stock items to keep the chart clean).

3.    Claude generates a visual chart. Depending on the number of items, it might use a bar chart for a smaller catalog or a treemap/bubble chart for a larger one.

4.    The chart is rendered as an interactive artifact in Claude Desktop, with item numbers, descriptions, and quantities.

Why This Matters

This is a question that gets asked in every warehouse meeting, every sales call, and every planning session. Instead of logging into BC, navigating to the item list, sorting by inventory, and maybe exporting it for a visual, you just ask.

And because it is conversational, you can immediately follow up: "Which items are below their reorder point?" or "Show me just the items in the FINISHED category" or "What is the total inventory value?" The agent keeps the context and builds on the previous answer.

Expected result: A visual chart showing available inventory quantities across your items. Items with the highest stock levels are immediately visible. Zero-stock items are excluded for clarity.

✅ Taking It Further Try chaining requests: "Show me available inventory, then highlight items that have not had any sales in the last 90 days." Claude can cross-reference inventory data with sales data across multiple API calls to surface slow-moving stock. This kind of ad-hoc analysis used to require a dedicated report. Now it is a conversation.

The Bigger Picture

These two scenarios are just the beginning. The pattern is always the same: ask a business question in plain English, and the AI agent figures out which BC API pages to call, fetches the data, and presents it visually.

Here are a few more ideas to try once your setup is working:

•        "Show me a trend of sales order totals by month for the last 12 months."

•        "Which customers have overdue balances? Show me a breakdown by aging bucket."

•        "Compare actual vs. budget for GL accounts in the 6000 range this quarter."

•        "What are our top 10 selling items by revenue this year? Show me a chart."

Each of these would traditionally require navigation, filtering, exporting, and charting. With MCP, they are one-line prompts.

 

Best Practices

Security

•        Least privilege: Start with a read-only MCP configuration. Only enable write operations after thorough testing.

•        No secrets in config: No passwords or secrets are stored. The proxy uses Azure’s delegated auth flow.

•        Separate configurations: Create purpose-specific configurations (e.g., Finance-ReadOnly, Sales-ReadWrite).

•        Audit access: Review who has the MCP - ADMIN permission set in BC.

Working with Agents

•        Be precise: Agents work best with specific, clear requests. “Show me customers” is good; “Show me the top 10 customers sorted by balance” is better.

•        Request complete data: When you need all records, say so explicitly and instruct the agent not to use the top parameter.

•        Understand tool calls: Each MCP tool call is a separate API request. Complex queries may take a few seconds.

•        Review before approving: For sensitive operations, the agent will ask for confirmation. This is by design.

Maintenance

•        Stay current: The BC MCP Server is in public preview and may change. Watch the Microsoft Learn documentation for updates.

•        Expand over time: As BC evolves, new API pages may become available. Add them to your MCP configuration to expand agent capabilities.

•        Test after updates: If something breaks after a BC update, re-check Feature Management and MCP configuration.

Conclusion

Over these four posts, we have gone from understanding what AI agents and MCP are, through enabling the BC MCP Server and configuring it, to building a proxy executable and testing it with real business questions.

The key takeaway is this: the value is not in reading individual records. It is in asking business questions and getting visual, actionable answers in seconds. Budget vs. actual comparisons, inventory overviews, trend analysis. All of this is now a conversation, not a report-building exercise.

The BcMCPProxy is a temporary bridge. Microsoft will likely provide direct MCP client support in future releases. But it works today and demonstrates the enormous potential of agentic AI in the Business Central ecosystem.

The future is agentic. Let’s build it.

Blog Series Navigation

   Blog 1: Understanding AI Agents and MCP

   Blog 2: The Business Central MCP Server

   Blog 3: Building BcMCPProxy.exe and Connecting to Claude Desktop

▶ Blog 4: Testing Scenarios and Best Practices (You are here)