How to Debug Epicor Functions (Logging, Testing, Maintenance)
how to debug epicor functions
Also searched as
- epicor function logging
- epicor functions maintenance
- epicor function maintenance
Short answer
Debug an Epicor Function by testing it in isolation with known input, writing explicit log entries from a code block, and reading the server trace log for the failing step. Keep libraries maintainable by naming functions clearly, documenting parameters, and managing security and versions in Epicor Functions Maintenance.
Applies to: Epicor Kinetic 2021 and later with Epicor Functions; behaviour of the test tool and tracing options varies slightly by release
How to debug an Epicor Function
- 1Open Epicor Functions Maintenance, find the library and function, and confirm the function is saved and set to a state you can call.
- 2Reproduce the failure with a small known input: use the function's test capability if your release has it, or call it through REST with a fixed payload.
- 3Add log lines at key steps from a code block, for example before and after each widget that touches data, with the variable values.
- 4Turn on Tracing Options in the Kinetic client, run the scenario once, and open the server trace log to read the function and BPM entries.
- 5Narrow down which widget fails by disabling downstream widgets or returning early with a fixed value.
- 6Check the input and output parameter types, because a mismatch in type or nullability is a common cause of runtime failures.
- 7Fix, save, and retest with the same input; then test an edge input (empty, null, large) before releasing.
- 8Remove or reduce verbose logging once fixed, so the trace log is not flooded in production.
Writing log entries
The simplest debugging aid is a log line you wrote yourself. In a Custom Code block you can write an entry to the Epicor diagnostic log, which appears in the server trace output when tracing is enabled. Include the function name and the value you care about so entries are searchable.
Log decisions, not noise: which branch ran, how many rows a query returned, and the key identifiers. Never log passwords, tokens or personal data, because trace logs are often copied to forums and tickets.
// In a Custom Code block
Ice.Diagnostics.Log.WriteEntry("MyLib.CalcFreight start, order=" + orderNum);
Ice.Diagnostics.Log.WriteEntry("MyLib.CalcFreight rows=" + rows.Count);Testing in isolation
A function is easiest to debug when it is called alone. Calling it through its REST endpoint with a fixed JSON body removes the BPM, the form and the user session from the equation. If it works alone but fails when called from a directive, the problem is in what the directive passes in.
Keep a small set of test payloads with the library documentation: a normal case, an empty case and a bad case. When you change a function months later, replaying those cases is cheaper than reasoning about what might break.
Maintaining function libraries
Functions are grouped into libraries, and each library has its own security and its own set of functions. Treat a library like a small codebase: one clear purpose, consistent names, and descriptions on each function stating what it needs and returns. Use Epicor Functions Maintenance to review, enable and control who may call them.
Before an upgrade, export your libraries and keep them in source control. After an upgrade, retest the functions that touch standard business objects, since those objects can change shape between releases.
Try it here, free
Epicor Function Library Design Template
A design document for an Epicor function: signature, inputs, outputs, logic notes, security, test cases and sign off.
Common pitfalls
- !Debugging only through the calling BPM so you cannot tell whose fault the failure is.
- !Leaving verbose logging on in production and filling the trace log.
- !Changing a function that many directives call without a test payload set.
- !Granting a library to everyone by default, including functions that update data.
- !Logging sensitive values to the trace log.
How an ERP-grounded AI assistant handles this
An assistant grounded in your environment can list which functions exist, which directives call them, and what the recent trace entries say, then propose a minimal fix for a developer to review. SyteRay-style agents do this for SyteLine, and the same pattern applies to Epicor through ERPray and a custom build. The changes remain human-approved.
Frequently asked questions
Where do Epicor Function log entries go?
Entries written with the Epicor diagnostic log appear in the server trace log when tracing is enabled through the Tracing Options. Enable tracing for the session you test with, reproduce the issue once, then read the trace output.
Is there a debugger for Epicor Functions?
There is no step-through debugger you can attach in the browser. Developers rely on isolated test calls, log lines and the trace log, and some use a separate development environment for code-heavy functions.
What is Epicor Functions Maintenance used for?
It is where you create and manage function libraries and their functions: definitions, widgets, parameters, state and security. It is the main screen for reviewing what is deployed and who may call it.
How do I test an Epicor Function without a BPM?
Call it through its REST endpoint with a fixed JSON body, or use a test option in the designer if your version provides one. Isolated calls separate function bugs from directive or form bugs.
Related
How to create and call an Epicor Function
Open Function Studio from the main menu (Customization > Function Studio) or from inside a BPM designer's Call Context widget, define a Library and Function with typed inputs/outputs, write the logic in the C# widget, then compile and test with the built-in test harness before calling it from a BPM directive, a dashboard, or another function.
AdvancedEpicor Function Examples: Update a Table, Call It, Schedule It
An Epicor Function takes typed inputs, runs widgets or code, and returns outputs. You can update data through a business object call or the table widgets, call the function from a BPM, from Application Studio or over REST, and schedule it through an external scheduler or a task agent pattern that fits your release.
Error fixFixing Epicor BusinessObjectException: BPM Directive Errors
A BusinessObjectException that says "A Business Process Management (BPM) directive has raised the following error" means a directive on that business object stopped the transaction, either deliberately via a Raise Exception widget or accidentally via an unhandled .NET error in Custom Code. Expand the InnerException on the error dialog to see the real message and the directive name, then open BPM Designer for that object and method to find the widget that fired.
How-toEpicor BPM InfoMessage, Message Box, Throw Exception and Hold
In Epicor Kinetic BPM, a message to the user is either a non-blocking InfoMessage (a Show Message widget, or PublishInfoMessage in custom code) or a blocking exception (a Raise Exception widget, or a thrown BLException) that cancels the save. A hold is not a separate message type: you set the relevant hold flag on the record in a Data or Method directive and optionally tell the user why.
How-toFixing a Slow Epicor BAQ (Business Activity Query)
A slow BAQ in Epicor is usually caused by unindexed join columns, a subquery or calculated field forcing a table scan, or the BAQ pulling far more rows than the dashboard actually displays before filtering client-side. Fix it by reading the SQL Server execution plan Epicor generates, moving filters into the BAQ criteria instead of the dashboard filter panel, and replacing subqueries with joins where possible.
How-toEpicor MRP Runs but Generates No Suggestions
When Epicor's MRP process completes without a job or purchase suggestion for a part you expect one for, the cause is almost always the part's own configuration (Part Class Type, Make Direct, Non-MRP flag, planning Time Fence) or the demand not being linked in a way MRP recognizes, not a defect in the MRP engine. Work through the part's Planning tab, its safety stock and lead time setup, and the demand source (sales order line status, job material requirement) before assuming the run itself failed.
AI for ERPAI for Epicor Kinetic, Beyond What Prism Covers
Add AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.
AI for ERPPrivate AI for Epicor Kinetic Cloud, Outside the Multi-Tenant Boundary
Run a private LLM on Epicor Kinetic private cloud or Kinetic Cloud data via BAQs, REST v2 and Data Fabric, keeping sensitive manufacturing data off shared AI.
Stuck on Epicor Kinetic?
Talk to engineers who work inside Epicor Kinetic every week, and who build private AI that answers these questions from your own ERP data.
Keep exploring
Free tools
- Epicor Function Library Design TemplateA design document for an Epicor function: signature, inputs, outputs, logic notes, security, test cases and sign off.
- Epicor Kinetic Customization Change Request Form TemplateA fill-in change request form for Application Studio customizations, BPM directives and Epicor Functions, with test and rollback sections.
- Epicor Kinetic Upgrade ChecklistA phase-by-phase upgrade checklist covering inventory, testing, integrations, cutover and rollback for Epicor Kinetic.
ERP fixes and how-tos
- Epicor Function Examples: Update a Table, Call It, Schedule ItWorked Epicor Kinetic Function examples: updating a table, calling a function from a BPM, Application Studio or REST, and scheduling a recurring run.
- Epicor Function Custom Code: C# Signature, Parameters and Calling ItWrite custom C# code in Epicor Functions: signature, request and response parameters, libraries, calling from BPM and Application Studio, with working examples.
- How to create and call an Epicor FunctionHow to create Epicor Functions in Function Studio: define inputs and outputs, write the C# widget, test, then call the function from a BPM directive.
AI on your ERP
- Private AI for Epicor Kinetic Cloud, Outside the Multi-Tenant BoundaryRun a private LLM on Epicor Kinetic private cloud or Kinetic Cloud data via BAQs, REST v2 and Data Fabric, keeping sensitive manufacturing data off shared AI.
- AI for Epicor Kinetic Quality: Non-Conformances, CAPA, Inspection and TraceabilityAI for Epicor Kinetic quality: summarize non-conformances, find repeat defects, draft CAPA and trace lots, with audit-ready logs and on-prem deployment.
Integrations
- How to build an MCP server for Epicor KineticDesign a Model Context Protocol server for Epicor Kinetic: which read tools to expose, BAQ and REST v2 mapping, auth, stdio vs HTTP transport and audit logging.
- How to add AI agents to Epicor KineticHow to add AI agents to Epicor Kinetic: a tool layer over the REST v2 API and BAQs, MRP exception triage, PO expediting, and human approval before any write.