This is an automated email from the ASF dual-hosted git repository. diveshdut pushed a commit to branch OFBIZ-13367-agent-skills-guidance in repository https://gitbox.apache.org/repos/asf/ofbiz-plugins.git
commit 99d846b18534644bfda4795f690abb8974bdd3f4 Author: diveshdut <[email protected]> AuthorDate: Wed May 20 10:19:19 2026 +0530 OFBIZ-13367 Add coding agent OFBiz guidance Add a few more instructions so coding agents work better with OFBiz coding guidelines. --- ai-agent-skills/manage-groovy/SKILL.md | 2 ++ ai-agent-skills/manage-services/SKILL.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/ai-agent-skills/manage-groovy/SKILL.md b/ai-agent-skills/manage-groovy/SKILL.md index 474d082fe..3d580813f 100644 --- a/ai-agent-skills/manage-groovy/SKILL.md +++ b/ai-agent-skills/manage-groovy/SKILL.md @@ -74,6 +74,7 @@ Implement business logic, complex data transformations, and data preparation scr // Fetch one GenericValue product = from("Product").where("productId", productId).queryOne() ``` +- **Domain Helpers First**: Before writing direct entity queries, look for existing OFBiz or component helper methods that encode business semantics. Direct or batched entity queries are still appropriate for enrichment, projections, or avoiding N+1 lookups once the helper behavior is understood. - **Advanced Querying**: Use `EntityCondition` for complex filters: ```groovy import org.apache.ofbiz.entity.condition.EntityCondition @@ -114,6 +115,7 @@ String newId = result.newProductId - **Direct SQL**: **NEVER** write raw JDBC/SQL in Groovy. Always use the Entity Engine (DSL or Delegator). - **Hardcoding Strings**: Hardcoding error messages instead of UI Labels, or hardcoding IDs (like `partyId`). - **Legacy Entity APIs**: **DO NOT** use legacy Delegator APIs like `delegator.findList(...)`. Always use the modern Entity DSL `from("Entity").where(...).queryList()`. +- **Custom Conversion Helpers**: Avoid local helper methods for conversions that OFBiz already provides. Prefer existing utilities such as `ObjectType.simpleTypeOrObjectConvert(...)` at service/input boundaries and `UtilMisc.toIntegerObject(...)` for integer conversion. ### Database Querying: - **Unconstrained Queries**: **NEVER** query a table without a `.where(...)` condition unless explicitly fetching a tiny bounded list (like enumerated `StatusItem`). diff --git a/ai-agent-skills/manage-services/SKILL.md b/ai-agent-skills/manage-services/SKILL.md index b34236bea..baaf97037 100644 --- a/ai-agent-skills/manage-services/SKILL.md +++ b/ai-agent-skills/manage-services/SKILL.md @@ -49,6 +49,7 @@ Define and implement business logic as reusable, transactional, and securely enf ### 2. Service Definition & Registration - **Naming**: Use `verbNoun` format for all service names (e.g., `updateExample`, `createOrder`). - **In/Out Parameters**: Use `<attribute name="..." mode="IN|OUT|INOUT" type="..." optional="true|false"/>`. NEVER bypass attribute validation by casually omitting them or making them wrongly optional. +- **Native Contract Types**: Backend/data services should keep OFBiz-native service types such as `Timestamp` and `BigDecimal` in IN/OUT attributes and returned maps. - **Auth & Security**: Set `auth="true"` for protected services. ALWAYS implement permission checks (e.g., `<permission-service>`). - **Export & REST**: Set `export="true"` to expose the service to external callers. Set `action="GET|POST|PUT|DELETE"` to automatically export the service as a REST API endpoint. - **Service Overrides**: Use `<implements service="..." />` to inherit attributes from an existing service. @@ -76,6 +77,7 @@ Define and implement business logic as reusable, transactional, and securely enf ### 1. View vs. Business Logic Separation - Services must remain completely agnostic of the View layer. NEVER put HTML encoding, FreeMarker syntax, or UI formatting into a core backend service. +- Do not stringify dates, timestamps, quantities, or money in backend data services unless the service is explicitly a presentation/export formatting service. - Error Messages: Use properties from `uiLabelMap` for user-facing error messages to support internationalization. ### 2. Error Handling Integrity
