--- name: moqui-service-writer description: This skill should be used when users need to create, validate, or modify Moqui framework services, entities, and queries. It provides comprehensive guidance for writing correct Moqui XML definitions, following framework patterns and conventions. license: Complete terms in LICENSE.txt --- # Moqui Service Writer ## Overview This skill enables writing correct Moqui framework services, entities, and queries by providing comprehensive patterns, validation tools, and reference documentation. It helps developers follow Moqui conventions and avoid common pitfalls when working with the enterprise framework. ## Quick Start ### For New Moqui Development 1. **Generate service templates** using `scripts\/generate_service.py --interactive` 2. **Create entity definitions** using `assets\/entity_template.xml` as a starting point 3. **Validate XML files** with `scripts\/validate_service.py` and `scripts\/validate_entity.py` 4. **Format XML consistently** using `scripts\/format_moqui_xml.py` ### For Existing Moqui Projects 1. **Validate current files** to identify issues and improvements 2. **Reference patterns** in `references\/` for best practices 3. **Use templates** in `assets\/` for new components 4. **Apply consistent formatting** across all XML files ## Writing Services ### Service Creation Workflow #### Step 1: Choose Service Type Determine service purpose and select appropriate verb: - **create** - Create new records - **update** - Modify existing records - **find** - Search\/retrieve records - **get** - Retrieve single record - **delete** - Delete records - **process** - Custom business logic #### Step 2: Generate Template Use service generator: ```bash python3 scripts\/generate_service.py --interactive ``` Or generate specific types: ```bash python3 scripts\/generate_service.py --verb create --noun Product --type create ``` #### Step 3: Customize Service Edit the generated service following patterns in `references\/service_patterns.md`: - Add proper authentication levels - Define input\/output parameters - Implement business logic in actions - Add error handling and validation #### Step 4: Validate Service ```bash python3 scripts\/validate_service.py path\/to\/your\/service.xml ``` ### Common Service Patterns #### CRUD Services Use entity-auto services for standard operations: ```xml

<\/in-parameters> <\/out-parameters> <\/service> ``` #### Search Services Implement find services with filtering: ```xml

<\/in-parameters> <\/out-parameters>

<\/entity-find> <\/actions> <\/service> ``` #### Custom Business Logic Services Implement complex operations with proper error handling: **Follow Moqui Framework Transaction Patterns:** - **Default**: No transaction attribute (98.5% of framework services) - **Critical Operations**: Use `transaction="force-new"` for financial\/bulk operations - **Long-running**: Add `transaction-timeout` for operations > 5 minutes - **Avoid**: `transaction="cache"` (causes locking issues in framework) ```xml

<\/in-parameters>

<\/if> <\/if>

Order processed successfully<\/message> <\/actions> <\/service> ``` ```xml

<\/in-parameters>